6.4 KiB
name, description
| name | description |
|---|---|
| review-architecture | 仅用户指定 review-architecture 时启用；检查指定模块或整个项目的架构，输出有证据的优化建议，不修改代码。 |
检查架构与模块设计
完成条件：覆盖约定范围的五个检查维度，核实候选问题，保存包含证据、优化建议及检查限制的报告。不能在首次浏览或发现第一个问题后结束，也不为凑数找问题或在无新证据时反复检查。
仅检查并给出优化建议，不修改被审代码、配置、计划或质量门禁，不自动生成实施计划，不修复、提交或推送。允许只读调查、必要验证及写入外部报告；需改文件的验证在隔离副本中进行，不影响用户工作区，不执行有实际外部副作用的验证。可独立使用，不要求先运行其他 skill，不自动调用规划或实施流程。
范围与事实依据
- 用户指定模块时，先根据代码定位实际边界，检查模块内部并沿相关调用、依赖关系核实边界问题；需要追踪跨出模块再返回的依赖闭环时继续追踪，但不扩展为无关模块审计。存在多个合理候选模块时澄清。
- 未指定模块则检查整个项目，从业务模块、入口和依赖关系组织调查，覆盖项目自有代码及有关配置、测试；排除第三方依赖副本、构建产物等非维护源码。报告说明实际覆盖范围，不能以少数样本宣称全项目健康。
- 默认检查当前工作区，包括与范围相关的暂存、未暂存及未跟踪源码。记录项目位置、检查时间、分支、HEAD（或无提交）及工作区状态，不以 HEAD 快照代替工作区，不要求获取远程或比较 master。非 Git 项目记录可用定位即可。检查期间相关文件变化时复核受影响证据，并说明结论对应的状态。
- 按需读取适用项目规范、模块契约、测试和现有
CONTEXT.md；可从.agent/MEMORY.md读取外部资产定位，不维护 MEMORY 或 CONTEXT，不扫描历史计划。独立检查不自动继承其他任务的跳过决定；用户明确限定本次检查时记录排除项。 - 以实际入口、调用方、实现和依赖解析为依据，优先复用现有分析工具；工具不可用时可用静态证据继续，并标明不能验证的部分。
检查标准
Codex 可读性永远摆在第一位。 以理解职责、追踪行为及安全修改的成本判断，不以最少行数、最少文件或最小 diff 衡量。接受为清晰模块边界付出的初期过度工程化，不因抽象数量或只有一个实现就否定接口；新增或保留结构须能解释其职责及可读性、隔离或演进收益。
| 维度 | 检查重点 |
|---|---|
| Codex 可读性 | 业务入口、命名、模块职责及接口契约是否清晰；调用与数据流是否容易追踪，是否依赖过多跨文件跳转、隐式注册或隐藏状态才能理解行为。 |
| 循环依赖 | 核实模块及包之间的实际依赖闭环，给出路径和每条边的代码依据；区分运行时、类型或构建依赖及其影响。动态注册、反射等无法确认时说明限制，不凭目录或名称判定。 |
| 复杂度 | 嵌套、状态组合、间接调用、职责混杂及修改扩散是否增加理解和验证成本；指标只作为线索，不用固定阈值直接判坏。 |
| 架构健康度 | 业务职责是否模块化，同一业务规则是否有清晰归属；跨模块调用方是否仅感知公开接口而非内部实现，是否高内聚、低耦合。区分合理编排、公共能力复用与规则散落，不要求把整个业务链路塞进一个模块；通用架构能力不绑定具体业务。 |
| 逻辑分叉 | 同一业务规则是否有重复实现、行为漂移或新旧路径并存，条件和状态组合是否难以追踪；核实业务、兼容或迁移依据，不把每个条件分支或有意差异视为缺陷。 |
报告问题前核对实际可达路径、调用方保护、公开契约、有意设计及合法例外。循环依赖须展示闭环；规则重复或漂移须比较具体路径及其业务依据。合并同根因问题，区分已复现、静态确认与待核实疑点，不将假设写成事实。静态证据充分时无需强制复现，必要验证应围绕具体疑点。
优化建议说明目标职责、模块归属或接口边界如何改善，并给出收益、成本、影响范围、接口或兼容性影响及验证方向；不预写详细实现，不建议无证据的全面重构。不因发现问题就暂停其余检查索要修复许可，完成报告后由用户选择是否进入 align-plan。
保存报告与交付
复用用户指定的外部位置或已知资产定位；已有本次计划目录则放在其中，否则用已知资产根目录。不从计划父目录猜根目录，不扫描执行资产。位置缺失时询问，同时继续只读调查；位置不可用时报告保存阻碍，不回退被审项目，不宣称已保存，也不隐去已确认问题。
保存独立的 architecture-review-YYYYMMDD-HHmmss.md，使用用户当地检查时间，避免覆盖已有报告。顶部使用以下 YAML，未知字段留空，特殊值加引号：
---
系统: 系统名称
时间: YYYY-MM-DD
目标: 本次架构检查的模块或项目及优化目标
---
正文保持紧凑，包含：
- 范围与结论：项目、目标模块或全项目范围、检查时间、Git 基线与工作区状态；五个维度各自的结论、证据和未覆盖部分，明确用户排除项。
- 已确认问题与优化建议：按影响排序，标明检查维度、证据状态、文件与最小相关行范围、具体依赖或逻辑路径、后果；给出优化方向、收益、成本、影响范围、接口及兼容性影响和验证建议。
- 待核实项与验证限制：未证实的疑点、所缺证据、建议验证方式，以及本次实际命令、结果和未运行的检查。不粘贴完整日志，不虚构精确成本或健康评分。
代码、命令及多行配置用带语言标记的围栏代码块，路径与标识符用行内代码，原文引用注明来源；顶部 YAML 不套代码块。无发现时表述为“在已检查范围和证据内未发现需要报告的问题”，不等于全项目无技术债。
确认报告可读后，对话给重要发现、优化优先级、检查限制和文件绝对路径链接。交付报告即完成，不自动开始规划或重构。