name: generate-blueprints description: 深度研究所有系统并为整个代码库创建或更新蓝图/文档
名称
blueprints:generate-blueprints - 为整个代码库生成全面的蓝图文档
概要
/blueprints
描述
通过为每个主要系统创建或更新位于仓库根目录的 blueprints/ 目录中的技术文档，全面记录代码库中的所有系统。
重要：蓝图位置
关键： 蓝图必须创建在仓库根目录，切勿在子目录或包中。
{repo-root}/blueprints/{repo-root}/packages/foo/blueprints/（示例，实际不应在此）{repo-root}/src/blueprints/（示例，实际不应在此）
蓝图是仓库范围的系统设计文档。系统可能跨越多个包或目录，但所有蓝图都归属于仓库根目录的单个 blueprints/ 目录。
实现
您被分配了全面记录此代码库中所有系统的任务。
流程
阶段1：发现
-
分析项目结构以识别所有主要系统：
- 顶级目录及其目的
- 包/模块边界
- 入口点（主文件、CLI命令、API端点）
- 配置系统
-
阅读现有文档：
- 所有级别的 README.md 文件
- 任何现有的 blueprints/ 目录
- 内联文档模式
- 测试文件用于行为文档
-
创建系统清单：
- 列出所有独立系统/功能
- 注意系统间的依赖关系
- 识别文档缺口
阶段2：审计现有蓝图
使用原生工具审计现有文档：
- 列出所有蓝图：使用
Glob("blueprints/*.md")查找所有现有蓝图文件 - 阅读每个蓝图：使用
Read("blueprints/{name}.md")检查每个记录的系统：- 蓝图是否匹配当前实现？
- 是否有未记录的新功能？
- 是否有任何记录的功能已被移除？
- 识别孤立的蓝图（已移除系统的文档）
阶段3：优先记录顺序
按重要性排序系统：
- 核心系统 - 一切依赖的中心功能
- 公共API - 面向用户的功能和接口
- 集成点 - 系统如何连接
- 支持系统 - 实用工具和助手
阶段4：生成文档
对于每个系统，使用 Write 工具创建或更新蓝图文件：
Write("blueprints/{system-name}.md", content)
每个文件必须包含YAML前置元数据：
---
name: system-name
summary: 简短一行描述
---
# {系统名称}
{简短描述}
## 概述
{目的和在更大系统中的作用}
## 架构
{结构、组件、数据流}
## API / 接口
{公共方法、命令、配置}
## 行为
{正常操作、错误处理、边缘情况}
## 文件
{关键实现文件及描述}
## 相关系统
{链接到相关蓝图}
阶段5：索引管理
蓝图索引由 SessionStart 钩子自动管理。当您运行 han blueprints sync-index 时，索引在 .claude/rules/blueprints/blueprints-index.md 处更新。
您无需手动创建或更新任何索引文件 - 只需专注于使用 Write 工具创建高质量的蓝图内容。
去重策略
记录时，积极防止重复：
- 创建前检查 - 使用
Glob("blueprints/*.md")和Grep搜索现有覆盖 - 阅读现有蓝图 - 使用
Read("blueprints/{name}.md")检查内容 - 合并相关系统 - 将紧密耦合的系统记录在一起
- 使用交叉引用 - 在蓝图之间链接而非重复
- 单一真相源 - 每个概念在恰好一个地方记录
输出
完成后：
- 列出所有发现的系统
- 列出创建/更新的蓝图
- 注明任何无法记录的系统（原因）
- 识别需要未来记录的领域
记住： 使用原生工具（Glob、Grep、Read、Write）管理蓝图文件。前置元数据格式（name 和 summary 字段）支持通过自动生成的索引发现。