Back to Details

code-simplify

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Simplify

代码简化

Objective

目标

Simplify code while preserving behavior, public contracts, and side effects. Favor explicit code and local clarity over clever or compressed constructs.
在保留代码行为、公共契约和副作用的前提下简化代码。优先选择明确的代码和局部清晰度，而非巧妙或压缩的结构。

Operating Rules

操作规则

  • Preserve runtime behavior exactly. Keep inputs, outputs, side effects, and error behavior stable.
  • Prefer project conventions over personal preferences. Infer conventions from existing code, linters, formatters, and tests.
  • Limit scope to user-requested files or recently modified code unless explicitly asked to broaden.
  • Make small, reversible edits. Avoid broad rewrites when targeted simplifications solve the problem.
  • Call out uncertainty immediately when behavior may change.
  • 严格保留运行时行为。确保输入、输出、副作用和错误处理行为保持稳定。
  • 优先遵循项目约定而非个人偏好。从现有代码、linters、格式化工具和测试中推断约定。
  • 除非明确要求扩大范围，否则限制在用户指定的文件或最近修改的代码范围内。
  • 进行小幅度、可回滚的修改。当针对性简化即可解决问题时，避免大范围重写。
  • 当行为可能发生变化时，立即告知不确定性。

Workflow

工作流程

1) Determine Scope

1) 确定范围

  • Verify repository context: 
    git rev-parse --git-dir
    .
  • Identify candidate files:
    • If 
      $ARGUMENTS
      contains file paths, patterns, or 
      --all
      , use them. 
      --all
      means uncommitted changes via 
      git diff --name-only --diff-filter=ACMR
      .
    • Otherwise, default to session-modified files (files edited in this chat session).
  • Exclude generated or low-signal files unless explicitly requested:
    • lockfiles, minified bundles, build outputs, vendored code.
  • If no session edits exist and no explicit scope was given, inform the user and stop. Do not silently widen scope.
  • 验证仓库上下文：
    git rev-parse --git-dir
    .
  • 识别候选文件：
    • 如果
      $ARGUMENTS
      包含文件路径、模式或
      --all
      ，则使用这些参数。
      --all
      表示通过
      git diff --name-only --diff-filter=ACMR
      获取的未提交更改文件。
    • 否则，默认选择会话中修改的文件（本次聊天会话中编辑过的文件）。
  • 除非明确要求，否则排除生成文件或低价值文件：
    • lockfiles、压缩包、构建输出、第三方依赖代码。
  • 如果没有会话编辑记录且未指定明确范围，告知用户并停止操作。不得擅自扩大范围。

2) Build a Behavior Baseline

2) 建立行为基准

  • Read surrounding context, not only changed lines.
  • Identify invariants that must not change:
    • function signatures and exported APIs
    • state transitions and side effects
    • persistence/network behavior
    • user-facing messages and error semantics where externally relied on
  • Note available verification commands (lint, tests, typecheck).
  • 阅读代码的上下文，而不仅仅是修改的行。
  • 识别必须保持不变的不变量：
    • 函数签名和导出的API
    • 状态转换和副作用
    • 持久化/网络行为
    • 外部依赖的用户可见消息和错误语义
  • 记录可用的验证命令（lint、测试、类型检查）。

3) Apply Simplification Passes (in this order)

3) 应用简化步骤（按以下顺序）

  1. Control flow:
    • Flatten deep nesting with guard clauses and early returns.
    • Replace nested ternaries with clearer conditionals.
  2. Naming and intent:
    • Rename ambiguous identifiers when local context supports safe renaming.
    • Separate mixed concerns into small helpers with intent-revealing names.
  3. Duplication:
    • Remove obvious duplication.
    • Abstract only when at least two real call sites benefit and the abstraction reduces cognitive load.
  4. Data shaping:
    • Break dense transform chains into named intermediate steps when readability improves.
    • Keep hot-path performance characteristics stable unless improvement is explicit and measured.
  5. Type and contract clarity:
    • Add or tighten type annotations when they improve readability and safety without forcing broad churn.
    • Preserve external interfaces unless asked to change them.
  1. 控制流：
    • 使用守卫子句（guard clauses）和提前返回来展平深层嵌套。
    • 用更清晰的条件语句替换嵌套三元表达式。
  2. 命名与意图：
    • 当局部上下文支持安全重命名时，重命名模糊的标识符。
    • 将混合关注点分离为具有明确意图名称的小型辅助函数。
  3. 重复代码：
    • 移除明显的重复代码。
    • 仅当至少有两个实际调用点受益，且抽象能降低认知负荷时，才进行抽象。
  4. 数据处理：
    • 当提升可读性时，将密集的转换链拆分为命名的中间步骤。
    • 保持热路径的性能特征稳定，除非明确要求并经过衡量的性能改进。
  5. 类型与契约清晰度：
    • 当提升可读性和安全性且不会导致大范围改动时，添加或收紧类型注解。
    • 除非明确要求，否则保留外部接口。

4) Enforce Safety Constraints

4) 执行安全约束

  • Do not convert sync APIs to async (or reverse) unless explicitly requested.
  • Do not alter error propagation strategy unless behavior remains equivalent and verified.
  • Do not remove logging, telemetry, guards, or retries that encode operational intent.
  • Do not collapse domain-specific steps into generic helpers that hide intent.
  • 除非明确要求，否则不要将同步API转换为异步API（反之亦然）。
  • 除非行为保持等效且经过验证，否则不要更改错误传播策略。
  • 不要删除编码了操作意图的日志、遥测、守卫或重试逻辑。
  • 不要将特定领域的步骤合并为隐藏意图的通用辅助函数。

5) Verify

5) 验证

  • Run the narrowest useful checks first:
    • formatter/lint on touched files
    • targeted tests related to touched modules
    • typecheck when relevant
  • If fast targeted checks pass, run broader checks only when risk warrants it.
  • If checks cannot run, state what was skipped and why.
  • 优先运行最有用的窄范围检查：
    • 对修改的文件运行格式化工具/代码检查
    • 对修改的模块运行针对性测试
    • 相关时进行类型检查
  • 如果快速的窄范围检查通过，仅当风险需要时才运行更广泛的检查。
  • 如果无法运行检查，说明跳过的内容及原因。

6) Report

6) 报告

Provide:
  1. Scope touched (files/functions)
  2. Key simplifications with concise rationale
  3. Verification commands run and outcomes
  4. Residual risks or assumptions
提供以下内容：
  1. 涉及的范围（文件/函数）
  2. 关键简化操作及简洁的理由
  3. 运行的验证命令及结果
  4. 剩余风险或假设

Simplification Heuristics

简化启发式规则

  • Prefer explicit local variables over nested inline expressions when it reduces cognitive load.
  • Prefer one clear branch per condition over compact but ambiguous condition trees.
  • Keep function length manageable, but do not split purely for line count.
  • Keep comments that explain intent, invariants, or non-obvious constraints.
  • Remove comments that restate obvious code behavior.
  • Optimize for the next maintainer's comprehension time, not minimum character count.
  • 当减少认知负荷时，优先使用明确的局部变量而非嵌套内联表达式。
  • 优先为每个条件使用清晰的分支，而非紧凑但模糊的条件树。
  • 保持函数长度可控，但不要仅为了行数而拆分函数。
  • 保留解释意图、不变量或非明显约束的注释。
  • 删除重复明显代码行为的注释。
  • 优化目标是下一位维护者的理解时间，而非最小字符数。

Anti-Patterns

反模式

  • Do not perform speculative architecture rewrites.
  • Do not introduce framework-wide patterns while simplifying a small local change.
  • Do not replace understandable duplication with opaque utility layers.
  • Do not bundle unrelated cleanups into one patch.
  • 不要进行推测性的架构重写。
  • 不要在简化小范围局部更改时引入框架级模式。
  • 不要用不透明的工具层替代易于理解的重复代码。
  • 不要将无关的清理操作捆绑到一个补丁中。

Stop Conditions

停止条件

  • Stop and ask for direction when:
    • simplification requires changing public API/contracts
    • behavior parity cannot be confidently verified
    • the code appears intentionally complex due to domain constraints
    • the requested scope implies a larger redesign rather than simplification
  • 当出现以下情况时，停止操作并询问用户方向：
    • 简化需要更改公共API/契约
    • 无法自信地验证行为一致性
    • 代码因领域约束而看似故意设计得复杂
    • 请求的范围意味着需要更大的重新设计而非简化

Output Contract

输出契约

When presenting simplification results:
  1. Show the exact files and regions changed.
  2. Explain each meaningful change in one sentence focused on readability/maintainability gain.
  3. Confirm behavior-preservation assumptions explicitly.
  4. Summarize verification performed (or clearly state omissions).
展示简化结果时：
  1. 显示更改的确切文件和区域。
  2. 用一句话解释每个有意义的更改，重点说明可读性/可维护性的提升。
  3. 明确确认行为保留的假设。
  4. 总结已执行的验证（或明确说明未执行的内容）。