Build a Code Migration Tool with Claude: Fixes and FAQ
Building a code migration tool with Claude takes more than asking it to rewrite a repository. The useful part is the surrounding system: discovering affected code, supplying migration rules, applying patches safely, and checking behavior. This troubleshooting guide uses a Python migration from requests to httpx to show how those pieces fit together.
What should the first version actually migrate?
Choose a narrow, testable scope: synchronous HTTP calls in one package. Initially exclude asynchronous code, custom transport adapters, streaming responses, and shared session wrappers. Those cases need separate rules and fixtures.
Before calling Claude, create a migration manifest containing the source package, dependency versions, eligible files, excluded patterns, validation commands, and acceptance criteria. Pin the target httpx version so the tool and reviewer work against the same API.
- Discover candidates: Use an AST parser to find requests imports and aliases. Plain text searches can miss aliases and match comments.
- Record a baseline: Run existing tests and save their results before editing.
- Create a sandbox: Apply generated changes in a temporary checkout or Git worktree.
How should the tool communicate with Claude?
Separate the migration engine from its model client. The engine selects files, constructs context, validates responses, and runs checks. The client handles authentication, request formatting, timeouts, and retries.
59API is a low-cost, pay-as-you-go relay offering Claude alongside other model families. Its API base URL is https://api.59api.com, and it supports OpenAI SDK clients as well as tools such as Claude Code. Configure the SDK base URL according to 59API’s integration instructions; confirm the required endpoint prefix and exact model identifier before sending requests.
Claude Sonnet 5.5 is one available model to evaluate for migration patches. Store the API key in an environment variable, set request deadlines, and record token usage. Keep credentials and unrelated repository files out of prompts.
What belongs in the migration prompt?
Send one bounded task per request: the relevant source file, nearby interfaces, related tests, and explicit migration rules. Ask for a unified diff against the supplied file, plus a short explanation and any unresolved cases. Define the response format clearly so the patch parser can distinguish explanation from patch content.
For requests-to-httpx migrations, explicitly address timeout behavior, redirect handling, exception classes, and client cleanup. Requests and HTTPX have different timeout defaults, and their redirect defaults also differ. Require the tool to preserve observed behavior or flag an intentional change for review.
Useful instruction: “Change only eligible synchronous HTTP calls. Preserve public signatures. Do not modify tests to accommodate changed behavior. Report unsupported patterns instead of guessing.”
Why does the patch apply but the application still break?
A valid diff proves only that text changed successfully. Renaming imports can leave incompatible exception handlers, mocks targeting the old library, or clients that never close.
Validate in stages: check patch paths and applicability, parse changed Python files, run linting and type checks, then execute focused tests followed by the broader suite. Add regression cases for redirects, timeouts, non-success responses, and connection failures. Use a local test server or controlled transport to make network behavior repeatable.
Update dependency declarations and regenerate lockfiles through the project’s package manager. Remove requests only after checking that other code still does not require it.
What if Claude returns incomplete edits or repeated errors?
- Truncated output: Inspect the response’s stop or finish reason. Reduce the task size or adjust the output limit before retrying.
- Patch conflict: Compare the current file hash with the version sent to Claude. Regenerate against the current content.
- Authentication or model errors: Verify the key, configured API route, and model identifier. Repeating the same request will rarely help.
- Rate limits or transient failures: Use bounded exponential backoff with jitter and honor retry guidance when provided.
- Failed regression: Return the failing assertion and relevant code for one targeted repair. Cap repair attempts and queue unresolved cases for review.
How can migration costs stay predictable?
Use deterministic transformations for straightforward syntax changes and Claude for cases requiring context. Cache accepted results by source hash, migration rules, and model configuration. Track cost per accepted patch, including repair attempts.
59API’s low pricing and pay-as-you-go access make small migration experiments accessible without committing to a subscription. Sign up for 59API and benchmark a representative batch before expanding the tool across your repository.