shuguang1994/project-blueprint

项目蓝图 🏗️

一条命令，让任何项目为 AI 智能体做好准备。
一键为新项目建立完整 AI 编程规范体系。

License: MIT
skills.sh

Topics ·
dsh-plugin
deepseek-harness
agent-skills
claude-code
cursor
codex

中文文档

这是什么？

Project Blueprint 是一个可复用的 AI 智能体技能，只需一句话就能将任何新项目转变为 AI 就绪的代码库。它不是静态模板——而是一个自主发现引擎：扫描你的项目文件，智能分类依赖项，并从包含 95 个条目的组件知识库中动态组装出定制化的 AGENTS.md、文档骨架、CI/CD 流水线和测试策略。

只需说：“初始化这个项目的开发规范”，智能体就会完成其余工作。

快速安装

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、2/3 层前后端或单项目 |
| Monorepo 嵌套 AGENTS.md | 根 AGENTS.md（全局约束 + 子项目索引）+ 每个包的 AGENTS.md（就近文件优先），当存在 ≥2 个构建/清单文件时 |
| 智能依赖分类 | 3 层：知识库精确匹配 → 29 种启发式模式 → 网络搜索 |
| 业务类型推断 | 2 层启发式（结构 + 配置特征），12 种业务类型 |
| 动态 AGENTS.md | 由 95 条组件知识库组装而成，而非模板 |
| 模块表生成 | 读取实际源码目录，通过文件模式推断职责，网络搜索作为回退 |
| 文档系统 | A/B/C/D/E 5 层分类，按业务类型生成 |
| 测试策略 | 与阶段相适应的分层策略，不强制生成示例文件 |
| 多 IDE 支持 | 自动生成 CLAUDE.md、.cursor/rules、copilot-instructions 等 |
| 厂商私有增强层 | 超越面包屑：Cursor .mdc glob 激活、Claude Code hooks/subagents 骨架、Copilot instructions 分层 |
| 增量模式 | 在现有项目上仅填补空白，绝不覆盖 |
| 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. 统一入口 + check-constitution 自检 |
| 文档契约与校验 | 文档状态头 / 编号 / 索引契约 + docs-check 脚本（错误阻断，警告不阻断） |
| AI 工作协议 | 7 步任务生命周期 + 证据标准 + DoD + 缺陷复盘模板 |
| 规范驱动开发（6 阶段） | specify → plan → tasks → checklist → implement → verify；规范检查清单可直接注册为门禁（source: spec#） |
| 规范-代码漂移门禁 | 种子门禁检查依赖 ↔ AGENTS.md 技术栈行、模块表 ↔ 实际目录，以及门禁有效性（drift-check.） |

它生成什么

| 输出 | 描述 |
|--------|-------------|
| AGENTS.md | 项目约定（受架构原则约束）；在 monorepo 中：全局约束 + 子项目索引 |
| /AGENTS.md | 当存在 ≥2 个构建/清单文件时的按包约定（monorepo：根 = 全局 + 索引，包 = 本地，最近文件优先） |
| docs/ | A/B/C/D/E 分类文档骨架 + README 维护指南（含 B-01-开发规范，真实的 8 章约定） |
| .github/workflows/ci.yml | CI 流水线（自动适配语言 + 平台） |
| .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 | 测试策略（分层、时机、框架特定模式） |
| docs/B/B-05-MCP工具清单.md | MCP 工具列表 + 组合建议 + 安装命令（按需） |
| scripts/gates.json | 门禁注册表（单一事实来源：source / level / stage / command；默认播种 2 个种子门禁） |
| scripts/verify. | 统一门禁入口（自动选择宿主：Node / Python / make / shell） |
| scripts/check-constitution. | 章程自检（AGENTS.md 红线 ↔ 门禁注册表，双向） |
| scripts/docs-check. | 文档一致性检查（编号 / 状态头 / 索引 / 归档冲突 + 大小；扫描范围自适应：遍历实际存在的 docs/ 子目录；错误阻断） |
| scripts/drift-check. | 规范-代码漂移检查（依赖 ↔ 技术栈行 / 模块表 ↔ 实际目录 / 门禁有效性）——第 2 个种子门禁 spec-drift |
| docs/B/B-06-门禁与工作协议.md | 门禁增长循环 + 证据标准 + DoD（中型/大型项目按需） |

按需：小型项目只获得单个门禁 + 统一入口——没有完整门禁层或协议文档（保持精简，避免过度工程）。

自主发现引擎

Project Blueprint 不检查固定的文件列表。它扫描你的项目并发现一切。

依赖分类：3 层

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

技术栈覆盖

| 层 | 组件 |
|-------|-----------|
| 语言（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 搜索回退

每个维度都有 Web 搜索回退——不仅是语言/框架，还包括 CSS、lint、包管理器、部署、UI 库、数据库和状态管理：

未知依赖：@shadcn/ui 不在知识库中
→ 启发式：包含 "shadcn" + "ui" → 维度：ui
→ WebSearch："shadcn/ui component library conventions 2026"
→ 提取：注册模式、主题化、Tailwind 集成
→ 写入 AGENTS.md

Web 回退覆盖两个阶段：生成（对未知依赖/模块进行 Web 搜索）+ 编码（生成的 AGENTS.md 要求在编写代码前，对照官方文档验证第三方库 API/版本）。

独特创新

已通过 Web 搜索验证——现有 AGENTS.md 生成工具均未实现这些功能。

| 创新 | 描述 | 竞品状态 |
|------------|-------------|-------------------|
| 全生命周期生成 | 一句话 → AGENTS.md + 文档 + CI/CD + 测试策略 + Git 约定 | 竞品仅生成 AGENTS.md |
| 自主发现引擎 | 三级分类（精确→启发式→Web 搜索），而不仅仅是读取 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 生态 |

有何不同

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

工作原理

用户说：“初始化这个项目”
↓
Step 1：自主扫描 → 文件分类 → 依赖推断（三级）
↓（Step 详情按需从 references/step-.md 加载）
Step 2：规则引擎从 95 条目组件知识库组装 AGENTS.md
↓（未知技术栈 → WebSearch 兜底）
↓（多子项目 → 根 AGENTS.md + 每个包的 AGENTS.md）
第 3 步：按业务类型（12 种）生成动态文档骨架 + MCP 工具推荐（B-05）
↓
第 4 步：配置 Git（.gitignore + 分支策略）
↓
第 5 步：配置 CI/CD（语言 + 平台自适应）
↓
第 6 步：建立测试策略（与阶段相适应，不强制）
↓
第 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 常见错误条目（错误/后果/❌示例/✅修复/知识库链接/搜索模板），扩展反模式覆盖
- 门禁脚本：为某些技术栈中的常见陷阱编写检查脚本（单文件、零外部依赖）——可被任何项目复用
- 启发式规则：扩展第 1.2 步的名称模式分类，覆盖更多依赖关键词
- 文件发现：扩展第 1.1 步的文件模式映射，以支持更多构建工具和语言生态
- 业务类型：扩展第 3.0 步的配置功能推断，以支持更多项目类型
- CI 平台：添加更多 CI 平台模板（GitLab CI、Jenkins、CircleCI 等）
- 真实反馈：分享来自真实项目的用例和改进建议，帮助框架演进
- 翻译：将 README 翻译为日语、韩语及其他语言

许可证

MIT — 详情见 LICENSE。

作者：曙光 (shuguang1994)

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