Back to Details

improve-codebase-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Improve Codebase Architecture

改进代码库架构

Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones. Goal: testability and AI-navigability.
识别架构摩擦并提出深化改进机会——即通过重构将浅模块转化为深模块。目标：提升可测试性和AI可导航性。

Vocabulary (use these terms exactly)

术语表（请严格使用以下术语）

  • Module — anything with an interface and implementation (function, class, package, slice)
  • Interface — everything a caller must know: types, invariants, error modes, ordering, config
  • Depth — leverage at the interface: much behavior behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation
  • Seam — where an interface lives; a place behavior can be altered without editing in place
  • Adapter — a concrete thing satisfying an interface at a seam
  • Leverage — what callers get from depth
  • Locality — what maintainers get from depth: change, bugs, knowledge concentrated in one place
Key principles:
  • Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
  • The interface is the test surface.
  • One adapter = hypothetical seam. Two adapters = real seam.
  • Module —— 任何具有接口和实现的单元（函数、类、包、代码片段）
  • Interface —— 调用者必须了解的所有信息：类型、不变量、错误模式、调用顺序、配置
  • Depth —— 接口的杠杆作用：简洁接口背后承载大量行为。Deep（深） = 高杠杆作用。Shallow（浅） = 接口复杂度几乎与实现相当
  • Seam —— 接口所在的位置；无需原地修改即可变更行为的地方
  • Adapter —— 在Seam处满足接口要求的具体实现
  • Leverage —— 调用者从Depth中获得的价值
  • Locality —— 维护者从Depth中获得的价值：变更、Bug、知识集中在一处
核心原则：
  • 删除测试：假设删除该模块。如果复杂度随之消失，说明它只是一个传递层。如果复杂度分散到N个调用者中重新出现，说明它有存在的价值。
  • 接口即测试面。
  • 一个Adapter = 假设性Seam。两个Adapter = 真实Seam。

When to use this skill

适用场景

  • User wants architectural improvement opportunities
  • Codebase is hard to navigate or test
  • Modules feel tightly coupled or shallow
  • Refactoring would improve testability
  • 用户希望获得架构改进机会
  • 代码库难以导航或测试
  • 模块存在紧耦合或过于浅显的问题
  • 重构可提升可测试性

When not to use this skill

不适用场景

  • Quick targeted refactors → use 
    code-refactoring
  • Design review of a plan → use 
    grill-with-docs
  • Implementation tickets → use 
    to-issues
  • 快速针对性重构 → 使用
    code-refactoring
  • 方案设计评审 → 使用
    grill-with-docs
  • 实现任务工单 → 使用
    to-issues

Process

流程

1. Explore

1. 探索阶段

Read domain glossary (
CONTEXT.md
) and ADRs first. Then walk the codebase organically, noting friction:
  • Where does understanding one concept require bouncing between many small modules?
  • Where are modules shallow — interface nearly as complex as the implementation?
  • Where have pure functions been extracted for testability, but real bugs hide in how they're called?
  • Where do tightly-coupled modules leak across seams?
  • Which parts are untested or hard to test through their current interface?
Apply the deletion test to suspected shallow modules.
首先阅读领域术语表（
CONTEXT.md
）和架构决策记录（ADRs）。然后全面梳理代码库，标记以下摩擦点：
  • 理解某个概念需要在多个小模块间反复跳转的地方？
  • 哪些模块属于浅模块——接口复杂度几乎与实现相当？
  • 哪些纯函数为了可测试性被提取，但实际Bug隐藏在调用逻辑中？
  • 紧耦合模块跨Seam泄漏的地方？
  • 当前接口下无法测试或难以测试的部分？
对疑似浅模块应用删除测试。

2. Present candidates

2. 提出候选改进项

Numbered list of deepening opportunities. For each:
  • Files — which files/modules are involved
  • Problem — why the current architecture causes friction
  • Solution — plain English description of what would change
  • Benefits — in terms of locality, leverage, and test improvement
Use 
CONTEXT.md
vocabulary for domain terms. Use the vocabulary above for architecture terms.
ADR conflicts: if a candidate contradicts an ADR, only surface it when friction is real enough to warrant revisiting. Mark clearly: "contradicts ADR-0007 — but worth reopening because…"
Ask: "Which of these would you like to explore?" — do NOT propose interfaces yet.
列出编号的深化改进机会列表。每个项需包含：
  • 文件 —— 涉及的文件/模块
  • 问题 —— 当前架构引发摩擦的原因
  • 解决方案 —— 用通俗易懂的语言描述变更内容
  • 收益 —— 从Locality（集中性）、Leverage（杠杆作用）和测试改进的角度说明
领域术语请使用
CONTEXT.md
中的词汇。架构术语请使用上述术语表中的词汇。
ADR冲突：如果候选改进项与ADR冲突，仅当摩擦足够严重值得重新审视时才提出，并明确标记："与ADR-0007冲突——但值得重新讨论，原因是…"
询问用户："你希望深入探索哪一项？"——暂不提出具体接口方案。

3. Grilling loop

3. 深度研讨循环

Once user picks a candidate, drop into a grilling conversation. Walk the design tree: constraints, dependencies, module shape, what sits behind the seam, what tests survive.
Side effects as decisions crystallize:
  • New concept not in CONTEXT.md? Add the term immediately
  • Fuzzy term sharpened? Update CONTEXT.md right there
  • User rejects with a load-bearing reason? Offer an ADR (only when a future explorer would need it to avoid re-suggesting the same thing)
一旦用户选定某个候选项，进入深度研讨对话。梳理设计树：约束条件、依赖关系、模块形态、Seam背后的内容、留存的测试用例。
随着决策逐渐明确，同步执行以下操作：
  • CONTEXT.md
    中未收录的新概念？     立即添加该术语
  • 模糊术语被明确？ 实时更新
    CONTEXT.md
  • 用户因关键原因拒绝？ 生成ADR（仅当未来探索者需要以此避免重复提出相同建议时）

Instructions

操作说明

  1. Identify the task trigger and expected output.
  2. Follow the workflow steps in this skill from top to bottom.
  3. Validate outputs before moving to the next step.
  4. Capture blockers and fallback path if any step fails.
  1. 识别任务触发条件和预期输出。
  2. 从上到下遵循此技能的工作流程步骤。
  3. 进入下一步前验证输出内容。
  4. 记录阻塞点及各步骤失败时的回退路径。

Examples

示例

  • Example: Apply this skill to a small scope first, then scale to full scope after validation passes.
  • 示例：先在小范围内应用此技能，验证通过后再扩展到全范围。

Best practices

最佳实践

  • Keep outputs deterministic and auditable.
  • Prefer small reversible changes over broad risky edits.
  • Record assumptions explicitly.
  • 保持输出可确定且可审计。
  • 优先选择小型可逆变更，而非广泛的高风险修改。
  • 明确记录假设条件。

References

参考资料

  • Project standards: 
    .agent-skills/skill-standardization/SKILL.md
  • Validator script: 
    .agent-skills/skill-standardization/scripts/validate_skill.sh
  • 项目标准：
    .agent-skills/skill-standardization/SKILL.md
  • 验证脚本：
    .agent-skills/skill-standardization/scripts/validate_skill.sh