Back to Details

orchestrate-batch-refactor

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Orchestrate Batch Refactor

批量重构编排

Overview

概述

Use this skill to run high-throughput refactors safely. Analyze scope in parallel, synthesize a single plan, then execute independent work packets with sub-agents.
使用本Skill可安全执行高吞吐量的重构工作。通过并行分析范围，合成统一计划，随后由子Agent执行独立的工作包。

Inputs

输入项

  • Repo path and target scope (paths, modules, or feature area)
  • Goal type: refactor, rewrite, or hybrid
  • Constraints: behavior parity, API stability, deadlines, test requirements
  • 仓库路径与目标范围（路径、模块或功能区域）
  • 目标类型：重构、重写或混合模式
  • 约束条件：行为一致性、API稳定性、截止期限、测试要求

When to Use Parallelization

何时使用并行化

  • Use this skill for medium/large scope touching many files or subsystems.
  • Skip multi-agent execution for tiny edits or highly coupled single-file work.
  • 当重构范围为中等或大型，涉及大量文件或子系统时，使用本Skill。
  • 对于微小修改或耦合度极高的单文件工作，无需使用多Agent执行。

Core Workflow

核心工作流

  1. Define scope and success criteria.
    • List target paths/modules and non-goals.
    • State behavior constraints (for example: preserve external behavior).
  2. Run parallel analysis first.
    • Split target scope into analysis lanes.
    • Spawn 
      explorer
      sub-agents in parallel to analyze each lane.
    • Ask each agent for: intent map, coupling risks, candidate work packets, required validations.
  3. Build one dependency-aware plan.
    • Merge explorer output into a single work graph.
    • Create work packets with clear file ownership and validation commands.
    • Sequence packets by dependency level; run only independent packets in parallel.
  4. Execute with worker agents.
    • Spawn one 
      worker
      per independent packet.
    • Assign explicit ownership (files/responsibility).
    • Instruct every worker that they are not alone in the codebase and must ignore unrelated edits.
  5. Integrate and verify.
    • Review packet outputs, resolve overlaps, and run validation gates.
    • Run targeted tests per packet, then broader suite for integrated scope.
  6. Report and close.
    • Summarize packet outcomes, key refactors, conflicts resolved, and residual risks.
  1. 定义范围与成功标准。
    • 列出目标路径/模块与非目标内容。
    • 声明行为约束（例如：保留外部行为）。
  2. 先执行并行分析。
    • 将目标范围拆分为多个分析分支。
    • 并行生成
      explorer
      子Agent以分析每个分支。
    • 要求每个Agent提供：意图映射、耦合风险、候选工作包、所需验证项。
  3. 构建一个感知依赖的计划。
    • 将explorer的输出合并为单一工作图。
    • 创建具有明确文件归属和验证命令的工作包。
    • 按依赖级别排序工作包；仅并行执行独立的工作包。
  4. 由Worker Agent执行。
    • 为每个独立工作包生成一个
      worker
      Agent。
    • 分配明确的职责（文件/任务范围）。
    • 告知每个Worker，代码库中还有其他Agent在工作，必须忽略无关的修改。
  5. 集成与验证。
    • 审查工作包输出，解决重叠问题，并运行验证关卡。
    • 针对每个工作包运行定向测试，随后对集成范围运行更全面的测试套件。
  6. 报告与收尾。
    • 总结工作包成果、关键重构内容、已解决的冲突以及剩余风险。

Work Packet Rules

工作包规则

  • One owner per file per execution wave.
  • No parallel edits on overlapping file sets.
  • Keep packet goals narrow and measurable.
  • Include explicit done criteria and required checks.
  • Prefer behavior-preserving refactors unless user explicitly requests behavior change.
  • 每个执行阶段，每个文件只能有一个所有者。
  • 不得对重叠文件集进行并行编辑。
  • 工作包的目标应保持聚焦且可衡量。
  • 包含明确的完成标准和所需检查项。
  • 除非用户明确要求变更行为，否则优先选择保留行为的重构方式。

Planning Contract

规划约定

Every packet must include:
  1. Packet ID and objective.
  2. Owned files.
  3. Dependencies (none or packet IDs).
  4. Risks and invariants to preserve.
  5. Required checks.
  6. Integration notes for main thread.
Use 
references/work-packet-template.md
 for the exact shape.
每个工作包必须包含：
  1. 工作包ID与目标。
  2. 负责的文件。
  3. 依赖项（无或其他工作包ID）。
  4. 需保留的风险与不变量。
  5. 所需检查项。
  6. 主线集成说明。
使用
references/work-packet-template.md
获取标准格式。

Agent Prompting Contract

Agent提示约定

  • Use the prompt templates in 
    references/agent-prompt-templates.md
    .
  • Explorer prompts focus on analysis and decomposition.
  • Worker prompts focus on implementation and validation with strict ownership boundaries.
  • 使用
    references/agent-prompt-templates.md
    中的提示模板。
  • Explorer的提示聚焦于分析与分解。
  • Worker的提示聚焦于实现与验证，并严格遵守职责边界。

Safety Guardrails

安全防护措施

  • Do not start worker execution before plan synthesis is complete.
  • Do not parallelize across unresolved dependencies.
  • Do not claim completion if any required packet check fails.
  • Stop and re-plan when packet boundaries cause repeated merge conflicts.
  • 在计划合成完成前，不得启动Worker执行。
  • 不得在未解决依赖的情况下进行并行化。
  • 若任何工作包检查项未通过，不得宣称完成。
  • 当工作包边界导致重复合并冲突时，停止执行并重新规划。

Validation Strategy

验证策略

Run in this order:
  1. Packet-level checks (fast and scoped).
  2. Cross-packet integration checks.
  3. Full project safety checks when scope is broad.
Prefer fast feedback loops, but never skip required behavior checks.
按以下顺序执行：
  1. 工作包级检查（快速且范围明确）。
  2. 跨工作包集成检查。
  3. 当范围较广时，执行完整项目安全检查。
优先选择快速反馈循环，但绝不能跳过必要的行为检查。