项目蓝图 shuguang1994/project-blueprint

Project Blueprint 🏗️

One command to make any project AI-agent-ready.
一键为新项目建立完整 AI 编程规范体系。

Topics ·

中文文档

这是什么？

Project Blueprint 是一个可复用的 AI 智能体技能，一句话就能把任何新项目变成 AI 就绪的代码库。它不是静态模板，而是一台自主发现引擎：扫描你的项目文件，智能归类依赖，再从一份收录 95 个组件的知识库里，动态拼装出定制化的 AGENTS.md、文档骨架、CI/CD 流水线和测试策略。

你只需要说一句：「Initialize this project's development standards」，剩下的交给智能体。

快速安装

Global (GitHub)
npx skills add shuguang1994/project-blueprint

China (Gitee mirror, no proxy needed)
npx skills add https://gitee.com/shuguang1994/project-blueprint.git

Update later
npx skills update project-blueprint

DeepSeek Harness（dsh）插件：

dsh plugin --profile web add 'github:shuguang1994/project-blueprint'

支持的智能体：Claude Code、Cursor、GitHub Copilot、Codex、Windsurf、Trae、OpenCode、DeepSeek Harness，以及另外 28 个以上。

为什么需要它

AGENTS.md 在 2026 年已是行业标准 —— 60,000 多个开源仓库在用，OpenAI、Google、Anthropic、Microsoft 联合推广。76% 的开发者使用 AI 编程助手（Stack Overflow 2025），但没有 AGENTS.md，AI 智能体就像「没做过入职培训的新人」——代码风格不统一、架构被破坏、CI 跑不过。

行业数据：Anthropic 的基准测试显示，AGENTS.md 能把错误模式的返工减少 40-60%。但手写一份高质量的 AGENTS.md 要花半天到一整天 —— 而且每开一个新项目都得重来一遍。
Project Blueprint 的思路：不用预设模板。自主扫描 → 智能分类 → 动态组装。你拿到的 AGENTS.md 反映的是项目真实的技术栈。而且它是唯一一个能从一句话生成 AGENTS.md + 文档骨架 + CI 流水线 + 测试策略 + Git 规范的工具。

核心能力

| 能力 | 说明 |
| 自主文件发现 | 扫描并分类 30+ 种文件模式——不用预设文件清单 |
| 项目结构识别 | 自动判断 monorepo、前后端两层/三层结构，还是单体项目 |
| Monorepo 嵌套 AGENTS.md | 根目录 AGENTS.md（全局约束 + 子项目索引）+ 每个包的 AGENTS.md（就近文件优先），前提是构建/清单文件 ≥2 个 |
| 依赖智能分类 | 三层：知识库精确匹配 → 29 条启发式规则 → 联网搜索 |
| 业务类型推断 | 两层启发式（结构 + 配置特征），覆盖 12 种业务类型 |
| 动态 AGENTS.md | 从 95 条组件知识库组装而成，不是套模板 |
| 模块表生成 | 读取真实源码目录，按文件模式推断职责，兜底走联网搜索 |
| 文档体系 | A/B/C/D/E 五级分类，按业务类型生成 |
| 测试策略 | 按阶段分层的策略，不硬塞示例文件 |
| 多 IDE 支持 | 自动生成 CLAUDE.md、.cursor/rules、copilot-instructions 等 |
| 厂商私有增强层 | 不止是面包屑：Cursor .mdc glob 激活、Claude Code 钩子/子代理骨架、Copilot 指令分层 |
| 增量模式 | 对已有项目只补缺口，绝不覆盖 |
| MCP 工具推荐 | 根据识别出的技术栈推荐 MCP 工具清单 + 组合，生成 docs/B/B-05-MCP工具清单.md，附安装命令（只出 MD，侵入性最小） |
| 自进化 | 生成的 AGENTS.md 内置自动维护规则——项目成长时同步更新模块表、技术栈和决策记录 |
| 渐进式步骤加载 | SKILL.md 瘦身为 ≤200 行的索引；步骤细节按需从 references/step-.md 加载 |
| 真实编码规范 | 初始化时写入基础编码规范（命名/结构/错误处理/日志/安全/性能 6 类），B-01 是实打实的 8 章文档，不是占位符 |
| AI 防错 | 内置 7 类 27 条 AI 常见错误知识库，初始化时注入核心规则，通过 BUG 反馈回路迭代 |
| 宪法与门禁成长 | 把元规则 + 6 步成长回路写进 AGENTS.md，项目的 AI 在工作过程中就能从宪法长出领域门禁 |
| 门禁注册表与统一入口 | scripts/gates.json 作为唯一事实来源 + verify. 统一入口；CI 的 gate job 内联（不用「记得追加」），每个 job 都自检运行时（command -v + 打印版本），运行时缺失第一行就报错 |
| 红线权威表 + 双向宪法审查 | 稳定 ID（RL-NN，只追加）+ docs/B/B-00-红线与门禁映射.md 作为唯一 source 引用；check-constitution 规则 A–E 双向审查——僵尸门禁 以及（规则 E）没有门禁的红线；表缺失时降级并说明未覆盖的风险，而不是悄悄变绿 |
| 文档契约与校验 | 文档状态头 / 编号 / 索引契约 + docs-check 脚本（错误阻断，警告不阻断） |
| AI 工作协议 | 7 步任务生命周期 + 证据标准 + DoD + 缺陷复盘模板 |
| 规格驱动开发（6 阶段） | specify → plan → tasks → checklist → implement → verify；规格清单可直接注册为门禁（source: spec#<change-id>） |
| 规格-代码漂移门禁 | 种子门禁检查依赖 ↔ AGENTS.md 技术栈行、模块表 ↔ 实际目录、门禁有效性，以及 测试框架 ↔ CI 测试步骤（drift-check.）；没有源码根目录时回退到顶层目录，并打印适用性裁定（原因/风险/结论），而不是静默跳过 |

生成内容

| 输出 | 说明 |
| AGENTS.md | 项目约定（受架构原则约束）；monorepo 中：全局约束 + 子项目索引 |
| /AGENTS.md | 当构建/清单文件 ≥2 个时，按包生成约定（monorepo：根 = 全局 + 索引，包 = 局部，就近文件优先） |
| docs/ | A/B/C/D/E 分类文档骨架 + README 维护指南（含 B-01-开发规范，真正的 8 章约定） |
| docs/B/B-00-红线与门禁映射.md | 红线权威表（唯一 source 引用）：稳定 RL-NN ID + 层级 + 归属门禁 + 无门禁原因；与 gates.json 一同生成 |
| .github/workflows/ci.yml | CI 流水线（自动适配语言 + 平台）；门禁 job 内联 + 运行时自校验；测试步骤按检测结果保留/移除（没有 --passWithNoTests 假绿开关） |
| .gitignore | 按语言整理的规则 |
| CHANGELOG.md | 版本日志（[Unreleased] 初始化占位，按 AGENTS.md 发布策略更新） |
| .husky/pre-commit | 提交前 lint 钩子（仅 JS/TS） |
| CLAUDE.md | Claude Code 厂商面包屑（基线） |
| .cursor/rules/project.mdc | Cursor 厂商面包屑（基线 + 私有增强层） |
| docs/B/B-03-测试指南.md | 测试策略（分层、时机、框架专属模式）；未生成 CI 测试步骤时，记录「有测试后补 CI 测试步骤」契约 |
| docs/B/B-05-MCP工具清单.md | MCP 工具清单 + 组合建议 + 安装命令（按需） |
| scripts/gates.json | 门禁注册表（唯一事实来源：source / level / stage / command；默认播种 2 个种子门禁；source 形如 AGENTS#RL-01@文档契约） |
| scripts/verify. | 统一门禁入口（自动选择宿主：Node / Python / make / shell；已提供可直接运行的 Python 与 Makefile 宿主 —— 绝不要引用你没有生成的宿主） |
| scripts/check-constitution. | 宪法自检（红线权限表 ↔ 门禁注册表，双向；规则 A / A' / B / C / D / E） |
| scripts/docs-check. | 文档一致性检查（编号 / 状态头 / 索引 / 归档冲突 + 大小；扫描范围自适应：遍历实际存在的 docs/ 子目录；错误块） |
| scripts/drift-check. | 漂移检查（依赖 ↔ 技术栈行 / 模块表 ↔ 实际目录 / 门禁有效性 / 测试框架 ↔ CI 测试步骤）—— 第 2 个种子门禁 spec-drift |
| docs/B/B-07-门禁与工作协议.md | 门禁增长循环 + 证据标准 + DoD（中大型项目按需启用） |

按需启用：小项目只配单个门禁 + 统一入口 —— 不要完整的门禁层或协议文档（保持精简，避免过度设计）。

自主发现引擎

Project Blueprint 不检查固定的文件清单。它扫描你的项目，发现一切。

依赖分类：3 层

所有检测到的依赖 ↓ 第 1 层：知识库精确匹配命中 95 条组件知识库 → 立即完成 ↓ 第 2 层：名称模式启发式 29 种模式覆盖 100+ 关键词 → 自动分类例如 winston → logging，antdv-next → ui，mysql2 → database ↓ 第 3 层：Web 搜索真正未知 → 实时搜索最新信息

技术栈覆盖范围

| 层 | 组件 |
| 语言（7） | TypeScript/JavaScript、Go、Python、Java、Rust、Ruby、PHP |
| 框架（15） | NestJS、Next.js、Vue 3、React、Express、FastAPI、Flask、Django、Gin、Spring Boot、SvelteKit、Nuxt 3、Laravel、Hono、uni-app |
| ORM（6） | Prisma、TypeORM、Drizzle、GORM、SQLAlchemy、JPA/Hibernate |
| CSS（5） | Tailwind CSS、CSS Modules、Scoped CSS、Styled Components、SCSS |
| UI 库（4） | Ant Design Vue、Element Plus、Naive UI、Vant |
| 测试（6） | Vitest、Jest、Pytest、Go testing、JUnit 5、Playwright |
| 代码检查（5） | ESLint、Prettier、Biome、Ruff、golangci-lint |
| 部署（5） | PM2、Docker、Vercel、Docker Compose、GitHub Pages |
| 数据库（2） | MySQL、PostgreSQL |
| AI/LLM（4） | LangChain / LangGraph、LlamaIndex、pgvector、Ollama / vLLM |
| IaC 与云原生（3） | Terraform、Helm、Kubernetes manifest（kubectl / kustomize） |
| 可观测性（3） | OpenTelemetry、Sentry、Prometheus + Grafana |
| 数据工程（2） | dbt、Airflow |
| 原生移动端（3） | Flutter、SwiftUI（Swift）、Jetpack Compose（Kotlin） |
| 合计 | 18 个二级章节 / 16 个技术栈维度，95 条组件条目（+ 状态 3、包管理 5、通用约定、12 种业务类型文档模式） |

Web 搜索兜底

每个维度都有网络搜索兜底——不只是语言/框架，还有 CSS、lint、包管理器、部署、UI 库、数据库和状态管理：

Unknown dep: @shadcn/ui not in knowledge base
→ Heuristic: contains "shadcn" + "ui" → dimension: ui
→ WebSearch: "shadcn/ui component library conventions 2026"
→ Extracts: registration patterns, theming, Tailwind integration
→ Writes into AGENTS.md

网络兜底覆盖两个阶段：生成（对未知依赖/模块做网络搜索）+ 编码（生成的 AGENTS.md 要求在写代码前，对照官方文档核实第三方库的 API/版本）。

独有创新

已通过网络搜索核实——现有 AGENTS.md 生成工具都没有实现这些。

| 创新点 | 说明 | 竞品情况 |
| 全生命周期生成 | 一句话 → AGENTS.md + 文档 + CI/CD + 测试策略 + Git 约定 | 竞品只生成 AGENTS.md |
| 自主发现引擎 | 三级分类（精确→启发式→网络搜索），不只是读 package.json | 竞品用固定模板或基础扫描 |
| 自进化机制 | 生成的 AGENTS.md 内置自动维护规则，随项目一起成长 | 竞品产出静态文件 |
| 业务类型感知 | 12 种业务类型推断，驱动不同的文档结构 | 没有竞品会推断项目类型 |
| 增量质量检测 | 自动评估现有 AGENTS.md 的质量，分级处理（完整→跳过 / 部分→补充 / 无→全量） | 竞品要么覆盖，要么从零开始 |
| 多 IDE 生态 | 自动生成 CLAUDE.md、.cursor/rules、copilot-instructions 等 | 没有竞品提供 |
| 模块表自动生成 | 读取真实源码目录，按文件模式推断职责，网络搜索兜底 | 没有竞品提供 |
| MCP 工具自动推荐 | 从检测到的技术栈出发，用三级匹配自动匹配 MCP 工具，输出组合建议（必须/推荐/可选）+ 一份可安装的 MD 文档；双层网络搜索让命令保持最新 | 竞品（如 Project Genesis Phase 9）只接入预设 MCP 配置——不会从技术栈自主推荐 |
| 7 语言 15 框架知识库 | 95 条组件条目，含 Commands + Conventions + CI，中文优先 | 竞品最多覆盖 JS/TS 生态 |
| 红线权威表 + 双向审查 | 红线放在一张表里，带稳定 ID（RL-NN），由每个门禁的 source 引用；检查双向运行——既查僵尸门禁，也查没有门禁的红线（规则 E）；表缺失时降级并说明未覆盖的风险，而不是直接放行 | 竞品把约定写成散文——改个章节名就会悄悄断链，也没有工具校验红线 ↔ 门禁的覆盖 |
| 内联 CI 门禁任务 + 运行时自校验 | 门禁任务内联进每个语言工作流（不用「记得追加」）；每个任务的第一个命令跑 command -v 加版本打印，运行时缺失会在第一行就失败 | 竞品模板只发碎片；接线靠手动，失败时悄无声息 |

有什么不一样

- 自主发现，不是预设 —— 扫描你项目里实际有什么
- 三级分类 —— 精确匹配 → 模式启发式 → 网络搜索
- 全栈覆盖 —— AGENTS.md + 文档 + CI + 测试策略 + Git，一句话搞定
- 对增量友好 —— 自动识别已有项目，只补缺的部分
- Monorepo 就近文件优先 —— 多子项目仓库拿到根 AGENTS.md 加每个包的 AGENTS.md，与官方 AGENTS.md 语义一致
- 自演化 —— 生成的 AGENTS.md 不是死文件；它教会 AI 随项目成长自我维护
- MCP 就绪的工具链 —— 根据你的技术栈自动推荐 MCP 工具加组合，附带可安装文档，永不发出过时命令
- AI 错误预防 + BUG→约定反馈闭环 —— 初始化时注入内置的 7 类 27 条 AI 常见错误知识库；约定缺失导致的 BUG 自动回流进 AGENTS.md 和 B-01，约定随真实实践一起演化
- 不会腐烂的约定 —— 不只是静态文档：每条阻断性红线都附带可执行检查，门禁注册表有单一事实来源和宪法自检，约定随项目成长而不是漂移
- 可生长的门禁 —— 初始化只播种通用门禁；项目的 AI 按元规则把真实坑点变成领域门禁（无门禁不成规则 / 每个缺陷都闭环）
- 不漂移的约定 —— 种子门禁（drift-check）检查依赖 ↔ 技术栈行、模块表 ↔ 实际目录、门禁有效性，让规格和代码无法悄悄分叉（quality-gates / spec-code drift）
- 渐进式披露 —— 技能主体是精简的 ≤200 行索引；Step 细节按需加载，常驻上下文保持很小又不丢深度
- 中文优先 —— 7 种语言、15 个框架、95 条组件条目原生中文

怎么工作

用户说：「初始化这个项目」 ↓ Step 1: 自主扫描 → 文件分类 → 依赖推断（三级）
↓ (Step 细节按需从 references/step-.md 加载)
Step 2: 规则引擎从 95 条组件知识库组装 AGENTS.md
↓ (未知技术栈 → WebSearch 兜底)
↓ (多子项目 → 根 AGENTS.md + 每个包的 AGENTS.md)
Step 3: 按业务类型（12 种）生成动态文档骨架 + MCP 工具推荐（B-05） ↓ Step 4: 配置 Git（.gitignore + 分支策略） ↓ Step 5: 配置 CI/CD（语言 + 平台自适应） ↓ Step 6: 建立测试策略（贴合阶段，不强制） ↓ Step 7: 注入持续自我维护指令 ↓ 已完成：生成 15+ 个文件（多子项目会为每个包追加 AGENTS.md），项目已具备 AI 就绪能力

环境要求

- 任意支持 SKILL.md 格式的 AI 编程智能体
- Node.js（用于 npx skills add 安装）

参与贡献

欢迎贡献！可以从这些方向入手：

- 知识库：往 references/knowledge-base.md 里补充更多语言/框架/ORM/UI 库条目
- MCP 工具：往 references/mcp-tools.md 里补充 MCP 工具条目（用法/安装/组合），扩大维度覆盖
- 代码规范：在 references/code-conventions.md 里补充或打磨基础编码规范规则（命名/目录/错误处理/日志/安全/性能，附检索模板）
- AI 常见错误：往 references/ai-common-mistakes.md 里补充 AI 常见错误条目（错误/后果/❌示例/✅修正/知识库链接/检索模板），扩大反模式覆盖
- 门禁脚本：为某个技术栈的常见坑写一个检查脚本（单文件、零外部依赖）——任何项目都能复用
- 启发式规则：扩展 Step 1.2 名称模式分类，覆盖更多依赖关键词
- 文件发现：扩展 Step 1.1 文件模式映射，支持更多构建工具和语言生态
- 业务类型：扩展 Step 3.0 配置功能推断，覆盖更多项目类型
- CI 平台：补充更多 CI 平台模板（GitLab CI、Jenkins、CircleCI 等）
- 实战反馈：分享真实项目中的使用案例和改进建议，帮助框架持续演进
- 翻译：把 README 翻译成日语、韩语等其他语言

许可证

MIT —— 详见 LICENSE。

作者：曙光 (shuguang1994)

Made with ❤️ in China | 始于实战，开源共享