Guardrail Tests: Refactor Legacy Code Safely

Guardrail tests pin the current behavior of a piece of code so a refactor cannot change it without you noticing. You identify the current state, write tests that capture that state, then make the minimal code change while keeping the same inputs and outputs. They are sometimes called characterization tests: they describe how the code behaves now, not how you wish it behaved.

This matters most on large, idiosyncratic repos where no one person holds the whole behavior in their head. A coding agent has a bias for action and will happily rewrite a module. Without a behavioral net under it, you have no proof the new code does what the old code did. The tests are that net.

Tests written after a refactor only prove the new code is self-consistent. They cannot tell you whether you preserved the old behavior, because the old behavior is already gone. Tests written first capture the behavior while it still exists, so any drift the refactor introduces shows up as a red test instead of a production incident.

Start in plan mode, not in agent mode. Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. runs the same search-and-retrieval over your repo but produces a Markdown plan you and the agent refine before any code is written. You can hand it a vague, half-formed prompt and use the planning pass to check your assumptions and tighten the scope. On a big repo this is where the real work happens.

In the workshop the target was Grafana - an open-source codebase that has been around for about ten years with thousands of contributors. The presenter ran one plan-mode prompt: find all the FIXME and TODO comments, rank the top five most critical, write a testing plan that pins current behavior, then migrate to the new functionality while making sure nothing else breaks. Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. came back with a Markdown plan listing the items as P0 through P2, each with a problem statement and a per-item unit-test plan.

A test that has never failed proves nothing. If a generated test asserts the wrong thing - or asserts nothing at all - it will pass green and give you false confidence. The discipline is old and still applies: never trust an automated test you did not see fail. Make each guardrail fail for the reason you expect, then make it pass.

The fix is engineering discipline, not a setting. Determine the golden state - the happy-path input and the output it should produce - explicitly. Feed that input/output pair to the agent as the anchor for the test, or codify it in the plan and have the agent adhere to it. Then inspect the generated test code. Cursor is an accelerant to your process here, not a replacement for verifying what is actually under test.

Four remedies came out of the workshop, all aimed at keeping the agent honest about failures. None of them is a magic flag; they are about how you scope the task and verify the output.

• Keep the rule file lean and specific. A long rule competes with everything else for the agent's attention; a short one aimed at exactly this problem is more likely to be followed.
• Keep the context window as empty as possible for test work. In a long conversation the rule context can get overwritten as the window fills, so the agent quietly stops obeying it. Open a fresh agent that only runs and writes tests.
• Add a validator step - a skill or a sub-agentA child agent a main agent spawns to work in parallel with its own context window, handing results back so the parent's context stays clean. that runs the test, reads the output, and reruns to confirm a real failure surfaces before the test is accepted.
• For a complex suite, isolate test-running in its own agent rather than mixing it with feature work, so nothing crowds out the verification step.

Once the guardrails are green against the old code, they become the contract the new code must satisfy. This is test-driven development adapted to agents: agents work well when the requirements are pinned up front, so a skeleton of passing behavioral tests is an ideal guiding light for the implementation that follows.

1. 1Pin the behavior: write guardrail tests that capture current inputs and outputs, and confirm each fails before it passes.
2. 2Make the minimal change: refactor or migrate the smallest unit that moves your goal - e.g. swap a slow Java path for Go - keeping inputs and outputs identical.
3. 3Verify before moving on: re-run the guardrail suite. Only advance to the next item once the current tests are still green. The plan drives the order.
4. 4Iterate item by item: walk the ranked P0-P2 list, repeating pin-change-verify so behavior never drifts more than one small step at a time.

Because the suite gates every step, the agent is constrained to changes that keep the tests passing. That is what stops it from silently rewriting behavior on a codebase too large to eyeball.

Split the job. Use a larger, more capable reasoning model to produce the high-level plan, then a leaner, faster in-house model to do the building. In the demo the presenter planned with a frontier Opus-class model and built with one of Cursor's in-house ComposerCursor's own fast coding model, tuned for the editor and priced well below frontier models; the recommended day-to-day model for executing a plan. models, which are fast thinking models tuned for execution. After plan mode you pick the build model and click Build to move into the writing phase.

Guardrail work is also a reporting and ticketing job. With the Atlassian MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs. connected, the agent can push the migration plan into a Confluence doc and file Jira stories straight off the plan. In the workshop the presenter appended a final task to the plan - update the Confluence doc with the migration details - and separately asked the agent to turn the TODO comments in the alerting module into Jira stories.

The recommended order is plan first, then report and ticket. Run plan mode, refine the plan, then let the last task fan it out: a Confluence page for the team and a set of Jira tickets to distribute the work. Anything you could do by hand in Atlassian, you can outline to the agent and wrap as a repeatable skill.

Guardrail tests reduce risk; they do not remove judgment. A few honest limits to hold onto.

• Guardrails only protect behavior you actually captured. Untested paths can still change silently, so coverage of the critical behavior is the real safety boundary - not the green checkmark.
• You still have to define the golden state. The agent will not decide what 'correct' means for you; pinning the happy-path input and output is human work.
• Generated tests need a human read. Inspect the assertions for the silent-fail patterns above before you trust the suite as a spec.
• MCPModel Context Protocol. A standard that lets an AI agent pull in context from outside the repo, like Jira tickets or internal docs.-driven reporting and ticketing is convenient but not guaranteed. Verify Confluence pages and Jira tickets landed; integrations like Atlassian can be unreliable mid-run.

The throughline: Cursor accelerates a sound engineering process. It does not replace the discipline of knowing what behavior you are protecting and proving your tests can fail.