name: create-blueprint description: 研究特定系统并创建或更新其蓝图文档

名称

blueprints:create-blueprint - 为特定系统生成或更新蓝图文档

概要

/blueprint <系统名称>

描述

在代码库中研究特定系统，并在仓库根目录的 blueprints/ 目录中创建或更新其技术蓝图文档。

重要：蓝图位置

关键： 蓝图必须在仓库根目录创建，切勿在子目录或包中创建。

{repo-root}/blueprints/{system-name}.md
{repo-root}/packages/foo/blueprints/{system-name}.md
{repo-root}/src/blueprints/{system-name}.md

蓝图是仓库范围内的系统设计文档。一个系统可能跨越多个包或目录，但应该在仓库根目录有一个蓝图来描述整个系统。

实现

你的任务是创建或更新特定系统的技术蓝图文档。

流程

1. 确定目标系统

用户将指定要记录的系统。这可以是：

功能名称（例如，“authentication”、“caching”）
目录路径（例如，“lib/commands/mcp”）
组件名称（例如，“MCP server”、“hook dispatcher”）

2. 深度研究阶段

彻底调查系统：

查找所有相关文件使用Glob和Grep
阅读实现以理解：
- 入口点和公共API
- 内部架构和数据流
- 依赖和集成
- 配置选项
- 错误处理和边缘情况
检查现有文档：
- 目录中的README文件
- 内联代码注释
- 现有蓝图文件
- 测试文件（它们记录预期行为）

3. 检查重复项

在创建新蓝图之前，检查已存在的内容：

列出所有蓝图：使用 Glob("blueprints/*.md") 查看所有现有蓝图文件
按关键字搜索：使用 Grep 在 blueprints/ 中搜索前端matter以查找相关主题
阅读相关蓝图：使用 Read("blueprints/{related-name}.md") 检查重叠
识别重叠系统，这些系统应一起记录

4. 编写蓝图

使用 Write 工具创建或更新蓝图文件 blueprints/{system-name}.md。

文件必须包含YAML前端matter：

---
name: system-name
summary: 简要的一行描述
---

# {System Name}
...

蓝图内容应遵循此结构：

---
name: system-name
summary: 简要的一行描述
---

# {System Name}

{简要的一行描述}

## 概述

{2-3段解释系统的目的、存在原因以及在更大系统中的作用}

## 架构

{描述系统结构}

### 组件

- **{Component A}** - {描述}
- **{Component B}** - {描述}

### 数据流

{数据如何在系统中流动}

### 依赖

- {Dependency 1} - {为什么需要}
- {Dependency 2} - {为什么需要}

## API / 接口

### 公共函数/方法

#### `functionName(params)`

{描述}

**参数：**
- `param1` (类型) - {描述}

**返回：** {描述}

### 命令

{如果适用，记录CLI命令}

### 配置

{记录配置选项}

## 行为

### 正常操作

{系统在正常条件下的行为}

### 错误处理

{如何处理错误}

### 边缘情况

{显著的边缘情况及其处理方式}

## 文件

关键实现文件：

- `path/to/main.ts` - {简要描述}
- `path/to/helper.ts` - {简要描述}

## 相关系统

- [{Related System}](./related-system.md) - {关系描述}

输出

完成研究和文档后：

使用 Write("blueprints/{system-name}.md", content) 创建/更新蓝图
报告记录了什么以及可能需要的相关系统文档

注意： 蓝图索引在 .claude/rules/blueprints/blueprints-index.md 由SessionStart钩子自动重新生成 - 你不需要手动更新。