Migrating an existing workflow to Claude Code agents

You already have a workflow that works. Maybe it is a brittle script, a chain of scheduled jobs, or a manual process a person runs every morning. It is not glamorous, but it is load-bearing, and people depend on it. Now you want to move it onto Claude Code dynamic workflows so it can handle the messy cases your rigid pipeline can't. The temptation is to rewrite it all at once and flip the switch. Resist that. The fastest way to lose trust in agentic AI is a big-bang migration that breaks something important on day one.

Migration to an agentic workflow is a controlled, reversible process, not a rewrite-and-pray. The goal is to move the work onto the new approach in steps small enough that any one step can be undone without drama, while proving at every stage that the agent is at least as good as what it replaces. This post is a playbook for doing exactly that: mapping the existing process, strangling it incrementally, running in shadow before cutover, and keeping a rollback you can actually pull.

Map the workflow before you touch it

You cannot safely replace a process you do not fully understand. Before writing a single agent instruction, document the existing workflow end to end: every input it accepts, every step it performs, every external system it touches, and — critically — every implicit rule the current process enforces that nobody wrote down. Legacy pipelines are full of these. The script skips weekends. It retries twice then alerts a human. It treats a certain account specially. Those behaviors are requirements even when they live only in someone's head.

This mapping doubles as your eval dataset. The inputs the current workflow handles, paired with the outputs it produces, are exactly the labeled cases you will measure the agent against. Capturing a representative set of real historical runs gives you a ground truth to compare the new agent to — without it, you have no objective way to know whether the migration improved things or quietly regressed them.

Strangle, don't rewrite

The strangler pattern is the safest migration shape. Instead of replacing the whole pipeline at once, you carve off one piece, move just that piece onto the agentic workflow, and leave everything else untouched. Pick the part with the highest pain and the lowest blast radius — usually a step that is brittle, full of edge cases, and not the most catastrophic if it errs. Get that one piece working and trusted, then carve off the next.

flowchart TD
  A["Incoming request"] --> B{"Step migrated
to agent?"}
  B -->|No| C["Run legacy step"]
  B -->|Yes| D["Run agent in shadow"]
  D --> E["Compare agent vs
legacy output"]
  E --> F{"Agent matches
& passes evals?"}
  F -->|No| C
  F -->|Yes| G["Promote agent
to primary"]
  G --> H["Keep legacy as
rollback path"]

This incremental approach has a compounding benefit: each migrated piece teaches you how the agent behaves on your real data before you bet anything larger on it. You learn which tools it needs, where it loops, what context it misses — at small scale, where mistakes are cheap. By the time you migrate the risky core, you are working from experience, not hope. Carving the work into reversible pieces is what makes the whole migration low-stress.

Run in shadow before you cut over

Before the agent's output drives anything real, run it in shadow: the agent processes live inputs alongside the existing workflow, but only the legacy output is used. You compare the two, log the differences, and study every divergence. Shadow mode is the single most valuable safety mechanism in an agentic migration, because it surfaces the agent's failure modes against production traffic with zero production consequences.

Treat divergences as a queue to investigate, not a pass/fail. Some will be the agent being wrong — exactly what you want to catch before cutover. But a meaningful fraction will be the agent being right where the legacy process was quietly wrong, handling an edge case the old script botched. Both kinds of divergence are valuable: one tells you what to fix, the other tells you the migration is already adding value. Run shadow long enough to cover the rare cases, not just a quiet afternoon.

Set an explicit bar for cutover. The agent should match or beat the legacy output on your eval dataset and show no unexplained divergences on shadow traffic over a defined window. Only when those conditions hold do you promote the agent from shadow to primary. Cutover is a decision you earn with data, not a date on a calendar.

Keep rollback one switch away

Even after cutover, the legacy path does not disappear immediately. Keep it warm and one switch away, so that if the agent misbehaves in production you can revert to the known-good process instantly while you investigate. A rollback that requires a redeploy or a code change is not a rollback you will use under pressure — make reverting a config flag, not an engineering project.

Pair the rollback with monitoring that would actually trigger it. Decide in advance what "the agent is misbehaving" means — an error rate, a divergence spike, a cost blowout — and watch for it automatically. The combination of a fast rollback and a clear trigger is what lets you cut over confidently: you are not betting the agent will be perfect, you are ensuring that if it isn't, the cost is a quick revert rather than an outage.

Only after the agent has run as primary cleanly for a sustained period should you retire the legacy path. Decommissioning too early trades away your safety net for tidiness, and tidiness is not worth an incident. Let the new workflow earn the right to be the only path by proving itself over real time, then remove the old one.

Frequently asked questions

What is the strangler pattern for agentic migration?

It is migrating a workflow one piece at a time instead of all at once — carving off a single step, moving just that step onto the agent while the rest stays legacy, proving it, then moving the next. Each piece is small enough to undo, so the whole migration stays reversible and low-risk.

What is shadow mode and why does it matter?

In shadow mode the agent processes live inputs alongside the existing workflow, but only the legacy output is used while you compare the two. It surfaces the agent's real failure modes against production traffic with zero production consequences, making it the safest way to validate before cutover.

How do I know when it's safe to cut over?

Set an explicit bar: the agent matches or beats the legacy output on your eval dataset and shows no unexplained divergences on shadow traffic over a defined window. Cutover is a decision you earn with that data, not a date you pick in advance.

How long should I keep the legacy workflow around?

Keep it warm and one config switch away well past cutover, paired with monitoring that can trigger an automatic revert. Only retire it after the agent has run cleanly as primary for a sustained period — decommissioning early trades your safety net for tidiness that isn't worth an incident.

Migrate your phone lines to agentic AI safely

CallSphere helps teams move call and message handling onto voice and chat agents the same careful way — shadow first, measured cutover, instant rollback — so the agents that answer every call and book work 24/7 earn trust before they own the line. See it live 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.