架构文档编写与使用

本 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（若存在）。