The pit stop before the first edit
Every refactor has a moment where the code still works, the tests are still green, and nothing has been decided yet. That moment is the safest place to do your thinking. Once you start editing, the code becomes a moving target and any plan you make gets shaped by the half-finished state you are standing in. Take the pit stop first. Spend one focused session building the plan, then open the editor.
Planning with a model is not about asking it to guess what your codebase looks like. It is about giving it a clear picture and asking it to reason out loud in plain language. Treat the model as a thinking partner rather than an author. The plan stays yours. The model helps you spot gaps, name risks, and turn a vague intention such as clean this up into a sequence of small, reversible steps.
The payoff is practical. A good plan tells you what to touch first, what must keep working, and how to step back if something goes wrong. It also gives you a definition of done that you can check without re-reading the whole codebase at the end.
Newcomers often skip this because planning feels like procrastination. In a change that touches shared code, it is the opposite: it is the cheapest place to discover that your idea will not work.
Map the code before you change it
Before you ask for a plan, gather the raw material. Open the files that matter and copy the parts the model needs to reason about: entry points, the functions you intend to change, the types that flow through them, and the tests that cover them. Trim aggressively. The goal is a map, not a mirror.
A useful map is written in plain language and answers a handful of questions.
- Which entry points reach this code, and who calls them
- What data flows in and out, and where it gets transformed
- Which invariants must hold after every change, such as sort order or empty input
- Which tests already pin the current behaviour, and which gaps they leave
- Which neighbours share these types or names and would notice the change
Write the map as if you were briefing a teammate on their first day. Short sentences beat clever ones. If you cannot explain a step, that is not a wording problem, it is your first finding: something in the code is unclear to you, and it will still be unclear during the refactor.
A coding agent can gather a lot of this for you. SwiftRelay is a pay-as-you-go relay for Claude, GPT, Gemini, DeepSeek and other models, and it works with Claude Code, Codex, Gemini CLI and any OpenAI-compatible SDK. Claude Code and Gemini CLI take the bare host, https://api.fastapirelay.com, while OpenAI SDKs add /v1 to that host. Billing is per token, so a planning session costs only the words you trade.
Write a brief the model can answer
Now give the model a brief instead of a vibe. A good brief has four parts: the goal in one sentence, the map from the last step, the constraints, and the questions you want answered. Constraints matter more than newcomers expect: files that must not change, behaviour that must be preserved, naming conventions, and anything else the code depends on.
Be specific about the ask. Instead of asking for something cleaner, ask for the smallest sequence of changes that removes duplication between two named functions while keeping the public signatures and the current test outcomes. The second request can be checked. The first one cannot.
Ask for the plan in stages rather than one big answer. First the diagnosis, then the steps, then the risks, then the verification. Staged answers are easier to challenge and easier to cut down when they get long.
A strong reading and reasoning model such as Claude Sonnet 5.5 works well as the planning partner, and a lighter model can handle the shortening work when you want a compact version to work from. Keep one conversation for the whole planning session so the model holds the context of the map and the brief.
End every answer with a request for the model to state what it is unsure about. Those open questions are usually the next thing you should go and read yourself.
Attack the plan before you trust it
A plan that has not been attacked is just a wish. Before you trust it, ask the model to play the skeptic. Make it argue against the steps it just gave you.
- Which step is most likely to break something outside the map
- What did we assume about the code that the code does not actually do
- What happens for empty input, missing values, and error paths
- Which caller would notice if a name or signature changed
- Which test would fail first if this step went wrong
- How would we undo this step on its own
Then ask for a rollback note beside each step, one or two lines describing how to put things back. When a step cannot be undone cleanly on its own, that is a sign to split it in two: one step that prepares, and one step that lands.
It also helps to ask the model to walk one concrete input through the changed code by hand. Tracing a single value from entry point to output catches ordering mistakes and off-by-one assumptions faster than reading the code again.
Do the same with the tests. Ask which new test would pin the behaviour you are about to change, and write that test before the change. If a planned step cannot be protected by a test, treat it as higher risk and keep it small.
Turn the plan into a checklist and run the first lap
The last move is to turn the plan into a checklist with a green light at the end of every line. Each item should be small enough to finish in one sitting and to describe in one sentence.
- The exact files or functions this step touches
- The behaviour that must stay the same
- The test that proves it
- How to undo it
- What tells you the step is done
Then run the first lap. Before the first edit, run the existing tests and record the outcome so you have a baseline to compare against. Make the change exactly as the checklist describes, run the tests again, and only then move to the next line. Small commits keep each step reviewable and easy to step back from.
When a step surprises you, stop and update the plan before continuing. A plan that drifts from reality is worse than no plan, because it makes you confident in the wrong thing. Two minutes of editing the checklist saves an hour of confusion later.
Keep the original brief and the final plan in the repository, next to the change. The next person who touches this code will thank you, and that person is often future you.
When you want a planning partner for the session, sign up for SwiftRelay. New accounts receive a small gift credit to get started, and inviting friends earns 14% of their top-ups.
Plan first, edit second, and the green light means something.