code-simplify

代码简化

目标

在保留行为、公共契约和副作用的同时简化代码。默认执行完整的简化流程：应用有充分把握、能显著提升可读性或降低缺陷风险的简化，包括在安全的情况下清理命名和意图。

参数

• 路径、模式、提交/范围或范围描述：用于“范围解析”步骤 2。
• --no-report：跳过完整的面向用户报告，向调用方返回简短的工作说明。
• --no-verify：跳过验证，因为父级编排器会另外验证最终结果。
• 默认：执行完整的简化流程，验证受影响的行为，并提供完整报告。

范围解析

解析一次范围，然后在本次运行的其余部分将结果视为固定。

1. 验证仓库上下文：git rev-parse --git-dir。如果失败，停止并告知用户从 Git 仓库中运行。
2. 如果请求指定了目标——文件路径/模式、提交/范围、自然语言子集（例如“解析器相关更改”），或每行包含一个仓库相对路径的 resolved-scope 围栏代码块——则范围仅限于这些目标。继续之前，将自然语言子集映射到具体路径。
3. 否则，范围仅限本会话中修改过的文件：本会话早些时候创建或编辑的文件。不要包含其他未提交的更改。
4. 如果没有本会话修改过的文件，或者当前上下文中看不到更早的对话记录，则回退到所有未提交文件，并各运行一次以下命令：
   • 已跟踪：git diff --name-only --diff-filter=ACMR
   • 未跟踪：git ls-files --others --exclude-standard
   • 合并两个列表并去重。
5. 除非明确要求，否则不要手动简化生成文件、供应商代码、大型文件和低信号文件：锁文件、压缩包、构建产物、生成的输出、供应商代码和大型数据快照。如果相关文件会影响正确性，可选用标记为 excluded-scope 的围栏代码块列出，每行一个仓库相对路径或 glob，并通过验证或不变式检查覆盖这些文件。
6. 如果解析出的范围不包含任何文件，报告这一情况并停止。
7. 使用标记为 resolved-scope 的围栏代码块输出范围，每行一个仓库相对路径。该代码块具有权威性：之后不要重新运行范围命令或重新审视排除项。

操作规则

• 编辑前说明假设。如果有多种解释会改变简化方式或验证策略，请列出这些解释并停止，等待指示。
• 严格保留运行时行为。保持输入、输出、副作用和错误行为稳定。
• 优先遵循项目惯例，而非个人偏好。从现有代码、代码检查工具、格式化工具和测试中推断惯例。
• 进行小幅、可逆的修改。每一处更改都应对应用户的请求、用户要求的清理，或因你自己的修改而产生的清理。
• 以解决请求所需的最少代码为准。不要添加用户未要求的功能、一次性抽象、推测性的灵活性或可配置项。
• 只清理由你自己的修改造成的问题：删除因修改而变得未使用的导入、变量、函数和文件；在“剩余风险”中提及预先存在的无效代码，不要删除它们。
• 仅当纯命名重构能带来明确的可读性或安全性提升，并且可以安全验证时才进行。
• 对于生成文件、供应商代码、大型文件或低信号文件，尽可能简化生成器、架构或契约，并通过不变式检查验证输出，而不是逐行或逐个文件手动修改。
• 当行为可能发生变化时，立即指出不确定性。

工作流

1）确定范围

• 应用“范围解析”部分。
• 将任何 excluded-scope 代码块视为不属于手动简化范围，但纳入验证计划。

2) 建立行为基线

• 阅读周边上下文，不要只看变更的行。
• 确定必须保持不变的内容：
  • 函数签名和导出的 API
  • 状态转换和副作用
  • 持久化／网络行为
  • 外部依赖的面向用户消息和错误语义
• 记录可用的验证命令（lint、测试、类型检查）。
• 编辑前定义成功标准。对于多步骤工作，简要说明计划，并为每一步列出验证检查。

3) 梳理简化机会

• 默认不做修改，除非简化有充分把握，且能显著提升可读性、清理当前变更中的冗余，或降低缺陷风险。
• 优先进行局部且保持行为不变的修改，而不是大范围重写。
• 跳过无效的检查。如果目标代码已经足够清晰，应如实说明，而不是为了改动而改动。
• 只有在能明确提升清晰度或安全性，且有安全验证路径时，才重命名标识符或拆分辅助函数。切勿仅凭个人偏好重塑 API。

4) 执行简化

按以下顺序应用完整检查清单：

1. 控制流：
   • 使用守卫子句和提前返回来扁平化深层嵌套。
   • 用更清晰的条件语句替换嵌套三元表达式。
2. 命名和意图：
   • 在局部上下文支持安全重命名时，重命名含义模糊的标识符。
   • 将混杂的职责拆分为意图明确的小型辅助函数。
3. 重复：
   • 消除明显的重复。
   • 只有在至少两个实际调用点都能受益，且抽象能降低理解成本时，才进行抽象。
4. 数据整形：
   • 在能提升可读性时，将密集的转换链拆分为具名中间步骤。
   • 除非明确提出并经过衡量，否则保持热点路径的性能特征不变。
5. 类型和契约的清晰度：
   • 在能提升可读性和安全性且不会导致大范围改动时，添加或收紧类型注解。
   • 除非用户要求变更，否则保留外部接口。

5) 遵守安全约束

• 除非明确要求，否则不要将同步 API 改为异步，或反向修改。
• 除非行为保持等效且经过验证，否则不要改变错误传播策略。
• 不要移除体现运维意图的日志记录、遥测、守卫或重试。
• 不要将特定领域的步骤合并为隐藏意图的通用辅助函数。

6) 验证

如果设置了 --no-verify，则跳过验证。否则，按照下方的“验证”部分执行。

7) 报告

按照下方的“报告”部分生成报告。

简化启发式

• 当能降低理解成本时，优先使用显式局部变量，而不是嵌套的内联表达式。
• 每个条件优先使用一个清晰分支，而不是紧凑但含义模糊的条件树。
• 保持函数长度适中，但不要仅为减少行数而拆分函数。
• 保留说明意图、不变量或非显而易见约束的注释。
• 移除仅重复显而易见代码行为的注释。
• 优先缩短下一位维护者的理解时间，而非减少字符数。

反模式

• 不要进行推测性的架构重写。
• 简化小范围变更时，不要引入适用于整个框架的模式。
• 不要用不透明的工具层替换易于理解的重复代码。
• 不要将无关的清理工作捆绑到同一个补丁中。
• 不要为不可能出现的情况添加错误处理。
• 不要为了保留代码量而保留代码；如果存在更简单且等效的方案，就采用它，或说明它为何不符合要求。

验证

运行能验证已修改行为的最小范围检查：

• 对已修改文件运行格式化工具／lint
• 对已修改模块运行针对性测试
• 相关时运行类型检查
• 对相关的 excluded-scope 输出进行不变量检查

只有在风险需要时才运行更广泛的检查，尤其是简化涉及共享契约时。列出每项跳过的检查及其原因。

报告

设置了 --no-report 时跳过；改为返回简短的工作笔记：涉及范围、关键简化、剩余风险。

使用以下章节标题，并按此顺序排列。省略不适用的章节——不要编号，也不要留下空缺或占位内容。

范围

已更改的文件和区域，以及任何 excluded-scope 条目及其采用的验证策略。

简化

每项有意义的更改用一句话说明，重点说明对可读性或可维护性的提升。明确确认保留行为的假设。

验证

运行的命令及其结果，包括跳过的检查。

剩余风险

每项风险单独一行：假设 <假设>；如果不成立，<会导致什么问题>；通过 <命令或检查> 进行确认。 使用通俗语言——展开或解释领域专用术语。直接提出需要用户决定的问题。没有风险时写 None.。

停止条件

遇到以下情况时，停止并询问如何处理：

• 简化需要更改公共 API/契约。
• 需求不明确，或不同解释会导致实质不同的修改。
• 无法有把握地验证行为一致性。
• 代码看起来是因领域约束而有意设计得复杂。
• 请求的范围意味着需要进行更大规模的重新设计，而非简化。