X Audit Arch

---
name: x-audit-arch
description: |
  独立架构巡检 skill。不在 x-dev → x-verify → x-qa-gate 主流程内，由用户手动触发或大里程碑后调用。
  调子 agent 做全项目视角的架构审查，核心两条主线：架构一致性（模块归属、边界类复用、分层、循环依赖、命名语义、错误处理一致性）与单一事实源（字段/枚举/默认值/prompt 规则/schema/文档是否多处重复维护并已漂移），辅以抽象合理性（奥卡姆，防过度设计）、模块契约清晰度、依赖方向健康。
  触发：用户说"架构巡检"、"audit arch"、"架构一致性检查"、"看看有没有重复的事实源"、"单一事实源检查"、"arch review"、"这块架构合不合理"，或大版本/重构里程碑后。
---

# x-audit-arch · 架构巡检

x-audit-arch 是独立巡检 skill，**不在 x-dev → x-verify → x-qa-gate 主流程内**。它由用户手动触发或大里程碑/重构后调用，做全项目视角的架构审查。

两条核心主线是用户最看重的：**架构一致性**（新代码守住项目既有的模块边界、分层、命名语义，而不是 AI 自己发明一套）和**单一事实源**（同一份关键信息只有一个权威来源，没有散落多处的重复定义）。其余维度（抽象合理性、契约、依赖健康）服务于这两条。

## 为什么独立

架构问题需要**全局视角**才有意义——单个文件本身没问题，但它把一个本该归属 A 模块的职责放进了 B 模块；单个 schema 定义没问题，但同一个枚举在三个地方各写了一份、已经开始漂移。这些都只有站在整个项目结构上看才暴露。塞进每个任务的 gate 会变成噪音，也看不到跨模块全貌，所以剥离成周期巡检。

## 与相邻 skill 的边界（避免重叠，必读）

| skill | 关注 | 与本 skill 的区别 |
|-------|------|------------------|
| x-qa-gate R1 | spec **正确性**：实现是否做了 spec 要的事 | R1 问"做对了吗"，本 skill 问"放对地方、符合项目结构吗"。功能正确但放错模块/破坏分层 → 归本 skill |
| x-audit-style | 表层规范：命名大小写、magic number、函数长度、死代码 | style 看**局部、战术**（这行代码风格）；arch 看**结构、战略**（这个职责该不该在这个模块）。命名只查**语义归属**（叫这个名字符不符合项目领域语义），大小写一致性归 style |
| x-audit-perf | 性能：复杂度、I/O、缓存 | 正交，互不重叠 |

最容易混的两处，按下面切：
- **重复代码**：两段近乎一样的代码块 → x-audit-style「复用机会」（提取函数）；同一份**事实源**（枚举/默认值/schema/规则）在多处各定义一份 → 本 skill「单一事实源」（收敛到唯一权威来源）。前者是战术去重，后者是结构性漂移风险。
- **命名**：snake/camel 大小写、缩写一致 → style；名字是否符合项目领域语义、有没有归属感（user/account/member 在本项目指同一概念却混用，导致读者误判模块边界）→ 本 skill。

## 流程

1. 用户触发（手动调用 / 大里程碑 / 重构后）。
2. dispatch 一个子 agent，prompt 包含本 SKILL.md 的检查清单 + 项目代码 + 输出格式。
3. 子 agent 输出 audit-arch 报告。
4. 写到 `reports/audit/audit-arch-YYYYMMDD-HHmmss.md`。
5. 不自动触发 x-fix——由用户决定哪些问题进入 backlog。架构改动影响面大，**必须人类裁决**，不要让巡检直接动手改结构。

## 审查范围

- 用户指定模块、目录、分层时，按指定范围执行。
- 用户只说 `x-audit-arch` / `架构巡检` 时，默认全项目视角（架构问题靠局部 diff 看不出来）。
- 范围太大时，先和用户确认聚焦哪几个模块/边界，避免泛泛而谈。

## 子 agent dispatch

```
Agent({
  description: "Architecture audit",
  subagent_type: "general-purpose",
  prompt: <本 SKILL.md 的"检查清单"段 + 项目代码 + 输出格式>
})
```

报告顶部必须填写 `Completed by model`。

## 取证原则（架构判断也要有证据）

架构问题最容易写成空泛的"建议解耦""感觉过度设计"。本 skill 要求每个问题都落到**可指认的证据**，否则不进报告：

- 指出具体文件 / 符号 / 行号，说明它**当前**在哪、**应该**在哪。
- 单一事实源问题必须列出**同一信息的所有副本位置**（≥2 处），并说明是否已经漂移（值不一致 / 改了一处忘了另一处的痕迹）。
- 循环依赖、分层破坏必须给出**依赖路径**（A → B → A），而不是只说"耦合高"。
- 过度抽象必须回答："删掉这一层，谁会坏？"——答不出谁会坏，就是过度抽象的证据。

没有证据的纯架构洁癖、个人审美偏好不写进报告。

## 检查清单

### 1. 架构一致性 — 模块归属与分层（重点）

判断新代码有没有放在它该在的地方、有没有守住既有分层。错位的职责会让模块边界慢慢糊掉，是架构腐化的最常见起点。

- **模块归属**：这段逻辑放在正确的模块/层了吗？业务规则跑进了工具层、数据访问混进了表现层、领域逻辑写在 controller 里？
- **分层方向**：依赖方向符合分层约定吗（上层依赖下层，下层不反向依赖上层）？有没有底层模块 import 了上层模块？
- **绕过既有抽象**：项目已有一个边界类/服务/门面（facade），新代码却绕过它直接调底层（直接拼 SQL 而不走 repository、直接读环境变量而不走 config 模块）？
- **错误处理一致性**：错误处理方式和项目其余部分一致吗（项目统一抛自定义异常，新代码却返回 null/error code）？日志、配置读取、参数校验的风格是否一致？

### 2. 架构一致性 — 边界类复用与命名语义（重点）

- **边界类复用**：项目已有承担这个职责的边界类/DTO/接口了吗？新代码是复用了，还是又造了一个近义的（`UserDTO` 已存在，又新增 `UserInfo`）？
- **命名语义归属**：名字符合项目的领域语义吗？同一概念在不同模块用了不同名字（user / account / member 实为一物却混用），会让读者误判它们是不同实体、跨错模块边界。
- **职责单一**：一个类/模块是不是承担了多个本该拆开的职责，导致它被多个不相关的方向同时依赖？

### 3. 单一事实源（重点）

同一份关键信息只应有一个权威来源。AI 很容易复制粘贴 schema、枚举、默认值、规则、prompt，短期能跑，长期必然漂移——改了一处忘了另一处，两份事实开始打架。这是本 skill 最高优先级的检查方向之一。

- **字段/schema 重复定义**：同一个数据结构在 dataclass、TypeScript interface、数据库 schema、API 文档里各写了一份？应以一个为权威源，其余派生或校验同步。
- **枚举/常量散落**：同一组状态码、枚举值、错误码在多处各定义一份？（本仓库 CLAUDE.md 的"状态枚举收敛到唯一真源"就是这条的实例。）
- **默认值多处**：同一个默认值（超时时间、重试次数、路径前缀）硬编码在多个文件里？改一处就漏其余。
- **规则/prompt 复制**：同一条业务规则、校验逻辑、prompt 模板被复制了多个版本？它们之间已经出现差异了吗？
- **文档与代码漂移**：README/spec/注释里描述的字段、行为、契约，和代码实际实现是否已经对不上？
- **已漂移的证据**：重点标记那些**副本之间值已经不一致**的——这是单一事实源缺失已经造成实际损害的硬证据，优先级最高。

### 4. 抽象合理性（奥卡姆 / 最小充分）

防止 AI 写出"看起来很完整、实际难维护"的过度设计。注意：奥卡姆不是"永远选最简单的"，而是"满足需求前提下不引入不必要的复杂度"。

- **过度抽象**：有没有只有一个实现的接口/基类/工厂？有没有为想象中的未来需求预留的扩展点（插件系统、策略模式）却从未用到？
- **不必要的层**：删掉某一层（一个只做转发的 service、一层薄封装），系统会不会更清楚？判据：删了之后**谁会坏**？答不出就是多余。
- **配置膨胀**：简单需求被做成了"配置中心 + 热更新 + 多租户"这类远超当前需要的方案？
- **最小充分改动残留**：能看出某次改动"顺手重构了无关模块"留下的痕迹（无关文件被动、引入了和本次需求无关的新抽象）？

### 5. 契约清晰度（契约优先）

模块之间的边界契约是否清楚——输入/输出/错误/是否可空/是否有副作用。契约模糊会让调用方各自猜测，是后续 bug 的温床。

- 公开接口的输入输出类型是否明确，还是大量 `any` / `dict` / 裸 map 传递？
- 错误是怎么返回的，调用方知道要处理哪些失败吗（契约里有没有声明可能抛的异常/错误）？
- 是否有副作用、是否修改全局状态，从签名/文档能看出来吗？
- 同一个契约被多个调用方依赖时，它是不是一个清晰的、有名字的边界，还是隐式约定？

### 6. 依赖健康

- **循环依赖**：模块 A → B → A 或更长的环？给出完整依赖路径。
- **耦合方向**：稳定的核心模块反向依赖了易变的外围模块？
- **依赖泄漏**：底层实现细节（具体的库类型、数据库行对象）泄漏到了公开接口/跨模块边界上？

## 严重度分级

架构问题一般不是即时生产事故（那归 x-cr / x-qa-gate），而是**可维护性与腐化风险**，所以用 P1/P2/P3：

| 等级 | 含义 | 典型 |
|------|------|------|
| P1（架构债，强烈建议修） | 已经造成或即将造成漂移/腐化的结构问题 | 多事实源**已漂移**、循环依赖、破坏分层、绕过既有抽象自造一套并行体系 |
| P2（建议修） | 结构不当但暂未造成损害 | 模块归属不当、命名不符语义、契约模糊、尚未漂移的重复定义、可疑的过度抽象 |
| P3（信息性） | 轻微、可选 | 轻度过度封装、可选的边界类复用机会、命名语义的小改进 |

## 输出

写入 `reports/audit/audit-arch-YYYYMMDD-HHmmss.md`，模板见 `templates/audit-arch-template.md`。

- 在 task 目录中执行：`dev-pipeline/tasks/<task>/reports/audit/audit-arch-YYYYMMDD-HHmmss.md`
- 在普通仓库范围执行：`reports/audit/audit-arch-YYYYMMDD-HHmmss.md`

## 不在范围

- **功能正确性**：实现做没做对 spec 要的事，归 x-qa-gate R1 / x-cr。本 skill 只看"放对地方、符不符合结构"。
- **表层规范**：命名大小写、magic number、函数长度、死代码，归 x-audit-style。
- **性能**：复杂度、I/O、缓存，归 x-audit-perf。
- **单任务级别的小范围结构审查**：小改动看不出架构问题，等里程碑后整体巡检。
- **个人审美 / 架构洁癖**：没有"会导致漂移或腐化"证据的纯偏好，不写进报告。
- **直接动手改架构**：本 skill 只出报告，结构性改动影响面大，必须人类裁决后再走 x-fix。