Skip to Content

How should I split internal refactors into milestones for a Python backend?

In Tares, you split an internal refactor into milestones that each end on acceptance checks, so the crew’s assumptions are confirmed before the next milestone. Put the safety net first, then the behavior you must keep, then the merge. The spec session writes the milestones and their checks into the plan.

How it works

A milestone in the software factory for Claude Code is a stretch of tickets with acceptance checks. When you run tares factory spec in your repo, Claude Code asks you questions and a second model challenges the plan. The result goes into Tares as a spec, a plan, an AGENTS.md for the project and the milestones, each with its checks. You find them in the Tickets fold on the project page.

The milestone boundary is also where decisions get settled:

  • While the crew builds, it meets things the plan did not cover. It picks a sensible answer, writes it down as an assumption and carries on.
  • At the end of each milestone, the orchestrator brings you its assumptions in one question. You keep them or not.
  • Your answer is stored in the Decisions fold in your own words, up to 4,000 characters. To make an answer stand from now on, say so, for this project or for every project.

The A project, end to end page follows a real project with three milestones, and the same shape suits an internal refactor:

  • M1, tests and CI on the branch. The safety net comes first: tests for the logic you are about to touch and a CI check on every pull request.
  • M2, behavior stays as it was. The example milestone was named “payout history stays as it was”. Its check is that past results do not change.
  • M3, merged and live. The pull request is documented, merged into main and running in production.

For a Python backend, write each check against your own test suite and CI, so that the milestone is done when a person can confirm it. A check such as “existing behavior is unchanged” is easier to confirm than “the code is cleaner”.

Inside a milestone, tickets run one at a time. Each ticket gets a branch, a pull request and a reviewer verdict, and the builder merges once the verdict passes and CI is green. A blocked ticket names the tickets it waits for. The plan can also grow in place. In the example, the reviewer found smaller issues outside its ticket, and the orchestrator added a ticket for them inside M2, before the integration tests.

Set it up

  1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed.
  2. Install the CLI, start Tares locally, and in a second terminal start the MCP endpoint every crew session shares. On Tares Cloud you run tares login instead and there is no MCP endpoint to start.
  3. Give Tares access to GitHub, in Settings > GitHub for a local Tares or Connect GitHub on Tares Cloud.
  4. Bring up the crew, then plan the refactor from your repo.
gh auth login
uv tool install tares     # or: brew install glassflow/tap/tares
tares up
tares mcp --transport streamable-http
tares factory crew up
tares factory spec "what you want to build"
  1. Replace the quoted text with your refactor goal and answer Claude Code’s questions. Say how you want the refactor cut: tests first, then the behavior that must not change, then merge and deploy.
  2. Read the milestones and their acceptance checks before you hand the project to the crew. Reword any check you could not confirm yourself. Then say yes to hand the project over. The orchestrator picks it up and starts a builder for the first milestone.
  3. Watch the Crew page in the console at http://127.0.0.1:8787/crew. Answer the questions that appear at the top, and use the end of each milestone to confirm or reject the assumptions. For the full walkthrough, see Get started.

What you get

  • A check at every boundary. Each milestone ends on acceptance checks you can confirm, so you know where the work stands before the next stretch begins.
  • Assumptions in one place. The choices the crew made on its own come to you together at the end of the milestone, with the tickets they touch and the builder that made them. In the example project, these included a config file name that did not load on the repo’s Node version and a decision to leave existing production data alone.
  • A record of the build. The project page keeps the spec, the plan, the tickets with their pull requests and review rounds, your decisions and the assumptions.
  • A visible progress bar. The project page shows four steps, Spec, Build, Review and Done, with one progress segment per ticket.
  • A clean finish. After the last milestone, the orchestrator asks whether the project is finished. Your answer is recorded and the project moves to the finished list. When no project is left, tares factory crew down stops every station.

When something else fits

  • If the change is one small edit with no behavior to protect, a single ticket may be enough, and a milestone plan adds little.
  • If you want to steer a build step by step, talk to the orchestrator in its session. It answers the builders and brings you what needs you.

Still stuck? Get help

Last updated on