---
name: architecture-docs
description: >-
  判断项目是否需要架构文档，或生成、完善、审查 ARCHITECTURE.md 及已有架构说明。用于模块分工、状态归属、依赖关系或核心流程需要梳理时；依据项目证据记录结构，区分当前实现与已确认设计。
---

# 架构文档

先判断是否需要，再处理文档。目标是让接手者理解系统、判断修改影响；本 Skill 不替项目制定新的架构规范或改造代码。

## 1. 判断是否需要

读取已有入口、架构说明和本次相关资料；有代码时核对关键入口、配置、调用与状态写入，尚未开发时核对已确认设计。

- **需要新建**：模块分工、共享状态或跨模块流程不直观，接手或修改前需要反复探索，而现有资料没有可靠说明。
- **沿用现有文档**：已有可定位的架构主记录，先检查它是否够用，缺什么补什么，不因文件名不同再建一份。
- **暂不需要**：结构简单，现有入口和代码已能说明关系；简述依据及未来需要补充的信号。
- **证据不足**：列出影响判断的未知项；不要凭目录名猜结构，也不把缺少资料直接判为“不需要”。

例如：单个脚本读表后导出结果，通常不需要；订单横跨 API、队列和库存服务，状态由谁修改说不清，就值得记录架构。

输出结论、依据和建议位置。用户只问是否需要或要求审查时保持只读；生成、完善在既有授权范围内执行。

## 2. 写清关键关系

复用已有主记录；确需新建时可用根目录 `ARCHITECTURE.md`，参考 `templates/ARCHITECTURE.example.md`，只保留适用部分。模板中的分层和约束是示例，不是目标项目事实。

| 内容 | 写到什么程度 |
|---|---|
| 模块分工 | 关键模块各负责什么、真实入口在哪；不逐项登记普通目录 |
| 状态归属 | 关键数据由谁保存、谁能修改、通过什么路径修改；现有多方写入如实记录，问题另列 |
| 对外接口 | 调用方需要知道的接口入口和约束链接；字段、错误码留在机器契约或代码定义 |
| 依赖关系 | 记录实际依赖；已确认的允许／禁止依赖单独标明，不把建议当既有规则 |
| 核心流程 | 只解释不直观的主要链路；图中注明箭头含义，代码依赖与运行时数据流分开 |
| 可替换实现 | 确实存在多个实现或明确替换点时再记录，不为完整而补出抽象层 |

每项关系应能追溯到代码、配置或已确认设计。未实现的设计标为计划，证据不足标未验证；现状与约定冲突时分别记录，不替任一方编造一致性。

选择理由链接到 ADR，详细接口链接到契约；从项目现有入口或 MAP 链接架构主记录。内容过长时下沉模块细节，主记录保留总览和指针。

## 3. 核对是否有用

- 从一个关键业务流程出发，能否找到涉及的模块、状态和接口，并说明修改会影响哪些关系？
- 抽查关键关系与当前代码或确认材料是否一致；过时模块、漏记依赖和状态归属冲突列出具体位置与依据。
- 路径和链接是否有效，是否重复了其他主记录，是否混淆现状、计划与建议？

完成时返回必要性结论、采用的主记录、检查范围与发现。只读审查给建议；已授权修改后复核受影响关系与链接，明确剩余未知项。文档正确不等于代码架构合理，也不代表业务测试通过。