创建蓝图Skill：一条命令让 AI 通读代码库，为任意系统生成仓库级技术蓝图
- 它是什么：
create-blueprint（创建蓝图Skill）是一个面向代码库的系统级文档生成技能，通过/blueprint <系统名称>触发，自动研究指定系统并在仓库根目录的blueprints/下创建或更新技术蓝图文档。 - 核心差异：它不按文件生成零散注释，而是以「系统」为单位横向拉通多个包、多个目录，产出带有统一结构的架构文档。
- 产出规范：文件带 YAML 前置元数据（
name、summary），正文包含概述、架构、组件、数据流、依赖、API/接口、行为、关键文件、相关系统等固定章节。 - 省心细节：创建前会自动查重，避免重复造文档；蓝图索引由 SessionStart 钩子自动重建，不需要手动维护。
- 适合谁：接手遗留项目的开发者、需要快速摸清模块边界的技术负责人，以及希望给 AI 编码助手提供长期上下文的团队。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 中文名 | 创建蓝图Skill |
| 英文名 | create-blueprint |
| 技能 ID | 13981 |
| 核心命令 | /blueprint <系统名称> |
| 产出位置 | {repo-root}/blueprints/{system-name}.md |
它解决什么问题
中大型代码库普遍存在一个矛盾：代码越写越多，系统级文档却越来越少。README 散落在各个子目录，注释只解释单行逻辑，新同学想知道「鉴权是怎么串起来的」「MCP server 的入口在哪」，只能靠人肉搜索。而通用 AI 助手在没有上下文时，往往只看到你粘贴的几百行片段，给不出跨模块的整体视图。
创建蓝图Skill 正是补这个缺口：它把「调研一个系统 → 形成结构化设计文档 → 沉淀到仓库里」这套动作产品化，你只给一个系统名，剩下的检索、阅读、归纳、落盘由技能按固定流程完成。
一键安装与生效验证的思路
该技能运行在支持 AI 技能（Skill）机制的编程环境中，其索引文件位于 .claude/rules/blueprints/blueprints-index.md，并由 SessionStart 钩子自动重建，说明它通常随项目规则或技能市场一并启用。具体的安装命令、下载入口与是否需要付费，请以官方说明为准。通用步骤如下：
- 准备前提：确保你的 AI 编程环境已支持技能/斜杠命令机制，且当前工作目录是目标代码仓库的根目录（蓝图必须写在仓库根，而非子包内）。
- 安装/启用技能：通过官方技能市场或项目内的技能目录添加
create-blueprint，具体命令与入口以官方说明为准。 - 验证是否生效：在会话中输入
/blueprint authentication之类的命令，若技能被正确加载，它应当先执行文件检索与代码阅读，而不是立刻返回一段空泛文字。 - 确认落盘结果：检查仓库根目录是否出现
blueprints/{system-name}.md，并核对文件中是否包含规范的 YAML 前置元数据与各章节内容。 - 确认索引联动：查看
.claude/rules/blueprints/blueprints-index.md是否已被自动更新——按技能说明，这一步由钩子完成，你无需手动改。
该技能的主要功能和特点
- 以「系统」为调研单位，而非以文件为单位：目标对象可以是功能名（如
authentication、caching）、目录路径（如lib/commands/mcp）或组件名（如MCP server、hook dispatcher），天然支持跨包、跨目录的系统。 - 强制的仓库根目录约定：蓝图统一落在
{repo-root}/blueprints/，明确反对写进packages/foo/blueprints/或src/blueprints/。这条约束保证了「一个系统一份蓝图」的单一事实源。 - 深度研究流程：先用 Glob 与 Grep 找齐相关文件，再阅读实现以理解入口点与公共 API、内部架构与数据流、依赖与集成、配置选项、错误处理与边缘情况，最后补看 README、内联注释、已有蓝图和测试文件（测试本身就是行为说明书）。
- 创建前自动查重：先
Glob("blueprints/*.md")列出全部蓝图，再用 Grep 搜索前置元数据中的相关主题，接着阅读可能重叠的蓝图，识别应当合并记录的系统，避免同一系统出现三份互相矛盾的文档。 - 统一的结构化模板：产出物包含概述、架构（组件/数据流/依赖）、API 与接口（公共函数、命令、配置）、行为（正常操作/错误处理/边缘情况）、关键文件清单、相关系统互链，读者可按同一套目录快速定位信息。
- 支持「创建」与「更新」双向操作：对已存在的系统再次执行命令，会在原有蓝图基础上补齐或修订内容，而不是简单覆盖。
- 索引自动维护：蓝图索引由 SessionStart 钩子自动重新生成，减少人工维护文档目录的负担。
- 与普通工具相比强在哪：普通文档生成器多为「按文件导出注释」，属于自下而上的堆叠；本技能是自上而下的系统归纳，且产出可被后续 AI 会话直接当作上下文复用。
如何使用该技能？
第 1 步：确定目标系统
给技能一个明确的系统边界。三种常见写法：
- 功能维度：
/blueprint authentication - 路径维度：
/blueprint lib/commands/mcp - 组件维度：
/blueprint hook dispatcher
系统名越具体，调研越聚焦；如果一次给的范围过大（例如直接写 /blueprint backend），容易得到一篇泛泛而谈的文档。
第 2 步：触发技能
在会话中输入：
/blueprint caching
第 3 步：让技能完成深度研究
技能会自动检索相关文件、阅读实现、检查文档与测试。此时不必急着催促它出结果，调研越充分，蓝图质量越高。
第 4 步：查重与合并判断
技能会先扫描已有蓝图，判断是否存在重叠系统。若发现 blueprints/cache.md 与 blueprints/redis-layer.md 讲的是同一件事，它会倾向于更新而非新建。
第 5 步：写入蓝图文件
产出文件形如 blueprints/caching.md，结构参考如下（沿用技能自带模板）：
---
name: caching
summary: 统一缓存层，负责读写策略与失效管理
---
# Caching
统一缓存层，负责读写策略与失效管理
## 概述
（2-3 段说明系统目的、存在原因与在整体系统中的位置）
## 架构
### 组件
- **CacheClient** - 对外统一入口
### 数据流
（请求如何进入、命中或穿透、如何回源）
### 依赖
- Redis - 提供持久化缓存存储
## API / 接口
### 公共函数/方法
#### `get(key, options)`
**参数：** `key`（字符串）- 缓存键
**返回：** 缓存值或空
## 行为
### 正常操作 / 错误处理 / 边缘情况
## 文件
- `path/to/main.ts` - 主要实现
## 相关系统
- [Authentication](./authentication.md) - 缓存键中包含用户身份
第 6 步：查看输出报告
技能完成后会报告「记录了哪些内容」以及「哪些相关系统可能也需要一份蓝图」。这份提示可以当作下一步的待办清单。
第 7 步：人工复核后再提交
蓝图是 AI 基于代码归纳的产物，提交前建议快速核对关键 API 签名与文件路径是否准确，并确认相关系统链接可用。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| create-blueprint（创建蓝图Skill） | 仓库级系统设计文档生成 | 深度检索代码、查重、按统一模板生成/更新 blueprints/*.md，索引自动维护 |
需支持技能机制的 AI 编程环境，一条 /blueprint <系统名> 命令即可；具体安装以官方说明为准 |
遗留系统摸底、跨包系统梳理、给 AI 助手准备长期上下文 | 优势：流程规范、结构统一、可增量更新；不足：依赖代码可读性，系统边界需人工判断 |
| 人工手写架构文档（Wiki / Confluence） | 传统团队知识库 | 完全由人撰写与维护 | 门槛低但成本高，需要专人投入 | 对外交付文档、评审材料 | 优势：准确、可表达设计意图；不足：与代码同步成本高，容易过期 |
| 通用 AI 编程助手对话式生成 | 灵活的问答式文档输出 | 用户粘贴代码或指定文件，AI 生成说明文字 | 门槛最低，但需人工挑选上下文 | 临时解释某个函数或模块 | 优势：即时、自由；不足：缺乏统一结构，不落盘、不查重、跨模块视角弱 |
| 注释导出类文档工具（如按源码注释生成 API 文档的工具） | 自下而上的 API 文档生成 | 扫描注释与类型定义，输出接口手册 | 需接入构建流程，配置成本中等 | 对外 SDK 文档、类型声明参考 | 优势：与代码强绑定、可自动化；不足：只覆盖「接口」层，讲不清架构、数据流与依赖关系 |
从表格可以看出，本技能的差异化在于「系统视角 + 结构化模板 + 可增量维护」三者的组合，而不是单纯的文档导出。
该技能的典型应用场景与实际体验情况
场景一：新人接手遗留项目
痛点：仓库有几十个包，README 停留在两年前，没人说得清某条链路。使用方式：先 /blueprint <核心模块路径>，让技能输出架构与关键文件清单，新人按蓝图逐层深入。实际体验：上手难度极低，一条命令即可；效果取决于该模块是否有基本可读的命名与测试，命名混乱的模块需要人工二次修订。
场景二：技术负责人梳理跨包系统
痛点：某个能力横跨 packages/a、packages/b 与 src/ 三处，没有一处文档描述全貌。使用方式：以功能名触发，例如 /blueprint authentication。实际体验：技能会跨目录聚合，并明确要求在仓库根目录产出单一蓝图，避免了「每个子包一份、互相矛盾」的老问题；注意系统名要给得足够具体，否则容易写得宽泛。
场景三：重构或下线前的风险摸底
痛点：改动前想确认依赖关系与边缘情况，靠搜索容易漏。使用方式：对目标系统执行一次蓝图生成，重点看「依赖」「错误处理」「边缘情况」三节。实际体验：测试文件被纳入调研范围这点很有价值，因为测试常常记录了真实预期行为；但蓝图是文档而非真相，重构决策仍需以代码与测试运行为准。
场景四：为 AI 助手积累长期上下文
痛点：每次新开会话都要重新解释项目结构。使用方式：把关键系统的蓝图沉淀在 blueprints/ 中，后续会话直接引用。实际体验：随着蓝图数量增长，团队会形成一份可被机器与人共同消费的「系统地图」，索引由钩子自动重建，几乎零维护成本。
该技能能为用户带来的价值
- 把调研时间压缩成一条命令：原本需要人工翻目录、逐个读文件、边读边记的调研工作，现在由技能按固定流程执行。按经验估算，摸清一个中等规模模块往往需要半天到一天，而技能可在一次会话内产出初稿，人工只需复核。
- 降低文档门槛：不需要文笔好、也不需要熟悉文档规范，模板内置了架构、数据流、依赖、API、行为等章节，填空式完成。
- 消除重复与冲突：内置查重流程确保同一系统只有一份蓝图，避免多份过期文档互相打脸。
- 让知识可沉淀、可复用：蓝图写在仓库里，跟着代码走，后续人和 AI 都能读取，形成团队级的「系统地图」。
- 为重构与评审提供依据：关键文件清单与依赖关系可以直接用于影响面评估，减少「改了不知道影响谁」的焦虑。
- 长期价值：蓝图可持续更新，随着系统演进不断修订，逐渐替代散落各处的口口相传。
常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
它运行在支持 AI 技能机制的环境中，通常通过官方技能市场或项目内技能目录启用，触发命令为 /blueprint <系统名称>。具体安装入口、所需环境版本与是否收费，请以官方说明为准。安装后建议先用一个小模块试跑，确认 blueprints/ 目录正常生成文件。
Q2：蓝图为什么一定要放在仓库根目录的 blueprints/？
因为蓝图描述的是「仓库范围内的系统」，而一个系统常常跨越多个包和目录。如果写在 packages/foo/blueprints/ 或 src/blueprints/，就会人为割裂系统视图，最终变成每个子包各说各话。统一放在仓库根目录，才能保证「一个系统一份蓝图」。
Q3：我重复执行命令，会不会生成一堆重复文档？
不会。技能在创建前会先列出所有蓝图、按关键字搜索前置元数据、阅读可能重叠的文档，然后决定是新建还是更新。如果两个系统高度重叠，它会倾向于合并记录，并在输出中提示相关系统。
Q4：蓝图索引需要我手动更新吗？
不需要。索引文件位于 .claude/rules/blueprints/blueprints-index.md，由 SessionStart 钩子自动重新生成，你只要保证蓝图文件本身写对位置即可。
Q5：它和直接让 AI 助手写文档有什么区别？适合谁用？
直接对话式生成依赖你手动提供上下文，产出零散、不落盘、没有统一结构；本技能会自动检索代码库、按统一模板输出到仓库固定位置，并支持后续更新。它更适合需要长期维护系统文档的团队、接手遗留项目的开发者，以及希望给 AI 编码助手准备长期上下文的工程负责人。