design-cleanup

设计清理——让代码树看起来仿佛一开始就是这样设计的

为什么需要这项技能

当设计决策在工作中途发生变化——采用了不同的方案、重命名了概念或替换了机制——分支中往往会留下被放弃设计的遗迹：无用的分支、只服务于旧路径的垫片、受旧概念影响的名称、讲述变更过程的注释，以及固守已无关紧要行为的测试。差异可能记录了这段历程，但最终的代码树不应如此。这项技能会找出这些遗迹，并重写结果，让它看起来仿佛当前设计从一开始就已存在。

步骤 1——确定决策

用一句话说明决策：“设计是 X；放弃的方案是 Y”。从用户或会话上下文中获取这条信息。如果没有明确说明，则根据分支差异和提交消息还原，然后在进行大范围编辑之前，向用户确认这句总结——如果误读了决策，清理工作会破坏正确的代码。

步骤 2——确定范围

• 计算分支差异：git diff $(git merge-base HEAD origin/main)...HEAD （如果没有，则依次尝试 origin/develop，然后是 develop）。
• 清理范围仅限于受该决策影响的代码：实现该决策的已更改文件，以及引用已重命名或移除概念的文件（通过搜索旧名称找到这些文件）。
• 其他内容都不在范围内。这项技能并不授权进行无关重构、格式调整或顺手改进。

步骤 3——查找遗留内容

针对范围内的文件，逐项检查以下类别：

• 无用代码：仅供被放弃路径使用的分支、参数、功能标志、配置键和辅助函数。
• 垫片和间接层：仅为衔接旧设计与新设计而存在的适配器、封装器和抽象层。
• 名称和结构：受旧概念影响的标识符、文件和模块——newParser、handleV2、legacyFoo，或围绕已不存在的概念组织的模块布局。
• 注释和文档字符串：任何描述旧设计或讲述变更过程的内容——“此前”、“取代……”、“现在我们”、“从 X 改为 Y”。描述必须只说明当前设计。
• 测试：固守被放弃行为、过渡状态或旧 API 形态的测试。应根据当前设计的预期行为重写测试；不要让它们意外地继续通过。
• 文档：描述旧机制的 README 章节、ADR、图表和示例。直接更新原内容——不要添加“迁移说明”。
• TODO：为旧计划留下的事项。

步骤 4——重写，不要修补

• 在所有地方都重命名为当前概念，而不只是修改起来方便的地方。
• 彻底删除无用代码；不要将其注释掉，也不要用条件屏蔽，以防“以后可能会用到”。Git 历史会保留旧版本。
• 移除不再有用的间接层。
• 重写受影响的注释、文档字符串和文档，只描述当前状态。

步骤 5——验证并报告

• 运行项目的构建和测试；清理不能改变保留设计的行为。
• 在生成的分支差异中搜索历史描述用语，作为初步检查： previously|instead of|no longer|old |new |V2|legacy——搜索命中都需要检查，但不一定违规；请逐项判断。
• 在整个代码树中搜索被放弃的名称，确认没有残留引用。
• 按上述类别分组，报告移除、重命名和重写的内容，并指出任何因超出决策范围而未处理的可疑内容。