simplifying-code

简化代码

工作规则

• 保留行为、接口、副作用和领域意图；证明任何未发布形态的例外在范围外没有调用方。
• 移除针对外部风险的保护措施之前，先复现其前置条件并证明风险已得到处理；否则应保留。
• 验证标准库替代方案在空值、null、无匹配项、排序和零值情况下的表现。
• 对于仅分析的请求，指出目标并报告拟议的简化方案，不要编辑代码。

原则

原则	规则
保留行为	输出必须与输入的行为完全一致，不得暗中添加或移除功能。具体而言，必须保留：异步/同步边界（不要将同步改为异步，反之亦然）、错误传播路径（不要改变策略）、体现运行意图的日志记录/遥测/保护措施/重试，以及领域特定步骤（不要将其折叠为隐藏意图的通用辅助函数）。有一种例外：仅存在于当前未发布范围较早迭代中的形态，不属于受保护行为。请确认它在已部署内容、持久化内容、公共或外部调用方、依赖分支或仓库内的已解决范围之外没有调用方，并且所有必要的调用方更新都在编辑范围内；否则应保留兼容路径。这项狭义豁免仅适用于已证实没有任何使用方的形态；它绝不允许移除保护措施，移除保护措施受“移除 AI 垃圾代码”一节中的证据门槛约束。
明确胜过巧妙	优先使用明确的变量，而非嵌套表达式。可读性胜过精简
简单胜过整洁	优先选择直接明了的代码，而非充斥模式的“整洁”代码。三行相似代码胜过过早抽象
精准修改	只修改需要简化的部分。遵循现有风格、命名约定和周围代码的格式
明示假设	修改代码块之前，先确定哪些内容导入它、它导入哪些内容，以及哪些测试覆盖它。在同一轮中修改依赖项
先删除，再简化	优先级依次为删除、简化、优化和自动化。检查后发现无需修改，也算是有效且完整的结果

更改接口、导出名称、持久化格式或路径会影响导入关系图之外的内容。请列出包含旧标识符的生产者、消费者、架构、测试固件、生成器、清单、脚本和 CI 配方、配置引用及文档，并在同一轮中完成迁移。收尾时搜索旧标识符：确保没有匹配项，或者为每个有意保留的匹配项用一行说明。重命名很容易遗漏仍保留旧键的测试固件和 .env.example 条目，而这两者都不在任何导入关系图中。若标识符属于公共或导出的 API，应先遵循停止条件：向用户确认，然后再列出相关内容；只有内部标识符才会在无需提示的情况下进行全面检查。

流程

1. 先阅读：在做任何更改前，先理解整个文件及其依赖项。遵循切斯特顿围栏原则：如果代码看起来多余，但原因不明，请先查看 git blame，再将其删除。先弄清原因，再判断该原因是否仍然成立。
2. 确定不变量：哪些内容必须保持不变？公共 API、返回类型、副作用、错误行为。编辑前，在一次性工作树中捕获相关的可观察输出，该工作树应代表精确的编辑前状态；只有当预先更改的 ref 与该状态一致时，才足以作为基准。在基准副本中保留相关的现有未提交更改，不要暂存工作树。
3. 确定目标：找出影响最大的简化机会。影响 = 可读性和可维护性；优先顺序：控制流 → 命名 → 重复 → 数据整形 → 类型（参见“异味 → 修复”表）
4. 按顺序应用：控制流 → 命名 → 重复 → 数据整形 → 类型。先做结构性更改，最后做表面调整。对于仅分析的请求，请描述拟议更改，而不要实际应用。
5. 验证：对于已应用的更改，通过相关测试、类型检查和导入检查确认行为一致。在相同输入下，将响应、CLI 输出和退出状态或作业产物与编辑前捕获的结果进行比较。只对有文档说明的非确定性字段进行标准化，并且在两边采用一致的方式；将无法解释的差异视为回归。如果没有测试，则进行直接比较，同时指出哪些行为尚未观察到。对于仅分析的报告，说明所需的检查和已有证据，不要声称拟议更改已通过验证。
6. 提交前范围审计：逐行检查每处更改，并问：“请求是否明确要求更改此行？”如果没有，则还原该更改，并将其列为“剩余风险”下的后续事项。对于范围不明确的请求（“简化我的项目”），请参阅 ia-verification-before-completion 的范围确认关卡。

停止条件

在以下情况下，先停止并询问，再继续：

• 简化需要更改公共 API（函数签名、返回类型、导出项）
• 无法通过测试或直接基准比较验证行为一致性
• 代码因领域原因而有意设计得复杂（对性能至关重要、协议合规）
• 范围意味着重新设计，而非简化

约束

• 只简化请求中指定的内容；不要添加功能、扩大范围、引入新依赖，也不要增加请求未要求的推测性可配置项或灵活性
• 保持未修改的代码原样；不要在未简化的代码行中添加注释、文档字符串或类型注解
• 不要将无关清理打包到同一个补丁中；每项简化都应是一个连贯、便于审查的单元
• 简化小范围的局部改动时，不要引入影响整个框架的模式
• 不要用不透明的工具层替代易懂的重复代码；三行相似代码胜过过早抽象
• 保留用于说明意图、不变量或非显而易见约束的注释，以及工具指令（例外情况）。删除仅仅复述显而易见代码行为的注释。仅在本次处理涉及的代码行上修正过时注释。
• 如果简化会让代码更难理解，就跳过
• 谨防过度简化：过于激进地内联会移除赋予概念意义的名称；将无关逻辑合并到一个函数中会掩盖不同的职责；移除为便于测试而存在的抽象会破坏测试套件
• 删除看似无用的代码前，搜索整个代码树，包括测试、夹具、配置、模板，以及使用字符串键或动态方式调用的代码。如果搜索无法检测相关的分派机制，应保留代码并提出询问，不要把零命中当作确凿证据
• 对于价值在于独立完整性的产物（提示词、技能和 Agent 指令、按服务划分的配置、供应商化策略文件），在相关编辑确实出现偏差之前，重复内容比共享依赖更可取。只有在多次出现协同修改失同步的情况，或确实存在共享形式的使用方时，才进行提取

验证

对于仅分析的报告，应区分现有证据与实施后必须进行的检查。代码更改后执行以下检查：

• 测试通过，类型检查通过
• 行为无变化（相同输入产生相同输出）
• 范围仅限于请求修改的文件；不顺带清理其他内容
• 根据步骤 1（梳理使用范围）中发现的导入方数量确定测试范围。没有外部导入方时，对已更改路径运行范围内测试；存在一个或多个外部导入方，或修改了共享代码／工具代码时，运行覆盖每个导入方的测试。如果测试运行器不支持按路径限定范围，则运行完整测试套件。

输出

对于仅分析的请求，报告每个目标的位置、拟议更改、理由、行为风险和所需验证，并将提案标记为尚未实施。

应用简化后，报告：

• 修改范围：修改的文件和函数
• 主要简化：每项用一行说明更改内容及原因
• 验证：测试通过、类型检查通过、行为无变化
• 剩余风险：所作假设、未处理但可能需要关注的部分

特定任务参考

在实施或审查对应行为前，阅读相关参考文档：

• 识别代码异味、移除 AI 生成的冗余内容，或消除保护措施／权宜方案时：simplification-patterns.md。
• 与其他技能结合并使用共同解析出的范围时：orchestrated-simplification.md。