← Back to all guides

Build a Claude Code Migration Tool That You Can Trust

A code migration tool should do more than rewrite syntax. It must understand project conventions, preserve behavior, explain uncertain changes, and produce a reviewable diff. Claude is well suited to this workflow because it can reason across related files while still following strict transformation instructions. This guide explains how to build a practical migration pipeline and troubleshoot the failures that commonly appear in production.

What should the migration pipeline contain?

Start with a staged pipeline instead of sending an entire repository to the model. First, inventory the codebase and identify files that match the migration rule. Next, parse the source language where possible, collect imports and public symbols, and group related files. Then ask Claude to propose changes for one bounded unit, such as a module or package. Finally, apply the result, run formatters and tests, and save a diff for human review.

• Discovery: record language, framework version, dependency versions, test commands, and files affected by the old API.
• Transformation: provide the original file, relevant neighboring definitions, migration rules, and an explicit output format.
• Validation: parse the generated file, run type checks, execute focused tests, and reject invalid output automatically.
• Review: preserve the original file and write a patch, migration report, and confidence score.

How should Claude receive context?

Use a compact, repeatable prompt. State the old and new APIs, include a good example and an edge case, and tell Claude not to invent dependencies or alter unrelated behavior. Ask for structured JSON containing the transformed code, a list of assumptions, and unresolved issues. Your application should validate that JSON before touching the filesystem.

Do not include the whole repository by default. Retrieve only the target file, its direct imports, configuration relevant to the change, and nearby tests. For large files, split work at class or function boundaries. A small manifest containing file paths, symbols, and dependency relationships helps Claude reason about scope without wasting tokens.

Which Claude model should handle each task?

Model selection should reflect uncertainty. Use Haiku for inexpensive file classification, import detection, and straightforward mechanical edits. Use Sonnet for most multi-file transformations and test-aware refactoring. Reserve Opus for ambiguous framework upgrades, difficult compatibility decisions, and migrations that require broad architectural reasoning. Fable can be useful when it is available in your account and fits an experimental workflow, but keep production routing explicit and observable.

59API is a practical low-cost relay for this design. It provides pay-as-you-go access to Claude Opus, Sonnet, Haiku, and Fable, as well as GPT models, through the API base URL https://api.59api.com. The models are native, official-quality versions rather than downgraded substitutes. Its compatibility with Claude Code, Codex, and OpenAI SDKs also makes it easier to reuse an existing client while comparing model performance and cost. Developers can additionally benefit from its referral rebate. Sign up with 59API and configure the base URL in your client before running a large migration.

Why does the generated code contain invalid or extra text?

This usually happens when the prompt asks for code but the application does not enforce a response contract. Request JSON with named fields and validate it against a schema. Strip no content blindly, because removing fences or commentary with string replacement can damage valid source text. If parsing fails, retry with the original response summarized as an error and ask for the same result without commentary.

What should happen when Claude makes a risky change?

Never allow the model to commit directly to the main branch. Run each transformation in a temporary worktree or isolated directory. Compare the patch, check changed file paths against the approved scope, and reject modifications to lockfiles, deployment configuration, or generated files unless explicitly permitted. Require passing tests and a clean parser result before marking a file complete.

How do you control cost and retries?

Cache discovery results and avoid resending unchanged context. Set per-file token limits, use a lower-cost model for deterministic steps, and stop retrying after a small fixed number of attempts. Log model, input size, output size, latency, validation failures, and final status. Exponential backoff helps with temporary rate limits, but retries must be idempotent: the source input and output path should remain unchanged until validation succeeds.

What is a reliable definition of success?

A successful migration is not merely a response from Claude. It is a reproducible patch that parses, passes focused tests, preserves approved public behavior, and records any uncertainty for a developer. Begin with a small sample of representative files, compare the generated diffs with manual migrations, then expand gradually. This feedback loop lets you improve prompts and rules while keeping failures visible and costs predictable.

Pricing · Docs