Back to Details

design-cleanup

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design cleanup — make the tree read as designed-this-way

设计清理——让代码树看起来从一开始就是如此设计的

Why this skill exists

此技能的存在意义

When a design decision changes mid-work — a different approach, a renamed concept, a replaced mechanism — the branch tends to keep fossils of the abandoned design: dead branches, shims that only served the old path, names shaped by the old concept, comments narrating the change, tests pinning behavior that no longer matters. The diff may show the journey; the final tree must not. This skill hunts those fossils down and rewrites the result as if the current design had been there from the beginning.
当工作中途变更设计决策（比如采用不同方案、重命名概念、替换机制）时，该branch往往会遗留旧设计的痕迹：废弃分支、仅服务于旧方案的垫片（shims）、受旧概念影响的命名、描述变更过程的注释、针对已失效行为的测试。Diff可以体现开发轨迹，但最终的代码树不能保留这些。此技能会找出这些遗留痕迹，并将代码重写为仿佛从一开始就采用当前设计的样子。

Step 1 — Establish the decision

步骤1——明确决策内容

State the decision as one line: "the design is X; the abandoned approach was Y". Take it from the user or the session context. If it is not stated, reconstruct it from the branch diff and commit messages, then confirm the one-line summary with the user before making sweeping edits — cleanup against a misread decision destroys correct code.
将决策总结为一句话：“当前设计为X；废弃的方案为Y”。可从用户表述或会话上下文获取该信息。若未明确说明，则从branch的diff和commit messages中重构决策内容，在进行大范围修改前需与用户确认该总结——基于错误理解的决策进行清理会破坏正确的代码。

Step 2 — Determine scope

步骤2——确定清理范围

  • Compute the branch diff: 
    git diff $(git merge-base HEAD origin/main)...HEAD
    (fall back to 
    origin/develop
    , then 
    develop
    ).
  • The cleanup covers only code touched by the decision: the changed files that implement it, plus files that reference the renamed or removed concepts (find them by grepping for the old names).
  • Everything else is out of bounds. This skill is not a license for unrelated refactors, formatting passes, or opportunistic improvements.
  • 计算branch的diff：
    git diff $(git merge-base HEAD origin/main)...HEAD
    （若失败则依次尝试
    origin/develop
    、
    develop
    ）。
  • 清理范围仅包含受决策影响的代码：实现该决策的变更文件，以及引用了已重命名或移除概念的文件（可通过grep旧名称找到这些文件）。
  • 其余内容均不在清理范围内。此技能不允许进行无关的重构、格式调整或随机优化。

Step 3 — Hunt the leftovers

步骤3——寻找遗留痕迹

Check each category against the in-scope files:
  • Dead code: branches, parameters, feature flags, config keys, and helpers that only the abandoned path used.
  • Shims and indirection: adapters, wrappers, and abstraction layers that existed only to bridge the old design to the new one.
  • Names and structure: identifiers, files, and modules shaped by the old concept — 
    newParser
    , 
    handleV2
    , 
    legacyFoo
    , or a module layout organized around a concept that no longer exists.
  • Comments and docstrings: anything describing the old design or narrating the change — "previously", "instead of", "now we", "changed from X to Y". Descriptions must state only the current design.
  • Tests: tests that pin the abandoned behavior, transitional states, or the shape of the old API. Rewrite them for the intended behavior of the current design; do not keep them green by accident.
  • Docs: README sections, ADRs, diagrams, and examples that describe the old mechanism. Update in place — no "migration note" additions.
  • TODOs: items left for the old plan.
针对范围内的文件，检查以下各类遗留内容：
  • 废弃代码（Dead code）：仅服务于旧方案的分支、参数、功能开关、配置项及辅助函数。
  • 垫片与间接层（Shims and indirection）：仅用于衔接旧设计与新设计的适配器、包装器及抽象层。
  • 命名与结构：受旧概念影响的标识符、文件及模块——例如
    newParser
    、
    handleV2
    、
    legacyFoo
    ，或是围绕已废弃概念组织的模块结构。
  • 注释与文档字符串：任何描述旧设计或变更过程的内容——比如“previously”、“instead of”、“now we”、“changed from X to Y”。文档描述应仅说明当前设计。
  • 测试：针对废弃行为、过渡状态或旧API形态的测试。需重写这些测试以适配当前设计的预期行为；切勿为了让测试通过而保留无关内容。
  • 文档：描述旧机制的README章节、ADRs（架构决策记录）、图表及示例。直接原地更新——不要添加“迁移说明”。
  • TODO项：为旧计划遗留的待办事项。

Step 4 — Rewrite, don't patch

步骤4——重写而非修补

  • Rename to the current concept everywhere, not just where it is cheap.
  • Delete dead code outright; never comment it out or gate it "just in case". Git history holds the old version.
  • Collapse indirection that no longer earns its keep.
  • Rewrite affected comments, docstrings, and docs to describe only the current state.
  • 全面重命名为当前概念的名称，不要仅在容易修改的地方更改。
  • 直接删除废弃代码；切勿注释掉或留作“以防万一”。Git历史记录会保留旧版本。
  • 移除不再必要的间接层。
  • 重写受影响的注释、文档字符串及文档，使其仅描述当前状态。

Step 5 — Verify and report

步骤5——验证并报告

  • Run the project's build and tests; the cleanup must not change behavior of the surviving design.
  • Grep the resulting branch diff for history words as a smoke check: 
    previously|instead of|no longer|old |new |V2|legacy
    — hits are candidates to fix, not automatic violations; judge each.
  • Grep the whole tree for the abandoned names to confirm no dangling references remain.
  • Report what was removed, renamed, and rewritten, grouped by the categories above, and call out anything suspicious that was left alone because it fell outside the decision's scope.
  • 运行项目的构建和测试；清理操作不得改变当前保留设计的行为。
  • 对最终的branch diff进行关键词扫描作为快速检查：
    previously|instead of|no longer|old |new |V2|legacy
    ——匹配到的内容是潜在需要修复的对象，但并非必然违规，需逐一判断。
  • 在整个代码树中grep旧名称，确认不存在悬空引用。
  • 按上述分类汇总报告已移除、重命名及重写的内容，并指出因超出决策范围而未处理的可疑内容。