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。