Bolt releases refactoring prompts for AI coding agents

Refactoring's official website

Messy code slows agents down too

Refactoring means leaving what the app does untouched while cleaning up the code underneath it. The buttons stay the same, the behavior stays the same — only the code's structure gets tidier. In the video, Bolt explained that one of the biggest reasons agents slow down or start making more mistakes isn't the agent's fault at all; it's a sign the code has gotten messy. In an unclean codebase, the agent has to burn more tokens just figuring out context, and that raises the odds of getting things wrong.

The video also featured a habit from OpenClaw founder Peter Steinberger. He said he asks himself what could be refactored next every time he merges a feature — and, according to remarks shared in the video, warned that skipping this habit means "you'll slop yourself into a corner."

Step 1: Audit and get a plan before touching any code

The first prompt Bolt published has the agent diagnose the codebase before making any changes. Here's the text as published:

"I want to refactor this project to make it cleaner and easier to maintain. Before changing any code, audit the code base and give me a plan. Look for the things that most hurt maintainability: files that are too long or doing too many unrelated things, the same logic duplicated in more than one place, components that mix data fetching, business logic, and UI, unclear or misleading names, dead code that nothing uses. For each, say what you would do to change it and how risky that change is. Do not change any code yet, do not add any features, fix unrelated bugs, or change how the app behaves. Just give me a prioritized plan so I can approve it before we touch anything."

In short, the request asks the agent to audit the codebase and produce a plan before making the project cleaner and easier to maintain — without touching any code first. It tells the agent to look for files that are too long or juggling too many unrelated jobs, logic duplicated in multiple places, components that mix data fetching with business logic and UI, confusingly named parts, and dead code nobody uses — and to flag what it would do about each one and how risky the change would be. It also makes clear the agent shouldn't touch any code yet, add features, fix unrelated bugs, or change behavior. All it should hand back first is a prioritized plan the developer can approve.

Step 2: Execute the plan one step at a time

Once the agent hands back a list of improvements, the tutorial's core advice is not to run them all at once. The bigger the codebase, the riskier it gets to push multiple refactors through at the same time, so Bolt recommends picking just the first item on the plan and running it through the next prompt.

"Refactor the first step from the plan. Rules: do not change any behavior. The app must look and work the exact same afterwards. Do not add features or fix unrelated bugs while you're in here. Only touch the files needed for this change. Keep the existing interface the same so nothing else breaks. When you're done, give me a short summary of what changed and confirm the app still behaves identically."

In short, the rules are: refactor only the first step of the plan, don't change any behavior, make sure the app looks and works exactly the same afterward, touch only the files that change requires, and keep the existing interface intact. Once done, the agent should give a short summary of what changed and confirm the app still behaves identically.

Running it in practice: results from two projects

Project	Most problematic component	Issue the agent flagged	First item executed
Internal recruiting pipeline tool	App component	A single file handled the app's entire state, CRUD operations, filtering, and layout rendering	Split database-access logic into a separate file
Meeting-summary and follow-up tool	Customer Call Card	A file of over 1,200 lines held seven sub-components, mixed API calls with display logic, and had duplicate functions and toggles	Refactor the Customer Call Card first

In both cases, the audit prompt pinpointed specific trouble spots, and the execution prompt only touched one of them. For the recruiting tool, moving five database queries into async functions in a separate file was classified as low risk and carried out immediately. For the meeting-summary tool, splitting up the 1,200-line component was classified as medium risk.

The shared skeleton behind both prompts

Shared element	How it's phrased in the prompt
Diagnosis before any code changes	"Audit and give me a plan before changing any code"
Behavior must never change	"Do not change any behavior," "the app must work exactly the same as before"
One step at a time	"Refactor only the first step of the plan"
Self-verification after completion	"Summarize what changed and confirm it behaves identically"

Drop any one of these four elements and the prompt starts to wobble. Skip the diagnosis step and the agent ends up deciding on its own what to fix. Drop the behavior-preservation rule and features can quietly shift mid-refactor. Remove the one-step-at-a-time instruction and you're right back to the risk the tutorial warned about in the first place: fixing too many things at once.

How to try this yourself

1. Start a fresh conversation to clear the context. The tutorial compared this to taking off from the start of a runway — for a big job like refactoring, you want as much room left in the context window as possible.
2. Switch to plan mode (a review-before-execution mode) and paste in the Step 1 audit prompt as-is.
3. Review the prioritized list the agent produces. Items flagged as low risk are usually safe to proceed with right away, but for anything flagged high risk, it's safer to ask the agent to explain the logic in more detail first.
4. Switch the mode to execution, and use the Step 2 prompt to have the agent refactor the first item on the plan.
5. If something goes wrong — a broken build, or behavior that's changed — the first place to check is the file scope the prompt was allowed to touch. Look first for any changes to files outside that scope.
6. When you carry this over to another project, keep the prompt wording as-is and just swap out "this project" for the actual project name. It's safer to leave the rule sentences about preserving behavior, going step by step, and summarizing at the end untouched.

Editor's take

As vibe-coding tools proliferate, so do complaints that agents are "getting dumber." This tutorial points somewhere else, though. It traces agent slowdown not to model performance but to debt piling up in the codebase. That's a principle that's held for human-written code for a long time, and Bolt has essentially confirmed it doesn't get suspended just because AI agents are involved.

Try it in a real workflow and you feel why the sequence matters. Ask an agent to just clean up the code without an audit prompt first, and it tends to touch whatever's visible and end up quietly changing behavior along the way. Follow the audit-approve-execute-one-step sequence instead, and a reviewer gets a checkpoint at every stage to judge whether the change is really safe. It's essentially transplanting the code-review habits developers get from other humans onto the agent.

For teams building side projects or internal tools with vibe-coding tools, there's always a point where you notice the code has slowed down only after piling on every feature. When that happens, it's cheaper to run one audit with these two prompts first than to keep bolting on new features. As a rule of thumb, any single file over 500 lines, or any logic copied into two or more places, is worth treating as a refactoring candidate.

Other coding-agent vendors will likely put out similar "diagnose-first" prompt guides of their own in their tutorials over the coming weeks. As competition among agents moves past raw benchmark scores, content that teaches people how to actually drive these agents well is becoming a competitive edge in its own right.