Migrating a Workflow to Claude Agents Without Breaking It (Agent Orchestration Coderabbit)

Most teams don't build their first agent system on a blank page. They have a workflow that already runs the business — a rule-based ticket router, a hand-coded enrichment pipeline, a human-in-the-loop process held together by a runbook — and the question is how to move it onto Claude agent orchestration without taking the existing thing down. This is the migration nobody writes about, because the demos all start from zero. But the demo isn't the risk; the cutover is. This post is a playbook for replacing a live workflow with a Claude-orchestrated one safely: how to start in shadow, how to cut over a slice at a time, what fallbacks to keep, and how to roll back the instant something looks wrong.

Map the workflow before you touch it

The first job is not to write a prompt; it's to understand precisely what the current system does, including the parts no one remembers. Document every step, every decision point, every external system it calls, and — critically — every implicit rule baked into the code or the team's habits. Agentic systems fail in migration most often not because the model is incapable but because the old workflow encoded a dozen edge-case behaviors that no spec ever captured, and the new system silently drops them.

While you map, capture a dataset of real historical inputs paired with the outcomes the current system produced. That dataset is gold twice over: it becomes your eval set for the new agent, and it becomes the baseline you compare against in shadow mode. You cannot claim the agent is "as good as" the old workflow without the old workflow's actual outputs to measure against.

Decompose, don't lift-and-shift

Resist the urge to hand the entire workflow to one giant agent prompt and hope. The reliable pattern is to decompose the workflow into discrete capabilities and decide, per capability, what should be an agent's judgment and what should stay deterministic code. A good rule: keep the parts that are rules genuinely deterministic — validation, calculations, hard policy checks — and reserve the agent for the parts that need flexible judgment over messy input, like interpreting an ambiguous request or composing a reply. Orchestration shines when a planner routes between these pieces, not when it tries to be all of them at once.

This decomposition also defines your migration units. Each capability you can replace independently is a slice you can ship, measure, and roll back on its own, which is exactly what makes the cutover survivable.

flowchart TD
  A["Incoming request"] --> B["Run old workflow (system of record)"]
  B --> C["Run Claude agent in shadow"]
  C --> D{"Outputs match within tolerance?"}
  D -->|Yes| E["Log agreement, build confidence"]
  D -->|No| F["Flag divergence for review"]
  E --> G{"Confidence threshold met?"}
  G -->|Yes| H["Cut over this slice to agent"]
  G -->|No| C
  H --> I{"Live error or regression?"}
  I -->|Yes| J["Roll back to old workflow"]
  I -->|No| K["Expand to next slice"]

Run in shadow before you trust it

Shadow mode is the single most valuable safety mechanism in an agent migration. You run the new Claude orchestration alongside the existing workflow on real production traffic, but the old system remains the system of record — its output is what reaches the customer. The agent's output is logged and compared, not acted on. This lets you measure the new system against reality, at full production volume and variety, with exactly zero customer risk.

What you're looking for in shadow is agreement rate and, more importantly, the character of the disagreements. Some divergences will be the agent being wrong — those are bugs to fix and eval cases to add. But some will be the agent being right where the old workflow was quietly wrong, which is its own discovery. Don't cut over on agreement rate alone; review a real sample of divergences until you understand each category. Only when the agent matches or beats the baseline on the cases that matter do you have earned confidence rather than hope.

Cut over a slice at a time

When you go live, never flip the whole workflow at once. Move one slice, or one segment of traffic, from shadow to live while everything else stays on the old path. Start with the lowest-stakes, most-reversible slice — the one where a mistake is cheap and easy to undo — and expand only as each slice proves itself in production. A percentage rollout works well: route 5% of eligible traffic to the agent, watch the live metrics, then 25%, then more, with the old workflow still warm and ready to take the load back.

Throughout, keep a fallback wired in. If the agent errors, times out, hits a loop guard, or returns low-confidence output, the request should fall back to the old workflow automatically rather than failing the customer. That fallback is what lets you move fast: the worst case for any single request is that it gets handled the old, known-good way. Keep the old system runnable for far longer than feels necessary — decommissioning it is the last step, not an early one.

Make rollback boring

The final piece is the ability to undo, instantly and without drama. Put the cutover behind a feature flag or a routing config you can change in seconds without a deploy, so that the moment live metrics go bad — error rate, the trajectory and cost signals from your evals, a spike in customer escalations — you can route traffic back to the old workflow and investigate calmly. A migration where rollback is a brave multi-hour operation is a migration that will eventually cause an outage; a migration where rollback is a config toggle is one you can run aggressively because every step is reversible. Cheap, instant rollback is what turns a risky cutover into a series of small, safe experiments.

Frequently asked questions

How long should I run in shadow mode?

Long enough to see the real variety of production traffic — including weekly and monthly edge cases — and to drive the agreement rate and divergence reviews to a place you trust, not a fixed number of days. For a workflow with rare but important edge cases, that often means weeks rather than hours, because the cases that break agents are exactly the ones that show up infrequently.

Should I replace the whole workflow with one agent?

Usually not. Decompose it: keep deterministic rules as code, reserve the agent for steps needing flexible judgment, and let an orchestrator route between them. This gives you independent migration slices you can ship and roll back one at a time, which is far safer than a single all-or-nothing prompt.

What's the most common migration mistake?

Underestimating the implicit edge-case logic the old workflow encoded and that no spec wrote down. Capture real historical inputs and outputs as both your eval set and your shadow baseline, and review divergences carefully — that's how you surface the hidden rules before they surface as production incidents.

Migrating your phone lines to agentic AI

CallSphere uses this exact playbook — shadow runs, sliced cutover, instant fallback — to move call and message handling onto voice and chat agents that use tools mid-conversation and book work 24/7, without disrupting the lines that are already ringing. See a safe rollout in action at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.