/architecture-docs

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

架构文档

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

1. 判断是否需要

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

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

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

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

2. 写清关键关系

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

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

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

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

3. 模块文档与代码边界一致性

模块建档与约定维护的编排由 [module-governance](../module-governance/SKILL.md) 按用户意图选择；本 Skill 只承担架构说明和以下边界核对，纯审查不启动写入，也不定义领域词义。

证据核对步骤

模块入口写法委托 `agent-entrypoints`，术语与决策委托 `domain-modeling`，契约委托 `contract-first`。根 MAP／已有架构总览只保留模块路径和关系，不额外强制创建 CONTEXT-MAP。按本次影响范围执行以下核对，先只读，不凭实现反向批准设计：

1. **固定范围。** 记录提交或工作区版本、受影响模块及直接消费者；读取根／父级／模块入口及其契约、术语和生效决策。源码与说明缺失分别标未验证，不以目录名猜上下文。 2. **提取约定。** 找到职责、公开入口、私有实现、状态拥有者、允许／禁止依赖与跨上下文映射。区分 accepted、proposed 和历史决策；没有明确禁止规则时只报新增依赖待确认，不擅自判违规。 3. **逐条找代码证据。** 从实际导入、调用、路由／消息配置与数据写入追踪到目标定义，核对是否越过公共入口、修改他模块拥有的状态、遗漏消费者或改变契约。`rg` 命中仅是线索：补查重导出、路径别名、依赖注入和异步调用；动态路径无法确认就保留缺口。不要只检查文件名或注释。 4. **核对业务语义。** 对照术语适用范围、状态流转及测试，不把不同上下文合理的同名词判成冲突。代码与约定冲突同时展示两方证据；未经业务确认不改文档迁就代码，也不借审计重构实现。 5. **执行已有验证。** 复用项目已有依赖约束检查、契约测试和相关模块测试，记录命令、环境、范围、版本与退出码。入口长度用已有计数脚本。没有边界检测器时做明确范围的证据审查，不把全量文档审计通过等同于依赖／状态隔离通过；不自动安装新工具或 hook。 6. **交付并复验。** 每项写“模块／约定位置 → 代码证据 → 一致／冲突／未验证／不适用 → 建议与验证”。修复在已有授权内进行；业务取舍待确认。实际改动后由 `change-impact` 核对受影响关系、`docs-maintenance` 同步主记录，避免把本流程再次递归启动。

场景与预期结论见 [模块边界核对示例](examples/module-boundaries.md)。这是 Agent 证据审查工作流，不是通用 DDD 静态分析器；文档不能替代领域模型中的业务行为和可执行测试。

4. 核对是否有用

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

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