architecture-review

测试

运行 pytest plugins/pensive/tests/skills/test_architecture_review.py，验证评审逻辑。

架构评审工作流

依据 ADR 和设计原则进行架构评估。

快速开始

/architecture-review

适用场景

• 批准重新实现。
• 大规模重构评审。
• 系统设计变更。
• 引入新模块／服务。
• 调整依赖结构。

不适用场景

• 选择架构范式——使用架构原型 技能
• 评审 API 表面——使用 api-review
• 选择架构范式——使用架构原型 技能
• 评审 API 表面——使用 api-review

渐进式加载

根据评审范围加载模块：

• modules/adr-audit.md（约 400 个 token）：ADR 验证和文档。
• modules/coupling-analysis.md（约 450 个 token）：依赖分析和边界违规。
• modules/principle-checks.md（约 500 个 token）：代码质量、安全性和性能。
• modules/fpf-methodology.md（约 800 个 token）：FPF（功能、实践、基础）多视角评审方法。
• modules/ceremony-audit.md（约 600 个 token）：用于映射那些永不偏离的层的人工检查视角。直通映射器、孪生类型、推测性 DTO、仅有单一实现的接口。包含 IO 边界反向信号。

全面评审时加载所有模块。针对特定范围的评审，只加载相关模块。

必需的进度项

1. arch-review:context-established：已确认仓库、分支和动机。
2. arch-review:adr-audit：已验证 ADR 并确认新增 ADR 的需求。
3. arch-review:interaction-mapping：已分析模块耦合。
4. arch-review:invariant-check：已检测不变量冲突并分析 3 个选项。
5. arch-review:principle-checks：已检查 LoD、安全性和性能。
6. arch-review:ceremony-audit：已检查永不偏离的映射层。
7. arch-review:risks-actions：已提出建议和后续行动。
8. arch-review:findings-verified

工作流

步骤 1：确认上下文（arch-review:context-established）

确认仓库和分支：

pwd
git status -sb

记录：

• 推动本次评审的功能、缺陷或史诗任务。
• 受影响的子系统。
• README／文档中的架构意图。
• 设计权衡假设。

步骤 2：ADR 审计（arch-review:adr-audit）

加载：modules/adr-audit.md

• 查找项目中的 ADR。
• 验证必需章节。
• 检查状态流转。
• 确认符合不可变性要求。
• 标记新增 ADR 的需求。

步骤 3：交互映射（arch-review:interaction-mapping）

加载：modules/coupling-analysis.md

• 绘制模块交互的前后对比图。
• 验证组合边界。
• 检查数据所有权是否明确。
• 验证依赖流向。
• 识别耦合违规。

步骤 3.5：不变量冲突检测（arch-review:invariant-check）

在检查原则之前，先判断这些变更是否与现有设计不变量冲突。这是架构评审中最需要判断力的一步：模型在这一步出错的频率高于其他任何环节。

识别现有不变量：

1. 扫描 ADR，查找状态仍为“accepted”的已记录决策
2. 检查模块边界（导入是否跨越了此前未跨越的层？）
3. 检查数据流向（数据现在是否沿新的方向流动？）
4. 检查 API 契约（公共接口的形态是否发生变化？）
5. 检查结构模式（是否在现有模式旁引入了新模式？）

# Detect boundary crossings in changed files
git diff --name-only | while read f; do
  head -20 "$f" 2>/dev/null | rg "^(import|from|use |require)" || true
done

检测到冲突时：

不要建议解决方案。列出三个选项，并将问题交由人工判断：

选项	适用情况	不适用情况
保留不变量（拒绝功能）	不变量简化了许多事情；功能只是锦上添花	确实需要该功能，且不变量已过时
在其上叠加（以不够优雅的方式添加）	需要该功能；不变量仍有价值；可以接受不够完美	叠加会造成维护陷阱，并不断累积问题
修订不变量（更改设计）	新的认知确实使原有推理失效	你只是在“清理”一个自己并未完全理解的决策

输出格式：

### Invariant Conflicts

[I1] **[Invariant name]** — [what decision it represents]
- **Location**: file.py:42
- **Anchor**: `verbatim source text at line 42`
- **Conflict**: [what change clashes]
- **Options**: Preserve / Layer / Revise
- **Recommendation**: ESCALATE TO HUMAN
- **Risk if wrong**: [what compounds]

**为何重要：**糟糕的不变量决策会不断累积。几次错误判断后，代码库就会变得无可挽救。这是判断力问题，而非上下文问题：Agent 应该指出问题，而不是解决问题。

步骤 4：原则检查（arch-review:principle-checks）

加载：modules/principle-checks.md

• 德墨忒耳法则。
• 反劣质模式。
• 安全性（输入验证、最小权限）。
• 性能（N+1 查询、缓存）。

步骤 4.5：仪式性代码审查（arch-review:ceremony-audit）

加载：modules/ceremony-audit.md

耦合分析（步骤 3）会找出存在泄漏的边界。本步骤则查找相反的问题：有成本却没有起到隔离作用的边界。

• 字段全部是 1:1 复制的直通映射器。
• 跨层结构完全相同的成对类型。
• 形态没有外部契约约束的推测性 DTO。
• 恰好只有一个实现且没有测试替身的接口。

每项发现都必须说明这项仪式性代码当前满足什么需求。如果说不出当前需求，那么这项仪式性代码本身就是问题所在。

**不要标记 IO 边界上的映射器。**即使它们看起来只是直通映射器，也承担着重要作用，因为它们能阻止未来新增的内部字段泄漏出去。请参阅模块中的反向信号。

步骤 5：风险与行动（arch-review:risks-actions）

使用 imbue:diff-analysis/modules/risk-assessment-framework 总结：

• 当前架构与提议架构。
• 业务影响。
• 技术债影响。

列出后续事项，并注明负责人和日期。

提供建议：

• 批准：架构合理。
• 附带行动批准：有少量问题需要处理。
• 阻止：存在需要重新设计的根本性问题。

架构原则检查清单

耦合

• 依赖遵循既定边界。
• 没有循环依赖。
• 扩展点得到恰当使用。
• 抽象没有泄漏。

内聚

• 相关功能归类在一起。
• 每个模块职责单一。
• 模块用途明确。

分层

• 各层职责明确。
• 依赖自上而下流动。
• 没有绕过层级。

不变量

• 已识别现有设计不变量。
• 已指出变更与不变量之间的冲突。
• 已给出三种选项的分析（保留／叠加／修订）。
• 不变量变更已交由人工判断。
• 差异中没有悄然修订不变量。

演进

• 变更可逆。
• 迁移路径明确。
• ADR 已记录决策。

验证发现是否有依据（arch-review:findings-verified）

将发现写入 .review/findings.json，运行引文验证器 （Skill(imbue:review-core) 步骤 5），并删除验证器拒绝的发现，或将其标记为 UNVERIFIED。

退出标准

• 已建立上下文、完成 ADR 审查、完成交互映射、指出不变量冲突、运行原则检查，并记录风险和行动。
• 每项报告的发现都附有 Location 和逐字引用的 Anchor，并经 citation_verifier.py 确认（退出码为 0）；或者，未验证的发现已被删除或标记为 UNVERIFIED。