How to Migrate Legacy Code with Claude Code in 2026: From an Isolated Environment to Acceptance

Your legacy project builds only on one developer’s machine, and nobody is sure which old behavior must remain unchanged.

Fastest safe route: This week, create an isolated copy, record the current build and test results, then ask Claude Code to explain the repository before it edits anything. Migrate in small batches and accept each batch only after checks and human review. Use macOS only when the project’s build, signing, or tests require it.

For legacy-system developers: identify dependencies, entry points, and test gaps before changing code.
For technical leads: set batch boundaries, review responsibilities, and rollback conditions.
For delivery teams: establish repeatable evidence from initial assessment through regression testing.

Last updated September 24, 2026; checked against the Anthropic event page for its Claude Code modernization session and the official installation guide. Confirm commands and plugin availability against current official materials before using them.

Claude Code legacy code migration starts with a baseline

Treat this as a controlled engineering change, not a prompt that converts an entire repository. The Anthropic event page describes a legacy-code modernization demonstration and a code modernization plugin. That establishes what was presented, not a guarantee that every language, repository, or migration task can be completed automatically. Use the code modernization playbook as a reference, then verify its current guidance against your own project.

Your baseline should answer three questions:

What does the system do today?
How do you know it does that?
What evidence would let a reviewer decide whether a proposed change is safe?

If tests are absent, do not record “the model generated a plausible replacement” as the baseline. Write down manual acceptance conditions instead: sample inputs, expected outputs, business invariants, and the person who can confirm them.

This matters because old systems often carry risks that are not visible in a dependency list. A service may rely on undocumented data formats. A batch job may assume a particular working directory. A user interface may have behavior that nobody considers worth documenting until it changes. Build scripts may also depend on local credentials, operating-system libraries, or environment variables that are missing from a fresh checkout.

What should you prepare before Claude Code touches a legacy project?

Start with a copy or branch that cannot alter production data or the main line of development. Record the repository revision, build instructions, test commands, runtime dependencies, and known operational constraints. List the modules in scope and the modules explicitly out of scope.

Then capture what is verifiable. Run the existing build and tests in the intended environment. Save their output, including failures. A failing baseline can still be useful: it distinguishes old defects from new regressions. If you rely on manual checks, state how someone else can repeat them.

Claude Code project memory can help preserve stable repository guidance between sessions. Keep that guidance factual: approved test commands, module boundaries, naming conventions, and known hazards. The Claude Code memory documentation explains project memory; it should not become a substitute for confirmed business rules.

Isolation before analysis

Do not begin on the main branch. Keep generated edits separate from the working tree used for releases, and make sure the environment has no unnecessary access to production credentials or sensitive data. Git worktrees can provide separate working directories associated with repository branches; consult the Git worktree manual for the supported workflow.

Claude Code’s installation, authentication, and project startup should follow the current official documentation. Avoid copying install commands from an old note or assuming a plugin described in an event is available in your current setup. Check the official materials first, then confirm that the CLI starts in the intended repository and under the intended account.

The first prompt should request an explanation, not a rewrite. Ask Claude Code to identify major components, likely entry points, build and test instructions, and dependencies between the modules in scope. Require it to distinguish what it found in the repository from what it inferred. Ask it to flag uncertainty and point to the relevant files or configuration rather than filling gaps with invented business logic.

A useful review loop is:

Read the proposed repository map.
Check the cited files and configuration yourself.
Correct false assumptions in project notes.
Mark unresolved business rules as questions for an owner.
Only then select a small migration task.

The Claude Code CLI reference describes command-line use. Its capabilities do not remove your responsibility to control what a session can read or change. Review the security guidance and grant only the access required for the task.

Keep a clean point you can return to before every accepted batch. If the baseline is unclear, pause and improve the evidence instead of asking the model to guess what “correct” means.

Batch size and review boundaries

A good batch has a clear purpose and can be checked independently. Examples include replacing a deprecated API in a bounded module, extracting a well-understood interface, or updating a data conversion path with known inputs and outputs. Avoid mixing unrelated refactors with behavior changes: when a test fails, you need to know which change caused it.

Use this comparison to choose the next unit of work:

Work unit	Appropriate when	Evidence to request	Main risk
Single module or function	Its inputs, outputs, and dependencies are understood	Focused tests, changed-file summary, and behavior notes	Hidden callers or shared state
Interface or data-format change	Consumers can be identified and compatibility rules are known	Contract checks, representative fixtures, and consumer review	Unnoticed downstream assumptions
Broad repository rewrite	Only after boundaries and behavior are documented	Staged proposals, migration plan, and separate acceptance for each area	Review overload and hard-to-isolate regressions

For each task, ask for the proposed scope before edits. Require a short explanation of affected files, expected behavior changes, assumptions, and checks to run. Inspect the diff yourself. If the scope expands, split the work rather than accepting a large patch because it appears internally consistent.

Keep interface contracts, serialized data, database assumptions, and implicit rules under closer human review. Generated code can be syntactically plausible while changing a default, error path, ordering rule, or edge case. Ask the domain owner to decide ambiguous business behavior. Do not let a model-generated explanation become evidence that the old behavior was understood.

Can Claude Code edit legacy code directly on the main branch?

Keep migration work off the main branch. Isolate it in a separate worktree or branch and merge only after the project’s normal review and acceptance conditions pass. This gives you a place to inspect the diff, run checks, and discard or revise a proposal without making unaccepted changes part of the release line.

Isolation is not only about Git. Separate test data from production data. Keep credentials out of prompts and avoid granting tools permissions that the task does not need. If your team uses protected branches, required reviews, or CI checks, keep those controls in place; a successful local session is not a reason to bypass them.

Environment selection by build target

The migration machine should match the project’s build and test requirements, not a general preference for a particular computer. Before choosing local hardware or a remote environment, inspect language toolchains, system libraries, build scripts, signing requirements, and authentication dependencies.

Environment	Choose it when	Verify before work	Typical limitation
Existing local development machine	It matches the project’s supported build environment and has the required tools	Toolchain versions, clean checkout, and reproducible test commands	Local configuration may hide setup gaps
Non-macOS build host	The project’s target and required tools are available there	System libraries, runtime, CI parity, and access controls	Cannot replace a macOS-only build or signing step
macOS development machine or remote Mac	The project needs macOS-specific building, signing, or testing	Required Xcode setup, signing access, test data, and release permissions	Adds environment and access-management work

macOS is not a default requirement for legacy code modernization. Use a Mac when the project’s actual workflow requires macOS—for example, a macOS-targeted build, a signing step, or tests that must run on that platform. Apple’s documentation on creating distribution-signed code for Mac is the relevant reference when distribution signing is part of the release path. Do not infer that every project using Claude Code needs a Mac.

If you are evaluating a remote Mac, compare the required toolchain and access model before committing to it. Hashvps’s package details can be reviewed alongside your build requirements; confirm availability and terms for the specific environment rather than assuming a particular configuration.

Acceptance evidence, not generated-code confidence

Code migration acceptance should compare the candidate with the old system’s observable behavior. Run the existing unit and integration tests, then add checks for important behavior that the current suite does not cover. Compare representative inputs and outputs. Review business invariants such as permitted state transitions, data relationships, or error handling.

Acceptance area	What you check	Evidence to keep	When to stop
Build and tests	The documented build and relevant test suites complete in the target environment	Command output, CI result, and environment notes	A new failure has no identified cause
Behavior	Representative cases and business invariants still hold	Fixtures, output comparisons, or signed-off manual results	An expected result is ambiguous or changed
Dependencies and security	Added, removed, or upgraded dependencies and access needs	Diff review and security notes	A change has not been assessed by the owner
Rollback readiness	The accepted change can be isolated or reverted	Commit reference and recovery instructions	Recovery depends on undocumented steps

These are project acceptance checks, not a claim that an automated test suite proves the absence of defects. If a behavior is not testable yet, record that limitation and assign a reviewer who can make the decision. The Claude Code security guidance can inform your review of permissions and security boundaries; it does not replace your organization’s application security process.

For each batch, retain the original request, the resulting diff, the checks run, known gaps, reviewer decision, and rollback point. Record who owns unresolved questions. Keep failures visible rather than editing the test report to make the batch look complete.

How do you confirm AI changes preserve old system behavior?

Compare behavior against the captured baseline, not against the model’s description of its own changes. Run the same representative inputs through the old and new versions where feasible. Check outputs, side effects, error conditions, and important business invariants. If the outputs differ, decide whether the difference is an approved modernization or an unintended regression; document that decision and who approved it.

Where tests are missing, add characterization tests or a repeatable manual procedure before migrating the behavior. That work may expose undocumented rules, but it gives the team a concrete basis for reviewing later changes. A green test run only supports the cases the tests actually cover.

Long-term maintenance and rollout

Before starting the next batch, review the previous batch’s open issues and any new production evidence. After release, monitor the system using its existing operational signals. When a regression appears, preserve the relevant inputs and logs, identify the change that introduced it, and add a test that prevents the same failure from disappearing from view again.

Keep a migration record that can be reused without treating a past prompt as a universal recipe. Useful reusable material includes verified setup steps, accepted test commands, module-specific constraints, and reviewer checklists. Reassess it when the build system, dependencies, or product behavior changes.

Use this short go/no-go checklist before expanding the migration:

[ ] The current revision and baseline results are recorded.
[ ] The next batch has a bounded scope and named reviewer.
[ ] Unconfirmed business rules are assigned to an owner.
[ ] Relevant tests or manual acceptance steps are ready.
[ ] The build environment matches the project’s actual target.
[ ] A rollback point and unresolved risks are documented.

If one of these is missing, keep the work in assessment or preparation. Moving to another module does not make an unverified change safer.

Choosing between your current setup and a Mac

A developer’s existing workstation may be sufficient for repository analysis and builds that match its operating system. A non-macOS cloud host may also be the right choice when its toolchain matches the project. Neither option is suitable for a macOS-only signing or test stage if it cannot provide that target environment. Conversely, a Mac adds no migration value when the project has no macOS-specific requirement.

The practical trade-off is between reusing a familiar machine, maintaining a matching build host, and arranging temporary macOS access for the stages that need it. A remote Mac can avoid buying hardware for a short-lived signing or compatibility task, but you still need to assess access, setup, data handling, and the project’s actual testing needs. Review Hashvps’s service terms before choosing a rental environment, and confirm that it fits the required workflow.

If your migration plan includes macOS-only builds or signing, compare your current setup with a temporary Hashvps Mac environment before the team reaches that stage. If the project builds and tests on another platform, stay with that platform rather than renting a Mac by default.