You restructure an old module without changing its behavior or breaking its callers by letting Atlas close the callsite gap before it touches anything. Atlas maps the module's public surface with the lsp tool's documentSymbol operation, runs findReferences on each exported symbol to enumerate every callsite, pins behavior by running the existing tests with bash to record a green baseline, then restructures with apply_patch, which anchors on context lines and refuses to apply against a drifted file. Atlas re-runs the tests with bash after each hunk lands, not once at the end.
How do I refactor a legacy module without breaking its callers?
Atlas refactors a legacy module by enumerating the callers first, using 2 lsp tool operations. documentSymbol maps the module's real public surface, and findReferences runs on each exported symbol to produce the true callsite list, all before a single line of the module changes.
A legacy module is dangerous precisely because nobody remembers who depends on it. The Atlas refactoring workflow treats that ignorance as the first problem to solve rather than something to discover during the change. documentSymbol asks the language server for the module's declaration list, which gives the real public surface instead of the one described in a stale comment. findReferences is then run on each exported symbol, and the union of those results is the true blast radius. Only once the callsite list exists does the restructuring begin, and every subsequent change is evaluated against a known set of dependents.
How do I pin the behavior of a module before refactoring it?
Atlas pins behavior first: run the existing tests with the bash tool and record the green baseline before changing 1 line. A refactor is defined by preserving behavior, and without a recorded green run from before the change, there is no way to prove afterward that the behavior was preserved.
The word refactor promises that behavior did not change, and the only evidence for that promise is a test run from before the change compared against one from after. Atlas records the baseline explicitly with the bash tool, running the module's existing tests and capturing the green result. If the suite is already red, that is information you needed before starting, not a surprise to discover halfway through when you cannot tell your breakage from the pre-existing breakage. The baseline turns every later bash run into a comparison rather than an isolated data point.
Why does Atlas use apply_patch instead of edit for a refactor?
Atlas restructures a legacy module with apply_patch, which seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted. Structural refactoring moves code across a file, so 1 patch anchored on context lines is safer than a chain of independent edits against shifting line numbers.
Refactoring is not a single replacement, it is many coordinated ones. apply_patch is the Atlas tool built for that. Each hunk carries context lines and old_lines, and apply_patch seeks that context in the current file before applying. If the file has drifted, because an earlier hunk moved the code or because something else changed it, apply_patch fails with Failed to find context rather than applying the hunk to whatever happens to sit at that line number now. A refactor that half-applies is worse than one that does not apply at all, and apply_patch makes the failure loud.
How often should I run tests during a refactor?
Atlas re-runs the tests with the bash tool after each hunk lands, not once at the end. A refactor that applies 8 hunks and then fails the suite gives you no information about which hunk broke it, while running the tests after each hunk isolates the breakage to the change that caused it.
Batching verification to the end of a refactor is how a two-hour refactor becomes a two-day bisect. The Atlas workflow runs the tests through bash after every hunk that apply_patch lands, comparing against the green baseline recorded before the work started. When the suite goes red, the responsible hunk is the one that just applied, and the fix is immediate and local. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, which means reverting a single bad hunk does not mean reverting the whole refactor.
How do I track partially migrated callsites in Atlas?
Atlas tracks the remaining callsites in a todowrite list so a partially migrated module cannot be mistaken for a finished one. After the lsp tool's findReferences operation enumerates every callsite, each unmigrated caller becomes a todowrite entry, and the refactor is done when 0 entries remain, not when the tests happen to be green.
The most damaging outcome of a legacy refactor is one that stops halfway and looks finished. Half the callers use the new structure, half use the old one, the tests pass because both paths still work, and the module is now more confusing than before it was touched. Atlas prevents that with todowrite. Each callsite from the findReferences enumeration is an entry, and the list is visible in the Atlas terminal-native TUI, which is rendered with SolidJS through the OpenTUI renderer. A refactor is done when the todowrite list is empty, not when the tests are green.
Where does the human approve during an Atlas refactor?
Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so each of the apply_patch hunks in a refactor is reviewed before it lands. Every Atlas tool call is permission-gated against 3 rule types, allow, ask, and deny, which also covers the bash test runs.
The mapping phase of an Atlas refactor changes nothing: the lsp tool's documentSymbol and findReferences operations and the read tool are read-only, and each is still permission-gated. The approval that matters comes at the diffs. Because Atlas re-runs the tests after each hunk, the review is also incremental: you see a hunk, you approve it, the bash run tells you whether the module still behaves. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, and Atlas reads git branches, status, and diffs, and can stage and create commits on your behalf once the refactor holds.
Step by step
- 01Map the module's public surface with the lsp tool's documentSymbol operation, so the refactor is planned against the real export list rather than a stale one.
- 02Run findReferences on each exported symbol to enumerate every callsite. The risk in a refactor is silent breakage at a callsite you did not know about.
- 03Pin behavior first: run the existing tests with the bash tool and record the green baseline before changing anything.
- 04Read the module and its callers with the read tool so the restructuring is designed against the code that actually exists.
- 05Restructure with apply_patch, which seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted.
- 06Approve each change at the diff. Atlas computes a unified diff for every file edit and surfaces it for approval before writing.
- 07Re-run the tests with bash after each hunk lands, not once at the end, so a red suite points at the hunk that caused it.
- 08Track the remaining callsites in a todowrite list so a partially migrated module cannot be mistaken for a finished one.
Frequently asked questions
- how to refactor legacy code without breaking anything
- Enumerate the callers first. Atlas maps the module's public surface with the lsp tool's documentSymbol operation, runs findReferences on each exported symbol, records a green test baseline with bash, and only then restructures with apply_patch.
- how do I find every caller of a legacy module
- Use the Atlas lsp tool. documentSymbol enumerates the module's exported symbols, and findReferences on each one returns the authoritative callsite list from the language server, which is the true blast radius of the refactor.
- apply_patch vs edit for refactoring in Atlas
- Use apply_patch for structural refactoring. It seeks each hunk's context and old_lines and fails with Failed to find context if the file has drifted, which is safer than chaining edits against line numbers that keep shifting.
- what does Failed to find context mean in Atlas
- It means apply_patch could not locate a hunk's context lines in the current file, so the file has drifted from what the patch expects. Atlas refuses to apply the hunk rather than writing it to the wrong location.
- when should I run tests during a refactor
- After each hunk lands, not once at the end. Atlas re-runs the tests with bash after every apply_patch hunk, so when the suite goes red the responsible change is the one that just applied instead of one of many.
- how do I avoid leaving a refactor half finished
- Track it. Atlas puts the remaining callsites from the findReferences enumeration into a todowrite list, so a partially migrated module cannot be mistaken for a finished one just because the tests happen to pass.
- can I roll back a refactor an AI agent applied
- Yes. Atlas snapshots file changes as git patches so edits can be diffed and rolled back, and every apply_patch hunk arrives as a unified diff you approve before it is written.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Refactor a Legacy Java Module with Atlas (2026)
Refactor a legacy Java module with Atlas in 2026. Enumerate callers with lsp findReferences, restructure with apply_patch, and prove behavior with JUnit 5 via mvn test.
Refactor a Legacy Module in Remix with Atlas in 2026
Atlas helps Remix developers in 2026 safely restructure legacy modules without changing behavior or breaking callers. Leverage `vitest`, `pnpm`, and `prettier` for a robust refactoring workflow.
Refactor a Legacy Scala Module with Atlas in 2026
Streamline legacy Scala modules in 2026 with Atlas. Safely refactor code, ensure no behavior changes, and maintain caller compatibility using sbt, ScalaTest, and scalafmt.
Refactor a Legacy Module in Swift With Atlas (2026)
Restructure an old Swift module without breaking its callers. Atlas maps the public surface with the lsp tool, patches with apply_patch, and reruns swift test each hunk.
Refactor a Legacy Module in Angular with Atlas in 2026
Refactor legacy Angular modules safely in 2026 with Atlas. Maintain behavior, track callsites, and ensure code quality using `ng test`, `pnpm`, and `prettier`.
Refactor a legacy module in Python with Atlas (2026)
Refactor a legacy Python module with Atlas in 2026: enumerate callsites with lsp findReferences, restructure with apply_patch, and prove behavior with pytest.
Refactor a legacy module in Nuxt with Atlas in 2026
Streamline your Nuxt 3 project by refactoring legacy modules with Atlas. Safely restructure code, maintain behavior, and prevent breaking changes using `vitest` and `pnpm` in 2026.
Refactor a Legacy PowerShell Module with Atlas in 2026
Safely refactor legacy PowerShell modules in 2026 with Atlas, the terminal-native AI coding agent. Maintain behavior, prevent breaking changes, and integrate with Pester and PSScriptAnalyzer.