跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

refactor

Behavior-preserving restructuring of code outside the current diff, such as extracting modules, renaming across files, or paying down debt. Triggers "refactor X", "restructure", "extract Y from Z". Just-changed code goes to /zero-tech-debt.

darkroomengineering · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add darkroomengineering/cc-settings --skill refactor

技能说明


name: refactor description: Behavior-preserving restructuring of code outside the current diff, such as extracting modules, renaming across files, or paying down debt. Triggers "refactor X", "restructure", "extract Y from Z". Just-changed code goes to /zero-tech-debt. context: fork

Refactoring Workflow

Standalone Codex

Create each new agent with spawn_agent, deliver context to a running agent with send_message, trigger another turn for an idle existing agent with followup_task, wait with wait_agent, and stop a current turn with interrupt_agent only when necessary. Never spawn codex-verifier and never run codex-run.ts from inside Codex.

Writers share the working tree unless the live host explicitly offers isolation. Assign non-overlapping ownership and serialize planner handoff, implementer, and test-writer phases; only read-only reviewers may overlap. Codex implementers are not promised Claude worktree isolation.

You are in Maestro orchestration mode. Delegate immediately.

Workflow

  1. Clarify - A refactor always crosses the delegation bar. Before exploring, run one clarifying round through the host's question tool: target shape, what must not change, and what "done" looks like; recommendation first on each
  2. Explore - Spawn explore agent to analyze current code
  3. Plan - Spawn planner agent to design refactoring approach
  4. Implement - Spawn implementer agent to refactor
  5. Test - Spawn tester agent to verify behavior unchanged
  6. Review - Spawn reviewer agent to check quality
  7. Learn - Store patterns discovered during refactoring

Agent Delegation

Spawn explore and planner first — they accept thin prompts because they discover what they need from the codebase:

Agent(explore, "Analyze the code to refactor: $ARGUMENTS. Identify patterns, issues, dependencies.")
Agent(planner, "Design refactoring approach based on analysis. Keep behavior unchanged.")

Claude: then assemble the implementer prompt from the actual planner output. The Claude implementer runs in an isolated worktree with no access to prior agent results, so paste the real plan — not "according to plan":

  • The user's refactor target ($ARGUMENTS) verbatim
  • The planner's step-by-step plan, including file paths and each move/rename/extract operation
  • Any "preserve behavior" invariants the planner called out
  • The test command that must remain green
  • Scope: "only the files in the plan; do not touch anything else"

Now spawn:

Agent(implementer, "<the assembled briefing above — all five items inline>")
Agent(tester, "Verify refactored code behaves identically to original.")
Agent(reviewer, "Review refactoring for quality and completeness.")

Standalone Codex branch: follow the lifecycle and serialization rules at the top. Use a fresh read-only reviewer for the independent pass after the writer and tester finish. Skip the Claude bridge branch below.

Refactors are a top source of subtle regressions — behavior that "shouldn't change" quietly does. When the Codex bridge is available, run a cross-model review in parallel with the reviewer:

Agent(codex-verifier, "Cross-model review of the refactor diff. Confirm behavior is preserved; report findings by severity.")

The bridge is gated and fails open: if Codex is unavailable, the reviewer agent alone is fine.

If the codex-verifier spawn fails, or it reports that Bash was stripped (forked skill contexts), run bun "$HOME/.claude/src/scripts/codex-run.ts" review directly instead — never skip the cross-model pass.

Output

Return a summary:

  • What changed: Brief description
  • Files modified: List of files
  • Tests passing: Verification status
  • Improvements: What's better now
  • Learnings: Patterns worth remembering