| name | architecture-doc |
| description | 指导在项目中编写、更新与使用架构文档（ARCHITECTURE.md）。在根目录维护架构文档，修改前后需阅读文档；文档关注最终结果与流程串联，不陷入实现细节。适用于新增/变更功能、重构、或需要理解系统整体时。 |
架构文档编写与使用
本 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、可插拔点、扩展新格式/新能力的入口说明 |
| 模块与职责 | 前端/后端按路由或层的模块划分，仅职责与边界，不列文件清单 |
具体文件与目录以代码仓库为准；架构文档只描述「做什么、和谁连」，不维护完整文件树。
工作流：开发与架构文档的配合
-
接到开发/重构任务时
- 读取项目根目录
ARCHITECTURE.md。
- 确认变更会影响哪些章节（模块、接口、数据流、流程等）。
-
设计与实现时
- 在实现中遵循文档中已写的边界与接口；若发现文档过时或错误，记录下来。
-
变更完成后
- 再次打开
ARCHITECTURE.md，根据实际变更更新对应章节。
- 若新增模块、接口或流程，在文档中补充；若删除或合并，从文档中移除或合并描述。
- 确保流程与串联关系（含 Mermaid 图）与当前实现一致。
-
评审或交接时
- 以「先读 ARCHITECTURE.md，再读代码」为推荐顺序，便于快速建立整体图景。
检查清单（更新架构文档后）
延伸阅读
