描述系统设计

调研一个代码库，并产出一份架构文档，说明某个功能或系统的工作原理。输出为一个 Markdown 文件，其组织方式需同时兼顾人类读者与未来 AI 智能体的阅读需求。

工作流程

阶段 1：范围定义

在深入探索代码库前，先明确需要记录的内容：

1. 明确需文档化的具体功能、系统或组件。
2. 厘清目标读者（开发者、AI 智能体，或两者兼顾）。
3. 若上下文未明确指出代码库位置，则需确认其所在路径。

阶段 2：初步探索

对代码库进行广度优先的快速探索，构建整体认知模型。如有条件，应优先采用轻量、高效的方式（例如在 Claude Code 中调用 Haiku Explore 子智能体）：

1. 浏览目录结构，识别关键入口点。
2. 通读 README、配置文件及现有文档。
3. 定位与该功能相关的核心文件和模块。
4. 建立对代码库整体组织结构的初步心智模型。

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

## 拟定提纲

1. [组件 A] — 简要说明
2. [组件 B] — 简要说明
3. [组件 C] — 简要说明

* 我是否准确把握了本次调研的范围？请回复 "yes" 继续。
* 否则，请指出我理解有误之处。

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

阶段 3：深度研究

针对已批准提纲中的每个组件，执行以下操作：

1. 从入口点出发，追踪代码执行路径。
2. 识别组件间的依赖关系与交互方式。
3. 记录配置项及其定义位置。
4. 定位数据存储或持久化的位置。
5. 构建代码引用索引（含文件路径 + 关键函数/类名）。

尽可能复用阶段 2 初步探索所得信息；必要时再按需阅读额外文件。若阶段 2 中范围发生显著变化，可调用第二个代码探索子智能体协助。

何时停止探索

满足以下全部条件时，即可开始撰写初稿：

• 可完整追踪“主路径”（happy path） —— 能从典型请求/操作的入口点出发，无中断、无遗漏地追踪至完成。
• 边界清晰 —— 明确界定哪些内容属于当前文档范围，哪些属于外部依赖。
• 可绘制架构图 —— 能手绘出不含占位符框的架构示意图。
• 能回答“谁与谁通信？” —— 对每个组件，均清楚其输入来源与输出去向。

尚未完成的迹象：

• 存在不确定性表述，如：“我认为它连接到……” 或 “大概会调用……”
• 存在未解析的引用，例如发现导入/调用了尚未调研的模块。
• 存在缺失的数据流向，例如无法解释数据如何从组件 A 流向组件 B。

探索过度的迹象：

• 逐个阅读目录下所有文件，而非选取代表性样本。
• 深入追踪外部库或框架内部实现。
• 过度关注不影响架构层面的底层实现细节。

阶段 4：文档初稿

依据下方模板生成文档初稿。将初稿提交给用户审阅，并根据反馈迭代修改。若支持，可使用 AskUserQuestion 工具就关键决策向用户征询意见。

阶段 5：定稿

1. 写入前务必确认文件路径。 可依据仓库惯例建议路径（例如 docs/architecture/ 或 ARCHITECTURE.md），但 绝不可未经用户明确确认路径即写入文件。若用户已在前期提供路径，则视为已确认。
2. 将最终文档写入已确认的路径。

文档模板

以下模板为起点，需根据所记录的功能灵活调整：删除不适用章节，补充独特环节，并优化结构以更好服务目标读者。

# [功能/系统名称] 架构

## 概述

[用 1–2 段文字概括该功能/系统的作用及其存在原因]

## 架构图

```mermaid
flowchart TD
    A[入口点] --> B[组件]
    B --> C[数据存储]
```

## 组件

### [组件名称]

**用途**：[该组件的功能说明]

**位置**：`path/to/file.ext`

**关键函数**：
- `functionName()` — 简要说明
- `anotherFunction()` — 简要说明

**交互关系**：
- 接收自：[组件]
- 发送至：[组件]

## 数据流

[描述数据在系统中从输入到输出的流转过程]

## 配置

[功能启用、禁用或配置的方式。包括文件路径与环境变量。]

## 代码引用

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

## 术语表

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

代码引用规范

使用可抵御重构的稳定引用方式：

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

请避免：

• 复制代码：切勿将代码粘贴进文档。代码极易过时；文档应作为指向源码的导航指南。应描述代码功能，再指明其所在位置。
• 行号：每次编辑都会导致行号变更。
• 绝对路径：仅使用相对于仓库根目录的路径。

Mermaid 图表

使用 Mermaid 编写架构可视化图表：

流程图（flowchart）用于表达组件间关系：

flowchart TD
    A[客户端] --> B[API 网关]
    B --> C[服务]
    C --> D[(数据库)]

序列图（sequenceDiagram）用于表达请求处理流程：

sequenceDiagram
    客户端->>API: 请求
    API->>服务: 处理
    服务-->>API: 响应
    API-->>客户端: 结果

图表应聚焦于当前所记录的具体功能，避免混入无关组件造成信息过载。

写作指南

• 重描述，不复制：说明代码作用及查找位置即可。需要实现细节的读者会直接查阅源码——而源码永远是最新的。
• 便于快速浏览：善用标题、表格与列表提升导航效率。
• 保持具体：注明真实文件路径、函数名与配置项键名。
• 兼顾两类读者：面向人类读者需语言清晰；面向 AI 智能体需结构一致、可解析。
• 保持时效性：注明关于代码状态或版本的任何假设。