Back to Details

deepen

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

deepen — make modules deep

deepen — 让模块更“深”

Behavior is sacred: tests green before AND after. Every change shrinks an interface or hides a decision — deepen, don't churn.
A deep module hides a lot behind a small interface; a shallow one's interface costs as much to use as writing the code yourself. Complexity = dependencies + obscurity, and it compounds. Deepen spends spare usage paying that down before it becomes a §B. Run it when the build is green & you have budget to drain — not under deadline.
行为不可侵犯：重构前后测试均需通过。每一处修改都要缩小接口范围或隐藏决策细节——聚焦深度优化，而非无意义变动。
深度模块（deep module） 用简洁的接口隐藏大量实现细节；而浅模块（shallow） 的接口使用成本几乎等同于自行编写代码。复杂度 = 依赖项 + 晦涩性，且会不断累积。Deepen功能会利用多余的使用额度提前降低复杂度，避免其演变为§B问题。请在构建成功、测试通过且有多余额度时运行该功能——切勿在截止日期前使用。

WHEN TO DEEPEN

何时使用Deepen

  • Build is green, tests pass, & you have token budget spare.
  • A module's interface feels as complex as its implementation (shallow smell).
  • The same change keeps touching many files (change amplification).
  • User explicitly asks to improve design quality.
⊥ run mid-feature or under pressure. Deepen is the deliberate pass, not the reflex.
  • 构建成功、测试通过，且有多余的令牌额度。
  • 模块的接口复杂度与实现复杂度相当（浅模块特征）。
  • 同一修改需要改动多个文件（变更扩散）。
  • 用户明确要求提升设计质量。
⚠️ 请勿在功能开发过程中或压力下运行。Deepen是刻意的优化步骤，而非本能操作。

FIVE STEPS

五个步骤

1. PICK THE SHALLOW

1. 挑选浅模块

Scan the modules the spec touches. Rank by shallowness — interface surface vs work done. Pick the one worst offender. Tells:
  • Pass-through method that only forwards to one other (shallow layer).
  • Caller must set 5 flags right to use it (config leakage).
  • Same abstraction repeated at two layers (no information hiding).
  • A 
    ?
    or §B that traces back to a confusing interface.
One module per pass. Deepening is surgical, ⊥ a codebase sweep.
扫描规范涉及的模块，根据“浅度”排序——即接口规模与完成工作量的比例。选出最严重的那个模块。判断特征：
  • 仅转发至其他方法的透传方法（浅层封装）。
  • 调用者必须设置5个标志才能正确使用（配置泄露）。
  • 同一抽象在两层重复出现（无信息隐藏）。
  • 可追溯至混乱接口的
    ?
    或§B问题。
每次处理一个模块。深度优化是精准操作，⚠️ 而非全面扫查代码库。

2. DIAGNOSE

2. 诊断问题

Name the design defect in caveman, citing file:line:
src/auth/token.go: 6-arg ctor leaks rotation policy to every caller. shallow. Complexity is real only if it shows: change amplification, high cognitive load, or an unknown-unknown (caller must know a hidden fact to call it right).
用直白的语言指出设计缺陷，并引用文件和行号：
src/auth/token.go: 6参数构造函数将轮换策略泄露给所有调用者。属于浅模块。 复杂度只有在体现为以下情况时才是真实问题：变更扩散、高认知负荷，或未知的未知项（调用者必须知晓隐藏信息才能正确调用）。

3. RESEARCH THE DEEPENING

3. 研究深度优化方案

What does a deeper version look like? Pull a known pattern (hand to research for the external case → §R) or derive from the codebase's own better modules. Moves that deepen:
  • Pull complexity down — hide the hard part inside, give callers the simple path.
  • Define errors out of existence — design the interface so the edge can't occur.
  • Information hiding — one decision, one module; callers don't learn it.
  • General-purpose interface over a pile of special-case methods.
更深度的版本是什么样的？参考已知模式（针对外部场景可调用research→§R），或从代码库中设计更优的模块推导。可实现深度优化的操作：
  • 将复杂度下移——把复杂逻辑隐藏在内部，为调用者提供简单路径。
  • 通过设计消除错误——设计接口使边缘情况无法发生。
  • 信息隐藏——一个决策对应一个模块；调用者无需知晓该决策。
  • 用通用接口替代一堆特殊方法。

4. PROPOSE

4. 提出建议

Draft the change as spec edits, not a silent rewrite:
  • New/simpler §I shape for the module.
  • §V that locks the deepened invariant so a future build can't re-shallow it.
  • §T refactor row(s), each citing the §V/§I it serves. Hand to spec to write. Show the before/after interface so the user sees the shrink.
将修改方案以规范编辑建议的形式呈现，而非静默重写：
  • 模块的新/简化版§I结构。
  • 用于锁定深度优化后不变量的§V，防止未来构建再次让模块变浅。
  • §T重构条目，每条引用其所服务的§V/§I。 提交给spec进行编写。展示接口的前后对比，让用户看到接口范围的缩小。

5. VERIFY BEHAVIOR HELD

5. 验证行为一致性

Refactor ≠ rewrite. Full suite green before you start AND after. A deepening that changes behavior is a feature in disguise — stop, route through 
/spec
+ 
/build
. New interface gets a test proving the old callers still work.
重构≠重写。开始前和完成后都要确保全量测试通过。如果深度优化改变了行为，那它本质上是一项新功能——请停止操作，通过
/spec
+ 
/build
流程处理。新接口需添加测试，证明旧调用者仍能正常工作。

WHEN TO STOP

何时停止

Done when the chosen module's interface is strictly smaller, its hidden decision no longer leaks, tests are green, and §I/§V record the new shape. One module deepened beats five churned. Budget left → pick the next shallowest, fresh pass.
当所选模块的接口范围严格缩小、隐藏的决策不再泄露、测试通过，且§I/§V记录了新结构时，即完成优化。优化好一个模块胜过无意义地改动五个模块。若还有剩余额度→选择下一个最浅的模块，开启新的优化流程。

BOUNDARIES

边界限制

  • ⊥ change behavior. Green before, green after. Pure structure.
  • ⊥ write SPEC.md. Propose §I/§V/§T; spec writes.
  • ⊥ deepen more than one module per pass.
  • ⊥ run under deadline or mid-feature. This is the spare-budget pass.
  • ⊥ add abstraction for single-use code. A deep module earns its hiding; a speculative one is just more surface.
  • ⚠️ 不得改变行为。优化前后测试均需通过。仅调整结构。
  • ⚠️ 不得编写SPEC.md。仅提出§I/§V/§T建议；由spec负责编写。
  • ⚠️ 每次优化不得超过一个模块。
  • ⚠️ 不得在截止日期前或功能开发过程中运行。这是使用多余额度的优化步骤。
  • ⚠️ 不得为单次使用的代码添加抽象。深度模块的隐藏是有价值的；而投机性抽象只会增加接口规模。