refactor-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refactor It

重构（Refactor It）

Improve the code's shape while preserving behavior. If behavior must change, stop and use

fix-it

(or implement the feature explicitly) instead of hiding changes inside a "refactor."

Paying down development / architecture debt (

handbook/concepts/12-bugs-and-debt.md

) is a valid reason to refactor — still keep steps behavior-preserving and evidence-backed.

在保留行为的前提下优化代码结构。如果必须变更行为，请停止并使用

fix-it

（或明确实现该功能），而不是将变更隐藏在“重构”的名义下。

偿还开发/架构债务（

handbook/concepts/12-bugs-and-debt.md

）是重构的合理理由——但仍需保证每一步都保留行为且有证据支撑。

Operating contract

操作契约

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's
```
Workflow
```
tool only for orchestration across many subagents that truly needs it; it is expensive.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code
```
CLAUDE_CODE_SUBAGENT_MODEL
```
or a CLAUDE.md rule; Codex
```
agents.default_subagent_model
```
or a role's
```
agents.<name>.config_file
```
; Cursor a custom subagent's
```
model:
```
frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code
```
haiku
```
); implementation and evidence gathering → mid (
```
sonnet
```
); planning, review, adversarial verification → top (
```
opus
```
or
```
fable
```
). In Claude Code set it with the
```
Agent
```
tool
```
model
```
param or agent frontmatter
```
model:
```
; in Codex pass a spawn model or set
```
model
```
in the role's config file; in Cursor set
```
model:
```
(default
```
inherit
```
) in
```
.cursor/agents/*.md
```
. Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

所有DecisionNerd/dev-skills技能通用，标准副本见：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。 使用工具前，用一两行写明终点：验收标准（若存在现有issue的AC、BDD场景、测试或契约则沿用；否则提出验收标准并说明应存放的位置）以及证明达标的证据。上报完成前重新核对。绝不要对未验证的工作上报完成。
请求范围决定终点。 问题类请求（“准备好了吗？”、“为什么坏了？”、“下一步是什么？”）以答案和一行明确指定下一个调用的
```
Next:
```
结尾。结果类请求（“修复”、“完成”、“上线”、“#42”）会沿着链路（诊断→修复→测试→就绪检查→merge-it）持续推进，直到达成目标或遇到真正的阻塞。对于范围内的仓库内工作，不要以“你需要我…吗？”结束一轮回复。
仅因真正的阻塞停止。 只有在没有用户参与就无法继续时，或在以下操作前才停止并询问：删除数据或未合并的工作、强制推送或历史重写、修改本仓库外的任何内容（GitHub对象、部署、实时数据、生产或付费资源、外部服务）、超出请求范围——除非用户的请求已经明确指定了该操作。对于风险命令，保留框架的权限提示。否则继续推进，并将状态说明与下一步操作放在同一条消息中。
一次问清楚，问到位。 对于真正的问题，若框架有结构化提问工具（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时用
```
request_user_input
```
），则使用该工具并提供具体选项；否则使用带编号选项的纯文本。将答案视为最终结论；除非被要求，否则不要重新讨论之前的结论、计划或答案。
可并行工作时拆分任务。 对于独立的读取类工作（仓库调研、证据收集、各选项研究、各领域审计）和独立验证工作（未编写变更的评审人员），使用子Agent。写入类操作对每组路径保持单一负责人且串行执行。向每个子Agent明确说明目标、完成条件、约束、禁止事项和返回格式；整合前验证每个子Agent的结果。仅在确实需要编排大量子Agent时使用Claude Code的
```
Workflow
```
工具；该工具成本较高。
为每个子Agent选择模型层级；优先遵循路由配置。 如果框架或用户配置已经为子Agent配置了路由（Claude Code的
```
CLAUDE_CODE_SUBAGENT_MODEL
```
或CLAUDE.md规则；Codex的
```
agents.default_subagent_model
```
或角色的
```
agents.<name>.config_file
```
；Cursor自定义子Agent的
```
model:
```
前置元数据），则遵循该配置，不要传入模型参数。否则：机械搜索或盘点类→快速/低成本（Claude Code
```
haiku
```
）；实现和证据收集类→中等（
```
sonnet
```
）；规划、评审、对抗性验证类→顶级（
```
opus
```
或
```
fable
```
）。在Claude Code中通过
```
Agent
```
工具的
```
model
```
参数或Agent前置元数据的
```
model:
```
设置；在Codex中传入生成模型或在角色配置文件中设置
```
model
```
；在Cursor中在
```
.cursor/agents/*.md
```
中设置
```
model:
```
（默认
```
inherit
```
）。如果框架无法选择，子Agent将继承父模型或由框架选择（Cursor内置的Explore/Bash/Browser子Agent会根据子任务选择）；请在状态说明中注明使用的模型。
长时间运行时保留检查清单。 对于超过约五个步骤或跨技能的工作，在仓库根目录保留
```
TASKS.md
```
，完成一项勾选一项。除非仓库已经跟踪该文件，否则不要提交它。
每次运行结束时包含三个标题。
```
Blocked on me
```
（一个真正的问题或阻塞项，没有则填“none”）；
```
Changed
```
（文件、提交、GitHub对象、部署，没有则填“nothing”）；
```
Found
```
（证据、结论和
```
Next: <具体调用>
```
）。

When to use

适用场景

"Refactor it", extract function/module, rename for clarity, decompose god-file
Prep for a feature when structure blocks a clean change
After
```
diagnose-bug
```
when the bug fix is done and structure still hurts

“Refactor it”、提取函数/模块、为提升清晰度重命名、拆解上帝文件（god-file）
当结构阻碍干净的功能变更时，为功能开发做准备
```
diagnose-bug
```
之后，bug已修复但代码结构仍有问题时

When NOT to use

不适用场景

Product behavior change →
```
fix-it
```
Disk/worktree clutter →
```
tidy-up
```
Docs-only cleanup →
```
document-it
```
/ DocSlime
```
kiss
```

产品行为变更 →
```
fix-it
```
磁盘/工作区杂乱 →
```
tidy-up
```
仅文档清理 →
```
document-it
```
/ DocSlime
```
kiss
```

Workflow

工作流程

Done when: public contracts unchanged, tests green after every step, diff reviewable. Single writer per path set; parallel read-only scouting (fast tier) for characterization coverage is fine.

Characterize current behavior
- Identify entry points, public API, and existing tests that lock behavior.
- If tests are missing for the risky surface, propose
```
test-it
```
  before deep refactor (or add characterization tests first).
Define non-goals
- No feature work, no dependency upgrades "while we're here," no drive-by style wars outside the touched surface.
Plan small steps
- Extract, rename, move, invert dependencies — one cohesive idea per step.
- Keep diffs reviewable; avoid rewriting unrelated files.
Execute with a safety net
- After each step, run the narrowest relevant tests.
- Stop if behavior drifts; revert the step or add a failing characterization test.
Verify
- Same public contracts, same user-visible behavior.
- Note any intentional API renames and required call-site updates (still behavior-preserving).
Wrap up
- Next:
```
test-it
```
  if coverage is still thin,
```
document-it
```
  if public API moved,
```
pulls create
```
  /
```
merge-it
```
  to land.

完成条件：公共契约不变，每一步后测试通过，diff可评审。每组路径仅有一个写入者；可以并行开展只读的摸底工作（快速层级）以补充表征测试覆盖。

梳理当前行为
- 识别入口点、公共API和锁定行为的现有测试。
- 如果风险区域缺少测试，在深度重构之前建议使用
```
test-it
```
  （或先添加表征测试）。
定义非目标
- 不做功能开发，不“顺便”升级依赖，不在修改范围外搞无关的风格统一。
规划小步骤
- 提取、重命名、移动、反转依赖——每步只做一个内聚的改动。
- 保持diff可评审；避免重写不相关的文件。
带安全网执行
- 每一步后，运行范围最小的相关测试。
- 如果行为偏移则停止；回滚该步骤或添加一个失败的表征测试。
验证
- 公共契约不变，用户可见行为不变。
- 记录所有有意的API重命名和必要的调用点更新（仍保留行为）。
收尾
- 下一步：如果覆盖率仍不足则用
```
test-it
```
  ，如果公共API有变动则用
```
document-it
```
  ，通过
```
pulls create
```
  /
```
merge-it
```
  上线。

Guardrails

护栏规则

Behavior change → not this skill (
```
fix-it
```
/ feature work).
Don't mix refactor with large feature commits; split PRs when possible (
```
pulls narrow
```
).
Performance "refactors" need a measured baseline or they're speculative — say so.

行为变更 → 不适用本技能（
```
fix-it
```
/ 功能开发）。
不要将重构与大型功能提交混在一起；尽可能拆分PR（用
```
pulls narrow
```
）。
性能“重构”需要有可衡量的基准，否则就是推测性的——请明确说明这一点。

Output

输出格式

markdown

**Target**
- ...

**Behavior locked by**
- tests / manual checks: ...

**Steps taken**
1. ...

**Verification**
- Ran: ...

markdown

**Target**
- ...

**Behavior locked by**
- tests / manual checks: ...

**Steps taken**
1. ...

**Verification**
- Ran: ...

Blocked on me

none

Changed

Found

...
Next: test-it / document-it / pulls create

undefined

...
Next: test-it / document-it / pulls create

undefined

Grounding

依据

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook

sources.md

Fowler refactoring = behavior-preserving micro-steps under test; Beck: passes tests first. Characterization tests before structural change.

Handbook card:

handbook/practices/refactor-it.md

本技能的TTPs基于当前工程基准（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE 书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis——参见手册

sources.md

）。

Fowler重构法 = 测试保障下的保留行为的微步骤；Beck原则：先让测试通过。结构变更前先写表征测试。

手册卡片：

handbook/practices/refactor-it.md