name: blueprints-writing user-invocable: false description: 用于在创建或更新新功能、API更改或架构修改的技术蓝图文档时使用。总是先搜索现有蓝图以避免重复，然后以适当结构编写。 allowed-tools: [Read, Write, Edit, Grep, Glob]

编写技术蓝图

目的

技术蓝图文档记录系统内部如何工作。它们不同于用户文档（如何使用）和README文件（项目概述）。

何时编写蓝图

为以下情况编写蓝图：

具有多个组件的复杂系统
公共API及其合同
架构决策及其理由
从代码中不明显的的行为
系统之间的集成点

跳过蓝图用于：

自文档化代码（简单实用程序）
测试文件（测试本身就是文档）
外部依赖（链接到其文档）

创建蓝图

重要： 创建新蓝图前总是检查现有蓝图，并使用正确的前缀格式。

# 1. 列出现有蓝图
Glob("blueprints/*.md")

# 2. 按关键词搜索相关蓝图
Grep("keyword", path: "blueprints/", output_mode: "files_with_matches")

# 3. 如果更新，读取现有蓝图
Read("blueprints/authentication.md")

# 4. 使用前缀格式编写蓝图
Write("blueprints/system-name.md", content_with_frontmatter)

前缀格式为：

---
name: system-name
summary: 简短一行描述
---

蓝图文件结构

使用此结构作为蓝图内容：

---
name: system-name
summary: 一行描述该系统做什么。
---

# 系统名称

一行描述该系统做什么。

## 概述

2-3段覆盖：
- 为什么该系统存在（解决的问题）
- 高层次上它做什么
- 在更大架构中的位置

## 架构

### 组件

列出主要组件：
- **ComponentA** - 目的和责任
- **ComponentB** - 目的和责任

### 数据流

描述数据如何在系统中移动：
1. 输入通过X到达
2. ComponentA处理和转换
3. 结果传递给ComponentB
4. 输出返回/存储

### 依赖

- **依赖** - 为什么需要，提供什么

## API / 接口

### 函数

#### `functionName(param1, param2)`

函数功能的清晰描述。

**参数：**
- `param1`（类型） - 此参数控制什么
- `param2`（类型，可选） - 省略时的默认行为

**返回：** 类型 - 返回值的描述

**抛出：** 错误类型 - 当此错误发生时

**示例：**
```typescript
const result = functionName('value', { option: true });

配置

选项	类型	默认值	描述
`optionA`	布尔	false	它控制什么

行为

正常操作

典型执行流的逐步描述。

错误处理

系统如何响应：

无效输入
缺少依赖
外部故障

边缘情况

记录非明显行为：

空输入处理
并发访问
资源限制

文件

关键文件及其角色：

src/main.ts:1-50 - 入口点，初始化
src/processor.ts - 核心处理逻辑
src/types.ts - 类型定义

写作风格

要精确

差：“系统优雅地处理错误” 好：“无效输入返回带有字段名和原因的ValidationError”

记录行为，而非实现

差：“使用for循环遍历项目” 好：“顺序处理项目，在第一个失败处停止”

包含示例

展示，不要只说：

// 好：具体示例
const result = processItems(['a', 'b', 'c'], { parallel: true });
// 返回：{ processed: 3, failed: 0 }

保持更新

与代码变更一起更新蓝图
删除已删除功能的文档
明确标记已弃用功能

常见错误

太多细节 - 不要记录每一行代码
太少上下文 - 解释为什么，不只是什么
过时文档 - 过时文档比没有更糟
重复内容 - 链接而非复制
实现焦点 - 记录合同，而非内部

技术蓝图写作Skill blueprints-writing