Build a Claude-Powered Code Migration Tool
What You Are Building
Code migrations are repetitive but risky: changing a framework, upgrading a language version, or replacing an API can affect hundreds of files. In this walkthrough, you will build a command-line migration tool that uses Claude to inspect source files, propose edits, validate the result, and write changes only after review.
The design is deliberately conservative. Claude produces a structured migration plan and a complete replacement file, while your program controls file selection, parsing, validation, backups, and approval.
Choose a Small, Testable Scope
Start with one migration rule. For example, convert a JavaScript API from moment().format() to the native Intl.DateTimeFormat API. Define the input and output clearly:
- Input: JavaScript or TypeScript files containing the old API.
- Output: equivalent code using the new API.
- Constraint: preserve behavior, exports, comments, and unrelated formatting.
- Failure policy: reject the change when validation fails or the model is uncertain.
A narrow first version gives you fixtures for automated tests and makes model output easier to evaluate.
Configure Claude Through 59API
Use an OpenAI-compatible client so the model layer remains replaceable. 59API provides pay-as-you-go access to Claude Opus, Sonnet, Haiku, and Fable through https://api.59api.com. Its relay uses official-quality models without a hidden downgrade, making it practical to use a stronger model for difficult files and a cheaper model for classification or simple transformations.
Set environment variables rather than hard-coding credentials:
- OPENAI_API_KEY: your 59API key.
- OPENAI_BASE_URL: https://api.59api.com/v1, if your SDK expects the versioned OpenAI path.
- MIGRATION_MODEL: a Claude model supported by your account.
Check the current 59API documentation for the exact model identifiers and endpoint format before deploying. Its low-cost, usage-based pricing helps keep experiments affordable, and the referral rebate can reduce future API spend when colleagues join through your account.
Build the Migration Loop
Your CLI should process one file at a time. First, collect files with a standard glob library and exclude directories such as node_modules, build output, and version-control metadata. Read the file, then send Claude a prompt containing the migration rule, the source text, and strict output instructions.
Ask for JSON rather than conversational prose. A useful response contract is:
- changed: boolean.
- reason: a short explanation.
- code: the complete resulting file.
- warnings: an array of unresolved concerns.
Tell Claude to return the original source when no change is needed, never invent imports, and never wrap the JSON in Markdown fences. Parse the response with a real JSON parser and reject malformed output. Do not apply partial snippets with string replacement; complete-file output is easier to diff and validate.
Validate Before Writing
Validation is the safety boundary. Compare the returned code with the original, create a temporary file, and run the project formatter, type checker, or parser against it. For JavaScript, tools such as the TypeScript compiler, ESLint, and a project test command provide useful checks.
Write a backup or require Git status to be clean before modifying files. Produce a unified diff and require an explicit --apply flag before writing. In dry-run mode, show the file path, model warnings, and diff without changing the repository.
Improve Reliability in Production
Add retries with exponential backoff for temporary API failures, request timeouts, token limits, and structured logs containing the file path, model, latency, and usage. Never log API keys or unredacted proprietary source code. Set concurrency limits so a large repository does not exhaust your budget or trigger rate limits.
Create a fixture suite with representative files: simple replacements, nested expressions, comments, unusual formatting, and files that should remain unchanged. Measure parse success, test success, unnecessary-change rate, and average cost per file. Once the tool is dependable, add an approval queue or pull-request integration.
Next Step
Begin with a dry-run migration on a small repository, review every diff, and expand the rule set only after the validation pipeline is trustworthy. If you want affordable access to Claude while building and testing the tool, sign up for 59API and start with pay-as-you-go usage.