describe-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Describe Design

描述设计

Research a codebase and produce an architectural document describing how features or systems work. The output is a markdown file organized for both human readers and future AI agents.

研究代码库并生成架构文档，说明功能或系统的工作原理。输出为Markdown文件，兼顾人类读者和未来AI Agent的使用需求。

Workflow

工作流程

Stage 1: Scope Definition

阶段1：范围定义

Understand what to document before exploring:

Ask what feature, system, or component to document.
Clarify the target audience (developers, AI agents, or both).
Confirm the codebase location if not obvious from context.

在开始探索前，明确需要文档化的内容：

询问需要文档化的功能、系统或组件是什么。
明确目标受众（开发人员、AI Agent，或两者兼顾）。
若上下文未明确说明，确认代码库的位置。

Stage 2: Initial Exploration

阶段2：初步探索

Explore the codebase broadly to build a mental model. Use lightweight, fast exploration methods when available (in Claude Code, for example, use a Haiku Explore subagent):

Scan directory structure and identify key entry points.
Read README, config files, and existing documentation.
Identify the main files and modules related to the feature.
Build a mental model of codebase organization.

Present a high-level outline to the user:

undefined

广泛探索代码库，建立整体认知模型。若有可用的轻量快速探索方法（例如在Claude Code中使用Haiku Explore子Agent），可优先采用：

扫描目录结构，识别关键入口点。
阅读README、配置文件和现有文档。
确定与目标功能相关的主要文件和模块。
建立代码库组织架构的认知模型。

向用户呈现一份高层级大纲：

undefined

Proposed Outline

拟议大纲

[Component A] - Brief description
[Component B] - Brief description
[Component C] - Brief description

Have I correctly captured the scope of the research? Reply "yes" to continue.
Otherwise, please let me know what I've misunderstood.


When the user confirms the scope, move on to deep research.

[组件A] - 简要说明
[组件B] - 简要说明
[组件C] - 简要说明

我是否准确把握了研究范围？回复“yes”以继续。
若有偏差，请告知我理解有误的地方。


用户确认范围后，进入深度研究阶段。

Stage 3: Deep Research

阶段3：深度研究

For each component in the approved outline:

Trace code paths from entry points.
Identify dependencies and interactions between components.
Note configuration options and where they're defined.
Find where data is stored or persisted.
Build a code reference index (file paths + key function/class names).

Try to rely on the initial code exploration for much of this information. Read additional files as needed. If the scope changed considerably in Stage 2, you can engage a second code exploration subagent.

针对已确认大纲中的每个组件：

从入口点追踪代码路径。
识别组件之间的依赖关系和交互逻辑。
记录配置选项及其定义位置。
建立代码引用索引（文件路径 + 关键函数/类名称）。

此阶段可主要依赖初步探索获取的信息，按需阅读额外文件。若阶段2中范围发生较大变化，可调用第二个代码探索子Agent。

When to Stop Exploring

探索终止条件

You're ready to draft when you can:

Trace the happy path — Follow a typical request/action from entry point to completion without gaps.
Name the boundaries — Clearly state what's in scope and what's external.
Draw the diagram — Sketch the architecture without placeholder boxes.
Answer "what talks to what?" — For each component, you know its inputs and outputs.

Signs you're not done:

Uncertainty: "I think this connects to..." or "probably calls..."
Unresolved references: Found imports/calls to modules you haven't examined.
Missing edges: Can't explain how data gets from component A to B.

Signs you've gone too far:

Reading every file in a directory instead of representative samples.
Tracing into external libraries or framework internals.
Exploring implementation details that don't affect architecture.

当你满足以下条件时，即可开始起草文档：

追踪正常流程 — 能够完整追踪典型请求/操作从入口点到完成的全流程，无信息缺口。
明确边界 — 清晰说明范围内内容和外部依赖。
绘制架构图 — 无需占位框即可勾勒出架构图。
回答“组件间如何交互？” — 了解每个组件的输入和输出对象。

未完成的信号：

存在不确定性：“我认为这连接到...”或“可能调用...”
未解析的引用：发现了尚未检查的模块导入/调用。
缺失关联逻辑：无法解释数据如何从组件A传递到组件B。

过度探索的信号：

阅读目录中所有文件而非代表性样本。
追踪到外部库或框架内部实现。
探索不影响架构的实现细节。

Stage 4: Document Draft

阶段4：文档草稿

Generate the document following the template below. Present the draft to the user for review and iterate based on feedback. If available, use the AskUserQuestion tool to request user input on key decisions.

按照以下模板生成文档。将草稿提交给用户审核，并根据反馈迭代优化。若有可用工具，可使用AskUserQuestion工具请求用户对关键决策提供输入。

Stage 5: Finalize

阶段5：最终定稿

Confirm the file location before writing. You may propose a path based on repository conventions (e.g.,
```
docs/architecture/
```
,
```
ARCHITECTURE.md
```
), but NEVER write the file without explicit user confirmation of the location. If the user provided a path upfront, that counts as confirmation.
Write the final document to the confirmed location.

写入前确认文件位置。你可根据仓库约定建议路径（例如
```
docs/architecture/
```
、
```
ARCHITECTURE.md
```
），但必须获得用户对位置的明确确认后才能写入文件。若用户预先提供了路径，则视为已确认。
将最终文档写入已确认的位置。

Document Template

文档模板

The following template provides a starting point. Adapt it to fit the feature being documented — omit sections that don't apply, add sections for unique aspects, and adjust the structure to best serve the target audience.

markdown

undefined

以下模板为基础框架，可根据待文档化的功能进行调整——省略不适用的章节，为独特内容添加新章节，调整结构以更好地服务目标受众。

markdown

undefined

[Feature/System Name] Architecture

[功能/系统名称]架构

Overview

概述

[1-2 paragraph summary of what this feature/system does and why it exists]

[1-2段文字总结该功能/系统的作用及存在意义]

Architecture Diagram

架构图

mermaid

flowchart TD
    A[Entry Point] --> B[Component]
    B --> C[Data Store]

mermaid

flowchart TD
    A[Entry Point] --> B[Component]
    B --> C[Data Store]

Components

组件

[Component Name]

[组件名称]

Purpose: [What it does]

Location:

path/to/file.ext

Key Functions:

```
functionName()
```
- Brief description
```
anotherFunction()
```
- Brief description

Interactions:

Receives input from: [Component]
Sends output to: [Component]

用途：[组件功能说明]

位置：

path/to/file.ext

关键函数:

```
functionName()
```
- 简要说明
```
anotherFunction()
```
- 简要说明

交互关系:

接收来自：[组件]的输入
输出至：[组件]

Data Flow

数据流

[Description of how data moves through the system, from input to output]

[描述数据在系统中的流转路径，从输入到输出]

Configuration

配置说明

[How features are enabled, disabled, or configured. Include file paths and environment variables.]

[功能的启用、禁用或配置方式，包含文件路径和环境变量]

Code References

代码引用

Component	File	Key Symbols
Auth	`src/auth/index.ts`	`authenticate()` , `AuthConfig`
Cache	`src/cache/redis.ts`	`CacheManager` , `invalidate()`

组件	文件	关键符号
Auth	`src/auth/index.ts`	`authenticate()` , `AuthConfig`
Cache	`src/cache/redis.ts`	`CacheManager` , `invalidate()`

Glossary

术语表

Term	Definition
[Term]	[Project-specific definition]

undefined

术语	定义
[术语]	[项目特定定义]

undefined

Code Reference Conventions

代码引用规范

Use stable references that survive refactoring:

Paths: Use relative paths from repository root (
```
src/auth/login.ts
```
)
Symbols: Reference function and class names, not line numbers
Format:
```
path/to/file.ext
```
with key symbols listed separately
Anchors: Use search patterns when helpful (
```
handleAuth function in auth/
```
)

Avoid:

Copying code: Never paste code into the document. Code goes stale immediately; the document should be a guide that points readers to the source. Describe what code does, then reference where to find it.
Line numbers: They change with every edit.
Absolute paths: Use repository-relative paths only.

使用可在重构后依然有效的稳定引用：

路径：使用相对于仓库根目录的路径（
```
src/auth/login.ts
```
）
符号：引用函数和类名称，而非行号
格式：
```
path/to/file.ext
```
单独列出关键符号
锚点：必要时使用搜索模式（
```
auth/中的handleAuth函数
```
）

需避免：

复制代码：切勿将代码粘贴到文档中。代码会立即过时；文档应作为指引，引导读者查看源代码。说明代码功能，然后引用其位置。
行号：行号会随每次编辑而变化。
绝对路径：仅使用相对于仓库的路径。

Mermaid Diagrams

Mermaid图表

Use Mermaid for architecture visualizations:

Flowcharts for component relationships:

mermaid

flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]

Sequence diagrams for request flows:

mermaid

sequenceDiagram
    Client->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>Client: Result

Keep diagrams focused on the specific feature being documented. Avoid overcrowding with unrelated components.

使用Mermaid进行架构可视化：

流程图用于展示组件关系：

mermaid

flowchart TD
    A[Client] --> B[API Gateway]
    B --> C[Service]
    C --> D[(Database)]

时序图用于展示请求流程：

mermaid

sequenceDiagram
    Client->>API: Request
    API->>Service: Process
    Service-->>API: Response
    API-->>Client: Result

图表应聚焦于待文档化的特定功能。避免加入无关组件导致过度拥挤。

Writing Guidelines

写作指南

Describe, never copy: Explain what code does and where to find it. Readers who need implementation details will read the actual source — which is always current.
Structure for scanning: Use headers, tables, and lists for quick navigation.
Be specific: Include actual file paths, function names, and config keys.
Serve two audiences: Write clearly for humans; use consistent structure for AI.
Stay current: Note any assumptions about code state or version.

描述而非复制：解释代码的功能及其位置。需要实现细节的读者会查看始终最新的源代码。
为快速浏览优化结构：使用标题、表格和列表便于快速导航。
内容具体：包含实际文件路径、函数名称和配置键。
兼顾两类受众：为人类读者撰写清晰内容；为AI Agent使用一致结构。
保持时效性：记录关于代码状态或版本的假设。