Project 42Start learning
Module 7 of 7 · 54 min

Migrate Claude Workflows with Evidence

Inventory dependencies, separate portable contracts from Claude-specific behavior, compare candidates, canary safely, and preserve rollback when changing models or providers.

Anthropic

By the end

You will be able to

  • Inventory model, prompt, API, content-block, tool, data, safety, and operational dependencies.
  • Separate portable application contracts from Claude-specific capabilities and behavior.
  • Use controlled evaluation and canary evidence instead of assuming model substitution is equivalent.
  • Migrate with coexistence, monitoring, rollback, and deprecation ownership.
01

Inventory before changing

Find every model reference, API endpoint, SDK, authentication path, request parameter, system instruction, content-block parser, tool schema, stop-reason handler, prompt assumption, data control, evaluation threshold, dashboard, and runbook.

Include direct Claude use, cloud-hosted variants, batch or cache behavior, coding agents, and shadow integrations. Assign an owner and evidence link to every dependency.

02

Separate portable contracts from provider specifics

User outcomes, application schemas, authorization policy, evaluation rubrics, telemetry fields, and postconditions can often remain portable. Message roles, system-instruction placement, content blocks, tool-result protocols, model identifiers, thinking controls, and hosted features may be Claude-specific.

Create an adapter boundary without pretending providers are identical. Preserve native capability where it matters and expose unsupported behavior explicitly instead of silently weakening the workflow.

03

Read current migration and lifecycle evidence

Use the official migration guide for the exact source and target model and deployment platform. Check parameter changes, unsupported patterns, tool behavior, output differences, context and budget implications, and required SDK changes.

Track lifecycle states and retirement dates from the official deprecation page. Partner-hosted platforms may have different identifiers, availability, and retirement schedules, so verify the actual deployment.

04

Evaluate and canary the candidate

Run baseline and candidate against identical representative, edge, adversarial, and incident cases. Compare quality, safety, refusals, structured output, tool selection and arguments, latency, usage, cost, and critical slices.

Use shadow traffic or a small canary where policy allows. Define promotion, hold, and rollback thresholds before launch; monitor by version and reconcile any side effects before switching traffic.

05

Migrate reversibly and close deliberately

Use configurable routing, versioned prompts and adapters, compatible data migrations, dual-read or dual-run patterns when justified, and a tested rollback path. Avoid irreversible cleanup until the observation window passes.

Close only after production evidence meets thresholds, rollback is proven, documentation and runbooks are current, deprecated usage is absent or accepted, and owners acknowledge residual risks. Migration to another provider follows the same evidence pattern.

Practice activity

Plan and rehearse a Claude migration

  1. Inventory one workflow across code, configuration, prompts, messages, tools, data, evaluations, telemetry, operations, and deployment platform.
  2. Create a portable-versus-Claude-specific contract table and map each incompatible behavior to an adapter, redesign, or explicit non-support decision.
  3. Run a baseline/candidate evaluation and define canary, promotion, hold, rollback, and deprecation-exit criteria.
  4. Rehearse rollback from a synthetic failed canary and record timing, evidence, data reconciliation, owners, and communication.

What to produce

  • A dependency inventory and compatibility matrix with official migration and lifecycle sources for the exact deployment.
  • A baseline/candidate report, canary plan, successful rollback rehearsal, and signed production closeout checklist.

Reflect before continuing

Which dependency looked portable until evaluation revealed a Claude-specific behavioral contract?

Evidence

Sources and verification

Knowledge check

Make it stick.

Pass at 80%

Choose the strongest answer for each question. Your attempts become part of your device-local transcript.

01What should happen before a model identifier changes?
02Which contract is most portable?
03Why verify the deployment platform?
04When should canary thresholds be defined?
05What proves migration closeout?