architecture-doc

# 架构文档编写与使用

本 skill 指导在项目开发中如何编写、更新以及正确使用架构文档，使 AI 与开发者能基于同一份「系统真相」进行协作。

## 何时使用本 Skill

- 用户要求编写或更新架构文档
- 开发新功能、重构、或变更设计前，需要理解现有架构
- 完成代码/设计修改后，需要同步更新架构说明
- 用户提到「架构」「ARCHITECTURE」「系统设计」「流程」「模块关系」等

## 架构文档的位置与命名

- **路径**：项目根目录下的 `ARCHITECTURE.md`（以当前工作区/仓库根为准）
- 若项目根目录不存在该文件，在开始架构相关工作时应**先创建**该文件，再按本 skill 的规范编写内容。

## 核心原则

### 1. 修改前后必须阅读架构文档

- **修改前**：进行功能开发、重构或设计变更前，必须先阅读根目录的 `ARCHITECTURE.md`，理解当前系统边界、模块划分、数据流与关键接口。
- **修改后**：代码或设计变更若影响模块职责、接口、数据流或部署方式，必须在同一轮对话或任务中更新 `ARCHITECTURE.md`，保证文档与实现一致。

### 2. 关注最终结果，不关注中间流程

- 文档描述**系统对外表现**和**各模块的输入输出与职责**，而不是「某行代码先执行再执行」。
- 写「用户上传文档后，经解析、分段、向量化，最终可被检索」；不写「先调 A 函数再调 B 函数」。
- **不收录「按版本/阶段的迭代历史」**（如 Stage 1/2/3 Update、某日上线范围等）：这类内容描述的是中间过程与历史版本，不是当前系统的最终结果。若确需保留迭代记录，应放在文档末尾的附录（如「版本迭代记录」）中，**不要**放在系统概述或核心模块前。

### 3. 关注流程与串联，不局限于细节代码

- 强调**模块间如何衔接**：谁调用谁、数据从哪来到哪去、关键 API 与事件。
- 使用流程图（如 Mermaid）、数据流说明、接口列表来体现「流程和串联」。
- **不**在架构文档中罗列具体函数名、内部变量或实现细节；若需指向代码，只到「模块/目录/职责」级别，并注明「具体文件与目录以代码仓库为准」。

### 4. 保持可被 AI 与人类共同消费

- 结构清晰、小标题明确，便于检索与引用（如「§3.3 文档处理模块」）。
- 术语一致；新增概念在首次出现时简短定义。
- 列表与表格优先，长段落拆成要点。

## 建议的文档结构

可参考项目现有 `ARCHITECTURE.md`，按需裁剪或扩展。推荐包含：

| 章节 | 内容要点 |
|------|----------|
| 系统概述 | 定位、功能亮点、技术栈（仅写当前最终能力，不写版本/阶段迭代历史） |
| 系统架构 | 高层框图（如前端 / API / 后端领域 / 存储），Mermaid 等 |
| 核心模块 | 各模块职责、输入输出、与上下游的衔接，不写具体代码 |
| 数据模型 | 核心表/概念、数据流（谁生谁用）、存储结构、关键关系 |
| API 接口 | 按领域分组的接口列表与用途，可选请求/响应要点 |
| 关键业务流程 | 端到端流程（如初始化、上传、处理、提取），用步骤与流程描述 |
| 扩展性/抽象 | Provider、可插拔点、扩展新格式/新能力的入口说明 |
| 模块与职责 | 前端/后端按路由或层的模块划分，仅职责与边界，不列文件清单 |

具体文件与目录以代码仓库为准；架构文档只描述「做什么、和谁连」，不维护完整文件树。

## 工作流：开发与架构文档的配合

1. **接到开发/重构任务时**
   - 读取项目根目录 `ARCHITECTURE.md`。
   - 确认变更会影响哪些章节（模块、接口、数据流、流程等）。

2. **设计与实现时**
   - 在实现中遵循文档中已写的边界与接口；若发现文档过时或错误，记录下来。

3. **变更完成后**
   - 再次打开 `ARCHITECTURE.md`，根据实际变更更新对应章节。
   - 若新增模块、接口或流程，在文档中补充；若删除或合并，从文档中移除或合并描述。
   - 确保流程与串联关系（含 Mermaid 图）与当前实现一致。

4. **评审或交接时**
   - 以「先读 ARCHITECTURE.md，再读代码」为推荐顺序，便于快速建立整体图景。

## 检查清单（更新架构文档后）

- [ ] 修改前已阅读 `ARCHITECTURE.md`
- [ ] 文档中描述的模块职责、接口与数据流与当前实现一致
- [ ] 无新增的实现细节（如具体函数名、内部变量）；仅保留「最终结果」与「流程串联」
- [ ] 概述与核心章节**未**包含「按版本/阶段的迭代历史」（如 Stage 1/2/3 Update）；若有迭代记录则仅放在文档末尾附录
- [ ] 流程图与列表已随变更更新（若有）
- [ ] 术语与章节引用一致，便于 AI 与人类检索

## 延伸阅读

- 架构文档位于**项目根目录**，文件名为 `ARCHITECTURE.md`（具体路径以当前工作区为准）。
- 更细的写作约定与反例见 [references/conventions.md](references/conventions.md)（若存在）。