Refactoring with AI coding agents: a tech-debt ticket Claude Code and Codex can finish safely
"Clean up the invoices service" is the most dangerous ticket you can give a coding agent. It will clean it up, and somewhere in a 2,000-line diff one behaviour will change. Here is a seven-field refactor ticket that Claude Code and Codex can finish, and a reviewer can approve, without guessing.

"Clean up the invoices service" is not a ticket an agent can finish
Refactoring looks like the perfect job for a coding agent. The work is tedious, the rules are mechanical, and nobody on the team wants to spend a week moving functions between files. So the tech-debt ticket that has sat in the backlog for a year finally gets assigned: "Clean up the invoices service."
The agent does exactly that. It splits the file, renames the helpers, replaces three old patterns and updates every caller. The tests pass. The diff is 2,000 lines. Somewhere in it, a rounding rule moved from before the tax calculation to after it, and nobody will notice until a customer's invoice is off by a cent. A refactor is the one kind of change where success means nothing visible happened, which makes it the easiest kind to get quietly wrong.
In 2026 the context for that refactor is also scattered. The debt ticket is in Jira, the architecture decision in Confluence, the migration notes in Notion, the screens that must not change in Figma and the module map on a Miro board. Each one is another connection for the agent and, if you use the vendor's built-in AI, another credit meter. Our AI credit fatigue piece adds those meters up.
This guide gives you a seven-field refactor ticket written for an agent reader, shows what Claude Code and Codex already expect from a refactor, and walks through how to run one milestone at a time so the reviewer can say yes without reading every line.
What Claude Code and Codex already say about refactoring
Both vendors publish refactoring guidance, and it agrees on almost everything:
- Claude Code. The common workflows page has a refactor recipe in four steps: find the deprecated usage, get suggestions, apply the change while keeping the same behaviour, then run the tests for the refactored code. Its tip is one line: do refactoring in small, testable increments. The best practices page adds the rule behind it: give Claude something it can run that comes back pass or fail, and ask for evidence, meaning the command it ran and its output.
- Claude Code plan mode and worktrees. In plan mode Claude makes no edits until you approve the plan, which is where a refactor should start. A worktree, started with claude --worktree, is a separate checkout on its own branch, so a long refactor does not block the rest of your work. For changes like a schema move, where every reader of the old shape must be found, the docs suggest raising the effort level.
- Claude Code checkpoints. The /rewind command (alias /undo) restores code and conversation to before any prompt. The docs are explicit about the limits: files changed only by shell commands are not tracked, and checkpoints are not a replacement for version control. Commit after every green milestone.
- Codex. OpenAI's refactor use case asks Codex to remove dead code and modernize legacy patterns without changing behaviour, to run the smallest useful check after each pass instead of batching the whole cleanup into one diff, and to keep public APIs stable unless the refactor requires a change. The code migrations use case says to work in milestones, run lint, type-check and focused tests after each one, and keep rollback options visible until the transition is complete.
- Codex worktrees and AGENTS.md. Codex worktrees let several independent chats run in the same project, so one milestone can run while you review the last. AGENTS.md carries the test and lint commands; Codex reads up to 32 KiB of it by default.
Read together, the advice is a template in disguise: say what must not change, pin it with tests, move in small steps that each end green, and hand back evidence. What the vendors cannot supply is the part only your team knows: why this debt matters now, which interfaces other teams depend on, and how to undo the change if it goes wrong in production.
The seven-field refactor ticket for AI coding agents
Copy this into your tech-debt work item. Each field closes a gap an agent would otherwise fill with a guess. Most refactor tickets fit in 150 to 250 words.
- 1. Why now. One or two sentences on the cost of the debt today: "Every change to invoices takes two days because pricing, tax and PDF rendering share one 1,400-line file. Three of the last five billing bugs started there." This tells a person whether to fund the work, and tells the agent what the new shape is for.
- 2. Behaviour contract. What must stay exactly the same: outputs, error messages, log lines other systems parse, performance limits, database writes. Write it as a list. "Invoice totals, PDF output and the invoices API responses are identical before and after." Agents treat this as the definition of success, so a missing contract makes them invent a looser one.
- 3. Safety net. The tests that pin the current behaviour, and what to add before any code moves. If coverage is thin, the first milestone is characterization tests: tests that record what the code does today, right or wrong, so any change shows up as a failure. For output-heavy code, a golden-file comparison is often the cheapest net: run 50 real inputs before and after and diff the results.
- 4. Scope and frozen interfaces. The files and modules in scope, and what the agent must not touch: the public API, the database schema, shared components other teams import, feature flags. This is the field that stops a refactor of one service from becoming a rewrite of three.
- 5. Milestones. The order of work, in steps small enough to review in ten minutes each, every one ending with the suite green and a commit. For example: add characterization tests; extract tax; extract PDF rendering; delete the old paths. If the agent's plan has one giant step, send it back.
- 6. Rollback. How to undo it if something goes wrong after release: revert the merge request, keep the old path behind a flag for one release, or run old and new side by side and compare. A refactor without a rollback plan is a bet.
- 7. Done means. The evidence a reviewer needs to merge: the same tests passing before and after, the new characterization tests added, the golden-file diff empty, frozen interfaces untouched, line count or complexity down, and one paragraph on anything the agent found but did not change. That last part is where the next tech-debt ticket comes from.
Add one line at the end: stop conditions. If the agent finds a real bug while refactoring, it should note it and keep the bug, not fix it in the same change. A refactor that also fixes bugs changes behaviour on purpose, and the reviewer can no longer tell the intended changes from the accidents. File the bug with our bug report template instead. Put this rule in CLAUDE.md for Claude Code or AGENTS.md for Codex; our CLAUDE.md vs AGENTS.md guide explains which file each rule belongs in.
Where a refactor's context lives in 2026, and what it costs
The template is the easy part. In most teams, the seven fields of one refactor sit in six subscriptions, and the agent has to visit each one:
| Tool and plan | Seat / month | AI layer and limits | Refactor context usually kept there |
|---|---|---|---|
| Jira Standard | $9.70 | Rovo, 25 credits per user per month on Standard (70 Premium, 150 Enterprise), $0.01 per extra credit from 3 Dec 2026 | The tech-debt ticket, often one line |
| Confluence Standard | $7.15 | Same pooled Rovo credits | Architecture decision records |
| Notion Plus | $12.00 | Custom Agents on credits, Business and Enterprise only | Migration notes and the plan |
| Figma Professional, Full seat | $20.00 | 3,000 AI credits per Full seat per month, MCP calls capped per day | Screens that must look the same |
| Miro Starter | $10.00 | Create with AI on Miro credits | The module and dependency map |
| Canva Business | $25.00 | Canva AI usage per member | The changelog or announcement graphic |
| Six-tool total | $83.85 | Up to six meters, six MCP servers | One refactor in six places |
| Sydla | $19.00 | None: your own Claude Code or Codex plan pays for the model | Ticket, frozen states, run and evidence on one work item |
Refactors also burn more agent time than features of the same size, because the agent has to read much more code than it changes. Every extra hop to fetch context adds to that. The comparison overview covers each tool, and the pricing section lists the source for every price.
Pay down tech debt without a second AI bill
Write the refactor ticket once, freeze the screens that must not change, and let your own coding agent read it all through one connection, for $19 per month instead of $83.85. That is $64.85 saved per user, every month, with no AI credits to ration while the agent reads a large codebase.
From ticket to merged refactor: work item, UX Studio, agent, review
Here is how the seven fields travel through Sydla on one work item, with the coding agent you already pay for.
- Ticket on the work item (fields 1 to 6). The engineer who owns the debt fills in the template on a tech-debt work item in Sydla. An agent can draft the scope from the code, propose milestones and estimate the cost of the run. A person approves the ticket before anything runs, because deciding that debt is worth paying now is a product decision. Our sprint planning guide covers how to fit refactors next to feature work.
- Frozen states in UX Studio. If the refactor touches anything a user sees, link the approved UX Studio screens in every state the code renders: empty, loading, error, done. These are the before pictures. After each milestone the agent can compare against them instead of a canvas that someone may be editing. Our design-to-code handoff guide explains why states beat screenshots.
- Run in Sydla Desktop with your own agent. Sydla Desktop launches the Claude Code or Codex CLI on your machine, signed in with your own Anthropic or OpenAI account, in your local checkout. Through one Sydla MCP server the agent reads the ticket and the frozen states. It starts in plan mode, writes the characterization tests, confirms they pass on the old code, then works one milestone at a time in its own worktree, committing each time the suite is green. There are no Sydla AI credits and no token markup. The Desktop guide walks through the first run.
- Review against field 7. Each milestone writes its evidence back to the work item: tests before and after, the golden-file diff, the list of frozen files untouched, the run cost and the merge request. The reviewer checks one small milestone at a time with the four-pass review checklist instead of one 2,000-line diff.
If the agent finds that the refactor needs a behaviour change, such as an error message that was wrong all along, the run stops and the question goes back to the person who owns the work item. Agents propose. People decide.
A filled-in example: splitting the invoices service
Here is the template applied to a typical tech-debt ticket, at the length we recommend:
- Why now: invoices.ts is 1,400 lines and mixes pricing, tax and PDF rendering. Changes there take about two days, and three of the last five billing bugs started in it.
- Behaviour contract: invoice totals to the cent, PDF bytes for the same input, invoices API responses and error codes, and the "invoice.created" log line finance parses all stay identical.
- Safety net: existing unit tests cover pricing only. Milestone 1 adds characterization tests for tax, plus a golden-file run of the last 50 production invoices from the anonymized seed, compared byte for byte.
- Scope and frozen interfaces: in scope, the invoices folder. Frozen: the public invoices API, the invoices table, and the shared money helper imported by the payments team.
- Milestones: 1, characterization tests and golden files. 2, extract tax into its own module. 3, extract PDF rendering. 4, move pricing. 5, delete the old paths. Suite green and a commit after each.
- Rollback: ship behind the new-invoices flag for one release, comparing old and new totals in the background; revert the merge request if any total differs.
- Done means: all old tests and new characterization tests pass, the golden-file diff is empty, frozen files untouched, invoices.ts gone and no new module above 400 lines, plus a note on anything odd the agent saw but did not change.
That is about 230 words. The agent knows what success looks like, the reviewer gets five ten-minute reviews instead of one afternoon, and finance never notices anything happened, which is the point. Compare it with "Clean up the invoices service", which is what the backlog said for a year.
Common refactoring mistakes with AI coding agents
These show up in almost every team's first month of agent refactors:
- Refactoring without a net. If the current behaviour is not pinned by tests, "the tests pass" proves very little. Make characterization tests the first milestone whenever coverage is thin.
- One giant diff. A single 2,000-line merge request cannot be reviewed honestly. Ask for milestones that each end green and each fit a ten-minute review, as both Anthropic and OpenAI recommend.
- Fixing bugs along the way. The agent finds a real bug and fixes it in the refactor. Now the behaviour changed on purpose and the reviewer cannot tell it from an accident. Note it, keep it, file it separately.
- Changing tests to make them pass. If an existing test fails after a refactor, the refactor is wrong, not the test. Put "do not edit existing tests" in the ticket, and check the diff for it.
- Measuring nothing afterwards. If "why now" said changes take two days, check in a month. Our retrospectives guide shows how to use run data to see whether the debt paydown paid off, and our cost per ticket guide shows what each milestone cost.
Frequently asked questions
Can AI coding agents refactor code safely?
Yes, if the behaviour is pinned first. Give the agent a behaviour contract that lists what must not change, tests that check it, and small milestones that each end with the suite green and a commit. Claude Code's docs recommend refactoring in small, testable increments, and OpenAI's Codex guidance says to run the smallest useful check after each pass and keep public APIs stable.
What should a refactoring ticket for an AI agent include?
Seven fields: why the debt matters now, a behaviour contract of what must stay identical, the safety net of tests to rely on or add first, scope and frozen interfaces the agent must not touch, milestones that each end green, a rollback plan, and a definition of done such as same tests passing, an empty golden-file diff and less code. Add a stop condition: bugs found during the refactor are noted, not fixed.
Should I write tests before asking Claude Code or Codex to refactor?
Yes. If coverage is thin, make characterization tests the first milestone: tests that record what the code does today, right or wrong. Have the agent run them on the old code to confirm they pass, then keep them green through every later step. For code that produces files or reports, compare real outputs before and after.
How do I review a large refactor written by an AI agent?
Do not review it as one diff. Ask for milestones, each one a small merge request with evidence: tests before and after, the output comparison, and proof that frozen files were not touched. Review each milestone in about ten minutes, and reject any change that edits existing tests or changes behaviour that the ticket froze.
How much does Sydla cost compared with tracking tech debt across Jira, Confluence, Notion, Figma, Miro and Canva?
Sydla costs $19 per user per month. One paid seat each of Jira Standard, Confluence Standard, Notion Plus, Figma Professional Full, Miro Starter and Canva Business costs $83.85 per user per month, so the saving is $64.85 per user per month. You bring your own Claude Code or Codex account, so your Anthropic or OpenAI plan pays for the model with no markup.





























