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.
Workflow
Stage 1: Scope Definition
Understand what to document before exploring:
- 1. 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.
Stage 2: Initial Exploration
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):
- 1. 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:
CODEBLOCK0
When the user confirms the scope, move on to deep research.
Stage 3: Deep Research
For each component in the approved outline:
- 1. 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.
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.
Stage 4: Document Draft
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.
Stage 5: Finalize
- 1. 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.
- 2. Write the final document to the confirmed location.
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.
INLINECODE2
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.
Mermaid Diagrams
Use Mermaid for architecture visualizations:
Flowcharts for component relationships:
CODEBLOCK3
Sequence diagrams for request flows:
CODEBLOCK4
Keep diagrams focused on the specific feature being documented. Avoid overcrowding
with unrelated components.
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.
描述设计
研究代码库并生成一份架构文档，描述功能或系统的工作方式。输出为Markdown格式文件，既适合人类阅读，也便于未来AI代理使用。
工作流程
第一阶段：范围定义
在开始探索前明确要记录的内容：
- 1. 询问需要记录的功能、系统或组件。
- 明确目标受众（开发者、AI代理或两者兼顾）。
- 确认代码库位置（若上下文未明确说明）。
第二阶段：初步探索
广泛探索代码库以构建心智模型。尽可能使用轻量级快速探索方法（例如在Claude Code中，可使用Haiku Explore子代理）：
- 1. 扫描目录结构，识别关键入口点。
- 阅读README、配置文件及现有文档。
- 识别与功能相关的主要文件和模块。
- 构建代码库组织方式的心智模型。
向用户呈现高层级大纲：
建议大纲
- 1. [组件A] - 简要描述
- [组件B] - 简要描述
- [组件C] - 简要描述
- * 我是否正确捕捉了研究范围？回复yes继续。
- 否则，请告知我理解有误之处。
用户确认范围后，进入深度研究阶段。
第三阶段：深度研究
针对已确认大纲中的每个组件：
- 1. 从入口点追踪代码路径。
- 识别组件间的依赖关系和交互。
- 记录配置选项及其定义位置。
- 查找数据存储或持久化位置。
- 构建代码引用索引（文件路径 + 关键函数/类名）。
尽量依赖初步代码探索获取大部分信息。根据需要读取额外文件。若第二阶段范围发生重大变化，可启用第二个代码探索子代理。
何时停止探索
当你能做到以下事项时，即可开始起草：
- - 追踪快乐路径 — 无间隙地追踪典型请求/操作从入口点到完成的全过程。
- 命名边界 — 清晰说明哪些在范围内，哪些是外部内容。
- 绘制图表 — 无需占位框即可勾勒架构。
- 回答什么与什么通信？ — 对每个组件，清楚其输入和输出。
尚未完成的迹象：
- - 不确定性：我认为这连接到……或可能调用……
- 未解决的引用：发现尚未检查的模块的导入/调用。
- 缺失的连接：无法解释数据如何从组件A到达组件B。
过度探索的迹象：
- - 读取目录中每个文件而非代表性样本。
- 追踪到外部库或框架内部。
- 探索不影响架构的实现细节。
第四阶段：文档起草
按照以下模板生成文档。将草稿呈现给用户审阅，并根据反馈进行迭代。若可用，使用AskUserQuestion工具就关键决策征求用户意见。
第五阶段：定稿
- 1. 写入前确认文件位置。 可根据仓库惯例建议路径（例如docs/architecture/、ARCHITECTURE.md），但未经用户明确确认位置，切勿写入文件。若用户预先提供了路径，则视为已确认。
- 将最终文档写入已确认的位置。
文档模板
以下模板提供起点。根据所记录的功能进行调整——省略不适用的部分，为独特方面添加章节，调整结构以最佳服务目标受众。
markdown
[功能/系统名称] 架构
概述
[1-2段摘要，说明该功能/系统的功能及存在原因]
架构图
mermaid
flowchart TD
A[入口点] --> B[组件]
B --> C[数据存储]
组件
[组件名称]
用途：[功能说明]
位置：path/to/file.ext
关键函数：
- - functionName() - 简要描述
- anotherFunction() - 简要描述
交互：
- - 接收来自：[组件] 的输入
- 发送输出至：[组件]
数据流
[描述数据如何在系统中流动，从输入到输出]
配置
[功能如何启用、禁用或配置。包含文件路径和环境变量。]
代码引用
| 组件 | 文件 | 关键符号 |
|---|
| 认证 | src/auth/index.ts | authenticate(), AuthConfig |
| 缓存 |
src/cache/redis.ts | CacheManager, invalidate() |
术语表
代码引用规范
使用能经受重构的稳定引用：
- - 路径：使用相对于仓库根目录的路径（src/auth/login.ts）
- 符号：引用函数和类名，而非行号
- 格式：path/to/file.ext，关键符号单独列出
- 锚点：必要时使用搜索模式（auth/中的handleAuth函数）
避免：
- - 复制代码：切勿将代码粘贴到文档中。代码会立即过时；文档应作为指南，引导读者查阅源码。描述代码功能，然后引用查找位置。
- 行号：每次编辑都会变化。
- 绝对路径：仅使用相对于仓库的路径。
Mermaid图表
使用Mermaid进行架构可视化：
流程图用于组件关系：
mermaid
flowchart TD
A[客户端] --> B[API网关]
B --> C[服务]
C --> D[(数据库)]
时序图用于请求流程：
mermaid
sequenceDiagram
客户端->>API: 请求
API->>服务: 处理
服务-->>API: 响应
API-->>客户端: 结果
保持图表聚焦于所记录的具体功能。避免用无关组件过度拥挤。
写作指南
- - 描述，绝不复制：解释代码的功能及查找位置。需要实现细节的读者将阅读实际源码——这始终是最新的。
- 便于扫描的结构：使用标题、表格和列表实现快速导航。
- 具体明确：包含实际文件路径、函数名和配置键。
- 服务两类受众：为人类清晰书写；为AI使用一致结构。
- 保持时效性：注明关于代码状态或版本的任何假设。
