---
name: project-blueprint
description: 为新项目快速建立完整 AI 编程规范体系（AGENTS.md、文档目录、CI/CD、Git规范、测试制度）。自主发现引擎：扫描项目→分类文件→推断技术栈，覆盖 7 语言 15 框架 95 个组件条目，未知栈三层递进联网回退。Establish AI coding conventions for new projects — autonomous discovery engine with heuristic dep classification, 7 languages 15 frameworks 95 component entries, web search fallback for unknowns.
author: 曙光 (shuguang1994)
license: MIT
---

# Project Blueprint — AI 编程规范体系搭建 Skill

> 跨项目可复用的 7 步规范体系搭建流程。新项目一句话触发，15+ 文件自动生成。

## 触发条件

当用户说以下关键词时自动加载（中英双语）：
- 初始化新项目 / 建立开发规范 / 搭建项目体系 / 项目脚手架
- init project / setup conventions / bootstrap / new project / AGENTS.md template

## 执行原则

- **探测优先**：先读取项目文件（package.json / go.mod / requirements.txt），不凭空猜测
- **最小侵入**：只补充缺失的文件，不覆盖已有配置
- **不确定就问**：技术栈/远程仓库类型不确定时，主动向用户确认
- **一步一验证**：每步完成后报告生成了哪些文件

---

## Step 索引与按需加载

| Step | 做什么 | 细节文件 | 何时读 |
|------|--------|---------|--------|
| Step 1 | 自主发现引擎：扫描项目文件 → 分类 → 三层递进推断技术栈 | `references/step-1-discovery.md` | 接入新项目、需要探测文件与技术栈时 |
| Step 2 | 规则引擎拼接：按组件名从知识库提取 Commands/Conventions/CI，拼装 AGENTS.md | `references/step-2-assembly.md` | 生成/更新 AGENTS.md 前 |
| Step 3 | 建立自适应文档体系：推断业务类型 → 生成 docs/ 骨架 + B-01/B-04/B-05 + 门禁层 | `references/step-3-docs.md` | 生成 docs/ 与门禁层时 |
| Step 4 | 配置 Git 规范：.gitignore / CHANGELOG.md / 分支策略 | `references/step-4-git.md` | 配置 Git 与版本记录时 |
| Step 5 | 配置 CI/CD：合并 CI job 片段 → 生成 workflow + 门禁统一入口 job | `references/step-5-ci-and-gates.md` | 项目有 CI/CD 需求时 |
| Step 5.5 | 门禁装配：宿主选择 → 装配点 → 实跑自测（与 Step 5 同文件） | `references/step-5-ci-and-gates.md` | 生成门禁后装配到提交与 CI 时 |
| Step 6 | 建立测试制度：安装测试框架 + B-03 测试指南 + git hooks | `references/step-6-testing.md` | 建立测试制度与 hooks 时 |
| Step 7 | 持续自适应：上下文管理注入 + 门禁生长 + 文档健康检查 | `references/step-7-adaptive.md` | 项目推进中维护 AGENTS.md / docs 时 |

> 索引层只给流程骨架，实现细节一律按需读取对应 step 文件，避免一次性载入全部细节（按章节标题定位，不读全文）。

---

## 输出验收清单

所有步骤完成后，向用户报告：

```
✅ 项目规范体系搭建完成，生成文件：
- AGENTS.md (xxx 行)
- docs/ (A/B/C/D/E 5 个分类目录 + archive + dev)，含 B-01-开发规范（实写 8 章，非占位符）、B-04-BUG知识库（`## BUG-NNN` 编号唯一 + 症状速查表 + 六段式）
- docs/B/B-00-红线与门禁映射.md (红线权威表：RL-NN 稳定 ID + 档位 + 对应门禁；与 gates.json 同时生成)
- docs/B/B-05-MCP工具清单.md (MCP 工具推荐，含安装命令与组合建议，按需生成)
- docs/B/B-07-门禁与工作协议.md (AI 编程工作协议 + 门禁生长细则，中大型项目)
- scripts/gates.json (门禁清单，唯一事实源)
- scripts/verify.* (门禁统一入口)
- scripts/check-constitution.* (宪法自校验，规则 A~E：含「有红线无门禁」方向)
- scripts/docs-check.* / scripts/drift-check.* (两条种子门禁：docs-consistency + spec-drift；drift-check 含检查 D「测试框架 ↔ CI test 步骤」)
- .trae/specs/ (spec-driven 开发基础设施)
- .github/workflows/ci.yml (或 .gitee-ci.yml，门禁 job 已内联 + 运行时自证；test 步骤按探测结果生成)
- .gitignore (如果之前没有)
- CHANGELOG.md (版本记录，[Unreleased] 初始化占位，发版按 AGENTS.md 发布规范更新)
- CLAUDE.md / .cursor/rules/project.mdc (vendor breadcrumbs)
- .husky/pre-commit / pre-push (如果安装同意)

下一步建议：
1. 填写 docs/A/A-01-PRD.md 项目需求
2. 根据实际项目完善 AGENTS.md 中的项目身份信息
3. 阅读 docs/B/B-03-测试指南.md，核心功能稳定后按制度编写首批测试（若 CI 未生成 test 步骤，按该文件的契约补上）
4. git push origin <主分支> 推送初始框架（按分支策略：main 或 develop）
```

**门禁验收**（与上表并列的报告项）：

- [ ] `scripts/verify.*` 本地实跑通过（或全部为 warn 级）
- [ ] `scripts/check-constitution.*` 输出 0 error，**且未处于降级态**（权威表已生成 → 规则 A/E 生效；报告中不得出现「无权威表，已降级」）
- [ ] `scripts/gates.json` 条目 ≥ 2，且每条 `source` 为 `AGENTS#<RL-ID>@<章节名>` 形态
- [ ] `docs/B/B-00-红线与门禁映射.md` 中每条 `blocking` 红线都有 ≥1 条门禁引用（规则 E 报 0 error）
- [ ] 新登记的 blocking 门禁已完成负向验证（留证）

**CI 验收**（4 条，见 `references/step-5-ci-and-gates.md` 的自检表）：

- [ ] 生成物中 `passWithNoTests` 命中数 = 0
- [ ] 生成的 workflow 含 `scripts/verify.` 调用（门禁已接线，不依赖"记得追加"）
- [ ] 每个 job 首条命令含 `command -v` + 版本打印（运行时自证）
- [ ] test 步骤与探测结果一致（有框架/测试文件才有 test 步骤；没有则 `B-03` 含补步骤契约）

> 任一项不满足时，在报告中显式标注"未闭环 + 原因 + 风险"，不得静默跳过（见 `references/ai-work-protocol.md` 第四章证据标准）。

---

## 参考文件索引

> 本索引是 **skill 包自身文件索引**（非目标项目文件清单，不违反「零固定表」设计），指向 `references/` 目录下的知识库与实现细节文件。**本索引随 `references/` 扩充同步维护**。

| 文件 | 职责 |
|------|------|
| `references/knowledge-base.md` | 95 组件条目知识库（16 个维度章节：语言/框架/ORM/CSS/UI/测试/Lint/包管理/部署/状态管理/数据库/AI/IaC/可观测性/数据/移动 + 通用段落），Step 2 拼接来源 |
| `references/code-conventions.md` | 基础代码规范种子知识库（命名/目录/错误处理/日志/安全/性能 6 大类 + 搜索模板），Step 2 参考 |
| `references/ai-common-mistakes.md` | AI 高频错误知识库（7 大类 27 条，六段式），Step 2 优先注入 + B-04 反哺迭代 |
| `references/mcp-tools.md` | MCP 工具知识库（维度匹配表 14 行 + 18 个工具条目 + 推荐组合矩阵，含适用场景/安装方式/推荐组合），Step 3.4 参考 |
| `references/agents-md-template.md` | AGENTS.md 兜底模板（全部探测+联网失败时使用） |
| `references/monorepo-agents.md` | 多子项目 AGENTS.md 装配规则（判定条件/根与子职责边界/骨架模板/增量合并），Step 2.4 参考 |
| `references/vendor-breadcrumbs.md` | AI 工具入口文件与私有增强层生成规则（CLAUDE.md / Cursor / Copilot / Gemini 等），Step 2.1 参考 |
| `references/ci-template.yml` | CI 模板（TS / Vue / Go / Python 四种**完整 workflow**：门禁 job 已内联 + 运行时自证 + test 步骤条件生成），Step 5 参考 |
| `references/docs-skeleton.md` | docs/ 目录骨架指南（A/B/C/D/E 五级分类 + `B-00-红线与门禁映射.md` 红线权威表 + BUG 库 schema 唯一源），Step 3 详细参考 |
| `references/gitignore-template.md` | Git 忽略规则模板（按语言选择），Step 4 参考 |
| `references/project-sync-guide.md` | Agent 文档同步操作指南（Step 7 参考） |
| `references/ai-work-protocol.md` | AI 编程工作协议（任务生命周期/证据标准/DoD/缺陷复盘模板=Bug 库条目内部结构/门禁生长 6 步），Step 3.5 生成 B-07 |
| `references/spec-driven.md` | 规范驱动开发六阶段（准入门槛/三件套模板/checklist 转门禁），Step 3.3 参考 |
| `references/gates-templates.md` | 门禁模板集（gates.json 唯一事实源 + 红线权威表 + verify.* + check-constitution.* 规则 A~E + 宿主/装配点选择 + 漂移门与种子门禁清单 + Python/Makefile 宿主），Step 3.5 / 5.5 参考 |
| `references/verify-py-template.md` | `scripts/verify.py` 可运行参考实现（Python 宿主，与 `verify.mjs` 语义等价），Step 3.5 / 5.5 参考 |
| `references/check-constitution-py-template.md` | `scripts/check-constitution.py` 可运行参考实现（规则 A / A' / B / C / D / E，与 Node 版语义等价），Step 3.5 参考 |
| `references/docs-check.mjs` | 文档一致性校验脚本参考实现（**校验范围自适应**：遍历 docs/ 实际存在的子目录；校验编号连续性/状态头/索引覆盖/归档冲突 + 单文件体积） |
| `references/drift-check.mjs` | 规范漂移校验脚本参考实现（依赖↔规范 / 模块速查表↔目录 / 门禁有效性 / **测试框架↔CI test 步骤**；**无源码根时回退到顶层目录比对，且不适用时输出适用性裁定**），spec-drift 门禁参考 |
| `references/eval-baseline.md` | 体系质量评估基准（Skill 生成物 + Skill 自身：规模指标 / 闭环指标 / 发布前核对），Step 7 参考 |
| `references/step-1-discovery.md` | Step 1 自主发现引擎完整实现细节 |
| `references/step-2-assembly.md` | Step 2 规则引擎拼接完整实现细节 |
| `references/step-3-docs.md` | Step 3 建立自适应文档体系完整实现细节 |
| `references/step-4-git.md` | Step 4 配置 Git 规范完整实现细节 |
| `references/step-5-ci-and-gates.md` | Step 5 配置 CI/CD 与 Step 5.5 门禁装配完整实现细节 |
| `references/step-6-testing.md` | Step 6 建立测试制度与基础设施完整实现细节 |
| `references/step-7-adaptive.md` | Step 7 持续自适应机制完整实现细节 |