用途
Architecture Audit 是一个只读的代码库架构审计技能。它读取整个项目——代码、文档以及其他使其可构建的文件——并报告其设计是否合理、文档是否仍能描述代码、是否遵循 YAGNI/KISS/SOLID，以及新加入者能否轻松构建并扩展它。它是只读的：只产出按优先级排列、便于快速浏览的建议报告和结论，绝不修改代码。报告可交给开发工作流去执行。该技能与框架和语言无关：它推理的是分层、契约和接缝，而不是任何单一技术栈。
主要能力
审计包含五条轨道，按范围运行：
- A. 架构与边界——分层、依赖方向、内聚性。
- B. 文档保真度——文档是否仍与代码、脚本和配置一致。
- C. 设计原则——YAGNI / KISS / SOLID，给出具体违规和具体优点。
- D. 可扩展性与可构建性——新加入者能否按文档从源码构建并添加新的 provider/plugin/module。
- E. 测试与护栏——检查是否位于正确的层，是否在漂移时大声失败。
使用方式
技能强调“读取真实流程，不要猜测”。每条发现都引用证据——file:line、读取过输出的命令、零命中的 grep、缺失的漂移防护。在判断之前先端到端追踪流程。一个“看起来像上帝模块”的文件只是线索；要通过统计它融合的不同关注点数量来确认，而不是看行数。
内置文件（按需加载）：references/design-vocabulary.md——模块形态的共享词汇（module、interface、implementation、depth、seam、adapter、leverage、locality），使用它们的测试（deletion test、“接口即测试面”、一个适配器意味着假设接缝而两个意味着真实接缝），决定加深模块如何测试的依赖类别，以及 design-it-twice 过程。在编写任何 Track A 或 Track C 发现之前阅读它，并使用这些词而不是发明同义词；兄弟技能针对同一词汇报告。
范围与方法：
- 确立范围——整个仓库，或指定子系统。明确说明；“架构”没有边界就没有意义。
- 先映射再判断——列出顶层模块并绘制依赖/数据流方向（简短分层图）。健康代码库的依赖指向一个方向；记录每个回边和循环。这张图也是发现扩展接缝和上帝模块的方式。位于仓库之外的业务逻辑——存储过程、触发器、宿主或控制台中定义的调度和 cron 作业、外部 ETL——仍作为命名框出现在图上，并连同其所在位置（数据库、调度器、管道工具）列入 NOT ASSESSED 列表，而不是从图上消失；遗漏它的图会显示系统并不存在的流程。
- 在提出任何建议之前，先阅读已记录的决策——ADR（docs/adr/ 或仓库保存它们的位置）、被拒绝想法目录如 .out-of-scope/，以及项目自己的词汇表（CONTEXT.md、领域文档，或代码和测试已使用的术语）。三个后果：与已接受 ADR 矛盾的建议会作为矛盾浮出（“与 ADR-0007 矛盾，值得重新讨论，因为……”），而不是当作决策从未做出那样提出；与所有者已拒绝内容匹配的建议要么放弃，要么针对记录的理由进行论证，因为每次审计都重新提出它是报告失去权威的方式；每条发现都用项目自己的话命名领域概念，因为用发明词汇写的报告会让读者付出翻译成本。这些文件不存在时，静默继续——它们的缺失本身不是发现。
- 通过执行验证，而非散文——当文档命名命令时，运行它；当它命名文件、符号或标志时，打开它。被引用但缺失的脚本或过时示例是发现，不是舍入误差。
- 零命中 ≠ 不存在——ripgrep 和基于 ripgrep 的搜索遵循 .gitignore，因此从忽略嵌套包、vendored 代码或构建输出的根目录搜索，即使存在匹配也返回空。在断定符号或调用者不存在之前，重新扫描限定到子目录，或关闭忽略规则。
- 委派广度，保留结论——在大树上，按子系统展开只读探索者（后台、UI、文档保真度……）并综合；不要用文件转储淹没一个上下文。先构建依赖图（步骤 2）——它是每个探索者共享的冻结简报，也是综合者解决跨子系统边的地方。集中运行项目自己的构建/测试门（Track B 和 E），绝不在并行探索者内部——并发套件运行会冲突。资源预检（在展开之前）：将并发上限设为 min((cores−1)×0.75, free_gb×0.7/per_agent, 6)，per_agent ≈ 0.7 GB 只读，或如果探索者运行构建/测试则为 1.5 GB；如果 CPU 负载 > 85% 或空闲 RAM < 2×per_agent，则串行；每波之前重新计算；运行时自身限制子代理并发时，遵从它。
- 评分、门控、报告——见输出。
完成条件：范围已说明，依赖图已绘制，范围内每条轨道都已走完，任何未读或未运行的内容都在 NOT ASSESSED 列表上，而不是猜测。
适用场景
适用于需要评估整个代码库或指定子系统架构健康度的场景，包括：检查模块边界与依赖方向、验证文档与代码是否一致、评估设计原则遵循情况、判断新贡献者能否按文档构建和扩展、检查测试与护栏是否位于正确层并在漂移时失败。也适用于在扩大贡献者数量或开源之前进行架构审查。
限制
- 只读：绝不修改代码，只产出报告和结论。
- 与框架和语言无关，不针对特定技术栈。
- 不评估：特定漏洞（→ awesome-security-audit）、运行时延迟/内存（→ awesome-performance-audit）、公共客户端泄露（→ awesome-leak-audit）、注释/命名清理（→ awesome-code-cleanup）。
- 不标记：被误认为臃肿的本质复杂性、基于品味的重写、格式化器/linter 拥有的风格、两次出现称为“重复”、实际被使用的抽象、没有产物的“感觉不对”。
- 没有产物时返回 NOT ASSESSED，而不是猜测。
- 结论分为 SHIP（设计合理且可扩展，只剩快速胜利和笔记）、FIX（存在真实结构或保真度问题，有明确所有者和方向，在扩大贡献者数量或开源之前解决）、BLOCK（分层反转、损坏的“从源码构建”或私有依赖泄露，阻止项目按文档构建或安全扩展）。
- 每条发现按影响和范围标注严重性 Critical / High / Medium / Low；Critical 保留给“阻止构建或扩展”。
- 每条发现标注置信度 High（通过运行命令或阅读每个相关文件确认）或 Medium（从结构推断而未完整阅读）；Medium 发现列在 Needs verification 下。
输出格式
以结论和范围开头，然后是按优先级排列、便于快速浏览的报告——读者应在几秒内找到最高价值行动。
Architecture Audit — <repo / subsystem> — <date> Verdict: SHIP | FIX | BLOCK (overall, or per track)
Architecture at a glance: <3–8 line layered map: which module depends on which, one arrow per edge>
Recommendations (most valuable first, grouped by effort/risk): Quick wins (low risk, high value) - [track B] <file:line / command> — <what's wrong> — <fix direction> — severity Structural (bigger, worth it) - [track A] <file:line> — <the concern-fusion / cycle> — <split direction> — severity Leave as-is (essential complexity — do NOT touch, and why) - <file> — <why the size/complexity is earned>
Not assessed: <what lacked evidence — unrun suite, unread subsystem — and why>