Back to Details

create-blueprint

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Name

名称

blueprints:create-blueprint - Generate or update blueprint documentation for a specific system
blueprints:create-blueprint - 为特定系统生成或更新蓝图文档

Synopsis

语法

text
/blueprint <system-name>
text
/blueprint <系统名称>

Description

说明

Research a specific system in the codebase and create or update its technical blueprint documentation in the 
blueprints/
directory at the repository root.
研究代码库中的特定系统，并在仓库根目录的
blueprints/
目录下创建或更新其技术蓝图文档。

Important: Blueprint Location

重要提示：蓝图位置

CRITICAL: Blueprints MUST be created at the repository root, never in subdirectories or packages.
  • {repo-root}/blueprints/{system-name}.md
  • {repo-root}/packages/foo/blueprints/{system-name}.md
  • {repo-root}/src/blueprints/{system-name}.md
Blueprints are repository-wide system design documents. A single system may span multiple packages or directories, but there should be ONE blueprint at the repo root describing the entire system.
关键要求： 蓝图必须创建在仓库根目录，绝不能放在子目录或包中。
  • {repo-root}/blueprints/{system-name}.md
  • {repo-root}/packages/foo/blueprints/{system-name}.md
  • {repo-root}/src/blueprints/{system-name}.md
蓝图是仓库级别的系统设计文档。单个系统可能跨越多个包或目录，但应该在仓库根目录下有一个描述整个系统的蓝图。

Implementation

实施任务

You are tasked with creating or updating technical blueprint documentation for a specific system.
你的任务是为特定系统创建或更新技术蓝图文档。

Process

流程

1. Identify the Target System

1. 确定目标系统

The user will specify which system to document. This could be:
  • A feature name (e.g., "authentication", "caching")
  • A directory path (e.g., "lib/commands/mcp")
  • A component name (e.g., "MCP server", "hook dispatcher")
用户会指定要文档化的系统。可能是：
  • 功能名称（例如："authentication"、"caching"）
  • 目录路径（例如："lib/commands/mcp"）
  • 组件名称（例如："MCP server"、"hook dispatcher"）

2. Deep Research Phase

2. 深度研究阶段

Thoroughly investigate the system:
  1. Find all relevant files using Glob and Grep
  2. Read the implementation to understand:
    • Entry points and public APIs
    • Internal architecture and data flow
    • Dependencies and integrations
    • Configuration options
    • Error handling and edge cases
  3. Check for existing documentation:
    • README files in the directory
    • Inline code comments
    • Existing blueprints/ files
    • Test files (they document expected behavior)
彻底调研系统：
  1. 使用Glob和Grep查找所有相关文件
  2. 阅读实现代码以理解：
    • 入口点和公共API
    • 内部架构和数据流
    • 依赖关系和集成
    • 配置选项
    • 错误处理和边缘情况
  3. 检查现有文档：
    • 目录中的README文件
    • 内联代码注释
    • 已有的blueprints/目录下的文件
    • 测试文件（它们记录了预期行为）

3. Check for Duplicates

3. 检查重复内容

Before creating a new blueprint, check what already exists:
  1. List all blueprints: Use 
    Glob("blueprints/*.md")
    to see all existing blueprint files
  2. Search by keyword: Use 
    Grep
    to search frontmatter in 
    blueprints/
    for related topics
  3. Read related blueprints: Use 
    Read("blueprints/{related-name}.md")
    to check for overlap
  4. Identify overlapping systems that should be documented together
在创建新蓝图之前，检查已有的内容：
  1. 列出所有蓝图： 使用
    Glob("blueprints/*.md")
    查看所有现有蓝图文件
  2. 按关键词搜索： 使用
    Grep
    在
    blueprints/
    目录的前置内容中搜索相关主题
  3. 阅读相关蓝图： 使用
    Read("blueprints/{related-name}.md")
    检查是否有重叠内容
  4. 识别应一起文档化的重叠系统

4. Write the Blueprint

4. 编写蓝图

Use the 
Write
tool to create or update the blueprint file at 
blueprints/{system-name}.md
.
The file MUST include YAML frontmatter:
markdown
---
name: system-name
summary: Brief one-line description
---
使用
Write
工具在
blueprints/{system-name}.md
路径下创建或更新蓝图文件。
文件必须包含YAML前置内容：
markdown
---
name: system-name
summary: 简短的一行描述
---

{System Name}

{系统名称}

...

The blueprint content should follow this structure:

```markdown
---
name: system-name
summary: Brief one-line description
---
...

蓝图内容应遵循以下结构：

```markdown
---
name: system-name
summary: 简短的一行描述
---

{System Name}

{系统名称}

{Brief one-line description}
{简短的一行描述}

Overview

概述

{2-3 paragraphs explaining the system's purpose, why it exists, and its role in the larger system}
{2-3个段落，解释系统的用途、存在的意义以及它在更大系统中的角色}

Architecture

架构

{Describe the system structure}
{描述系统结构}

Components

组件

  • {Component A} - {description}
  • {Component B} - {description}
  • {组件A} - {描述}
  • {组件B} - {描述}

Data Flow

数据流

{How data moves through the system}
{数据如何在系统中流转}

Dependencies

依赖关系

  • {Dependency 1} - {why it's needed}
  • {Dependency 2} - {why it's needed}
  • {依赖项1} - {其必要性}
  • {依赖项2} - {其必要性}

API / Interface

API / 接口

Public Functions/Methods

公共函数/方法

functionName(params)

functionName(params)

{Description}
Parameters:
  • param1
    (type) - {description}
Returns: {description}
{描述}
参数：
  • param1
    (类型) - {描述}
返回值： {描述}

Commands

命令

{If applicable, document CLI commands}
{如果适用，记录CLI命令}

Configuration

配置

{Document configuration options}
{记录配置选项}

Behavior

行为

Normal Operation

正常操作

{How the system behaves under normal conditions}
{系统在正常条件下的行为}

Error Handling

错误处理

{How errors are handled}
{错误的处理方式}

Edge Cases

边缘情况

{Notable edge cases and how they're handled}
{值得注意的边缘情况及其处理方式}

Files

文件

Key implementation files:
  • path/to/main.ts
    - {brief description}
  • path/to/helper.ts
    - {brief description}
关键实现文件：
  • path/to/main.ts
    - {简短描述}
  • path/to/helper.ts
    - {简短描述}

Related Systems

相关系统

  • {Related System} - {relationship description}
undefined
  • {相关系统} - {关系描述}
undefined

Output

输出

After completing the research and documentation:
  1. Create/update the blueprint using 
    Write("blueprints/{system-name}.md", content)
  2. Report what was documented and any related systems that may need documentation
Note: The blueprint index at 
.claude/rules/blueprints/blueprints-index.md
is automatically regenerated by the SessionStart hook - you don't need to manually update it.
完成研究和文档编写后：
  1. 使用
    Write("blueprints/{system-name}.md", content)
    创建/更新蓝图
  2. 报告已文档化的内容以及任何可能需要文档化的相关系统
注意： 位于
.claude/rules/blueprints/blueprints-index.md
的蓝图索引会由SessionStart钩子自动重新生成——你无需手动更新它。