Improve Codebase Architecture

周期性架构健康检查：发现 shallow module → deep module 的深度化机会。目标是提升可测试性、AI 可导航性、模块边界清晰度。

与 XP-Gate 质量门禁的分工：

术语（与 XP-Gate Principles 一致）

核心判断工具

Deletion Test

想象删除某个模块：

• 如果复杂性消失 → 它是 pass-through，不值得保留
• 如果复杂性在 N 个调用方中重新出现 → 它真正提供了价值
• "Yes, concentrates" = 你想发现的信号

The Interface Is the Test Surface

接口就是测试的边界。如果测试需要深入实现细节，说明接口太浅。

One Adapter = Hypothetical Seam. Two Adapters = Real Seam.

只有一个实现满足接口 → 可能过度抽象。两个以上 → 真正的可替换边界。

流程

1. 探索

先读项目的 CONTEXT.md（领域语言）和 docs/adr/（架构决策）。

然后有机地走查代码库（不要遵循死板启发式），注意你在哪里感受到摩擦：

• 理解一个概念是否需要在多个小文件间跳来跳去？
• 模块是否 shallow — 接口几乎与实现一样复杂？
• 纯函数是否仅仅为了可测试性而被提取，但真正的 bug 隐藏在调用方式中？（缺乏 locality）
• 紧密耦合的模块是否在其 seams 之处泄漏？
• 哪些部分难以通过当前接口进行测试？

对任何怀疑 shallow 的模块执行 Deletion Test：删除它会让复杂性集中还是分散？"是的，会集中"就是你要的信号。

2. 呈现候选项

以编号列表呈现深度化机会。每项包含：

• Files — 涉及哪些文件/模块
• Problem — 当前架构为何造成摩擦（使用 CONTEXT.md 中的领域术语）
• Solution — 自然语言描述会怎样改变
• Benefits — 用 locality 和 leverage 解释收益，以及测试会怎样改善

使用 CONTEXT.md 领域术语。如果与 ADR 冲突，仅在摩擦值得重新讨论 ADR 时才标注：

"Contradicts ADR-0007 — 但值得重新打开，因为…"

不要列出 ADR 禁止的每个理论重构。

此时不要提出接口设计。先问用户："你想探索哪个候选项？"

3. 用户选择候选项

仅当用户明确选择某个候选项时，才进入步骤 4。

4. Grilling 循环（设计树遍历）

用户选中某个候选项后，进入 grilling 对话：

• 遍历约束、依赖、深度化模块的形状
• seam 背后放什么、什么不放在 seam 背后
• 哪些测试能在深度化后存活/新增

对话中的副作用（决策固化时立即执行）：

• 命名不在 CONTEXT.md 中的新概念 → 新增到 CONTEXT.md
• 模糊术语在对话中变清晰 → 更新 CONTEXT.md
• 用户拒绝候选项且有有理由 → 提议记录为 ADR（避免未来重复建议）
• 需要探索替代接口 → 按接口设计原则引导

5. 输出（可选）

如果用户在 grilling 后决定执行重构：

• 生成重构计划（含文件列表、步骤顺序、风险点）
• 调用 test-driven-development skill 执行重构（保持行为不变）

与 XP-Gate 集成

触发时机

Phase 5 (FEEDBACK) 后推荐调用：
  → learn + retro + **improve-codebase-architecture**
  → 发现架构摩擦 → 记录到 retro → 下一 Sprint 纳入 backlog

或作为独立周期性任务：
  → /improve-codebase-architecture  → 每周/开发潮后

与 ralph-loop 的关系

架构改进本身可以作为一个独立的 REQ 通过 ralph-loop 执行：

• REQ: "深度化 Order 模块（从 N 个散文件合并为 deep module）"
• 通过 test-driven-development 保证行为不变

与质量门禁的关系

架构改进后，质量门禁的 violation 数量应减少：

• God class → 拆分为 deep modules → SOLID-001 (SRP) 告警消失
• Deep nesting → 封装为简单接口 → CC-002 告警消失
• Code duplication → 提取公共 deep module → Gate 2 (Dup Code) 改善

Anti-Patterns

使用示例

/improve-codebase-architecture

→ Explore: 读取 CONTEXT.md, 走查代码库
→ 发现 3 个浅模块候选项
→ 呈现: #1 Order 模块过浅 / #2 Auth 适配器泄漏 / #3 支付领域缺乏 locality
→ 用户选中 #1
→ Grilling: 讨论 Order 的 seam 应该在哪
→ 更新 CONTEXT.md: 新增 "Order Intake" 术语
→ 提议 ADR: "Order 状态机封装" → 用户同意 → 创建 docs/adr/000X.md
→ 输出: 重构计划 → TDD 执行