Guardrail Tests: Refactor Legacy Code Safely

Guardrail tests pin the current behavior of a piece of code so a refactor can't change it without you noticing. You identify the current state, write tests that capture it, 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.

They matter 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 rewrite a module without hesitation. Without tests that pin the old behavior, you have no proof the new code does the same thing.

Write them first, while the old behavior still exists to capture. Tests written after a refactor only prove the new code agrees with itself. The old behavior is already gone by then, so they can't tell you whether you kept it. Tests written first turn any drift the refactor introduces into a red test instead of a production incident.

Start in Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. Press Enter for the full definition. before you let Agent write any code. Plan mode researches your repo, asks clarifying questions and writes a Markdown plan that you and the agent refine before anything changes. You can hand it a vague, half-formed prompt and use the planning pass to check your assumptions and tighten the scope. Cursor's Plan mode docs say the hard part is often figuring out what change should be made.

Grafana was the workshop's target: an open-source codebase about ten years old, with thousands of contributors. The presenter ran one Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. Press Enter for the full definition. 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 without breaking anything else. Plan mode came back with a Markdown plan that listed the items as P0 through P2, each with a problem statement and its own unit-test plan.

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

This takes engineering discipline, because no setting fixes it. Define the golden state explicitly: the happy-path input and the output it should produce. Give that pair to the agent as the test's anchor, or write it into the plan and have the agent follow it. Then inspect the generated test code, because Cursor speeds up your process but doesn't check what is under test for you.

Apply the workshop's four remedies. Each one changes how you scope the task or check the output, and all four aim to keep the agent honest about failures.

• Keep the rule file lean and specific. A long rule competes with everything else for the agent's attention, and 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, rule context can get overwritten as the window fills, and the agent quietly stops obeying it. Open a fresh agent that only writes and runs tests.
• Add a validator, either a skill or a subagent, that runs the test, reads the output and reruns it to confirm a real failure surfaces before the test is accepted.
• On a complex suite, run tests in their own agent instead of mixing them with feature work, so nothing crowds out the verification step.

Once the guardrails pass 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 requirements are pinned up front, so a set of passing behavioral tests guides 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, such as swapping a slow Java path for Go, while keeping inputs and outputs identical.
3. 3Verify before you move on. Re-run the guardrail suite, and advance to the next item only while the current tests stay green. The plan sets the order.
4. 4Repeat item by item down the ranked P0 to P2 list, so behavior never drifts more than one small step at a time.

Because the suite gates every step, a change that alters pinned behavior shows up as a red test before you move on. On a codebase too large to review by eye, that gate is what catches a silent rewrite.

Plan with a larger reasoning model and build with a leaner, faster one. In the demo, the presenter planned with an 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. Press Enter for the full definition. models, which the presenter described as fast thinking models tuned for execution. When the plan is ready, pick the build model and click Build to start writing code.

Check your Cursor subscription before you copy that split. Opus-class models are third-party models, which the Free and Plus plans don't include, and Plus doesn't include Auto.

Connect 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. Press Enter for the full definition., and the agent can push the migration plan into a Confluence doc and file Jira stories straight from the plan. The workshop presenter appended a final task to the plan: update the Confluence doc with the migration details. Separately, the presenter asked the agent to turn the TODO comments in the alerting module into Jira stories.

Plan first, then report and ticket. Run Plan modeA mode that makes no edits: it researches the codebase and produces an editable plan you review before any code changes. Press Enter for the full definition., refine the plan, and let its last task fan out the results: 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 describe to the agent and wrap as a repeatable skill.

Guardrails reduce risk, but they don't remove the need for judgment. Four limits matter.

• Guardrails only protect the behavior you captured. Untested paths can still change silently, so the real safety boundary is how well your tests cover the critical behavior.
• You still have to define the golden state. The agent won't decide what 'correct' means for you, and 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. Press Enter for the full definition.-driven reporting and ticketing is convenient but not guaranteed. Integrations like the Atlassian MCP can fail mid-run, so check that Confluence pages and Jira tickets landed.

Cursor speeds up a sound engineering process. You still have to know which behavior you are protecting, and prove that your tests can fail.