How should I split bug fixes into milestones for a Python backend?
Tares plans bug fixes as milestones, each with acceptance checks, so you split the work where a milestone can end with something you can confirm. A pattern that worked in a real project is tests and CI first, then one milestone per behavior you fix, then a final milestone for merged and live. At the end of each milestone the orchestrator brings you the assumptions the crew made, in one question.
How it works
The software factory for Claude Code turns a spec into milestones, and each milestone carries acceptance checks. The builder works through the tickets of a milestone one at a time. For each ticket it makes a branch, does the work and opens a pull request. The reviewer reviews every pull request, and once the verdict passes and CI is green, the builder merges.
The a project end to end walkthrough shows the split on a project that started with a pull request with no tests and a few bugs. The spec session produced three milestones:
- M1, tests and CI on the branch: a test setup, unit tests for the logic that had the bugs, and a CI check on every pull request.
- M2, payout history stays as it was: one group of related bugs, written as an observable outcome. Past weeks stay as they were when a sitter is deactivated or a rate changes.
- M3, merged and live: the pull request documented, merged into main and running in production.
For your Python backend, the same shape gives you a test and CI milestone first, so every later fix is checked by a pull request check. Then you add one milestone per group of related bugs, each named for the outcome it protects. The last milestone is merged and live.
The end of a milestone is where assumptions get confirmed. When the crew meets something the plan does not cover, it picks the 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. In the example project, one assumption was a different config file name because the one in the working doc failed to load. Another was leaving existing production data alone, flagging it in the pull request and leaving any production fix to the person.
The plan can also grow inside a milestone. In the example, the reviewer found smaller issues outside the ticket it was reviewing. The orchestrator turned them into a new ticket and placed it in M2 before the integration tests.
Set it up
- 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.
- Install the CLI.
- On a local Tares, start Tares. On Tares Cloud, run
tares logininstead and pick your workspace in the browser. - On a local Tares, in a second terminal, start the MCP endpoint every crew session shares. Tares Cloud has no MCP endpoint to start.
- Give Tares access to GitHub, in Settings > GitHub for a local Tares or Connect GitHub on Tares Cloud.
- Bring up the crew.
- Plan the project with a description of the bugs. Run it in the repo and answer Claude Code’s questions. The result is a spec, a plan, an AGENTS.md for the project and milestones with acceptance checks.
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"When the spec session ends, you say yes to handing the project to the crew. The orchestrator picks it up and starts a builder for the first milestone. If you are new to the factory, start with Get started.
Once the crew is running, open the Crew page at http://127.0.0.1:8787/crew on a local Tares. The Tickets fold of the project page lists the milestones with their acceptance checks. The Assumptions fold lists every choice the crew made on its own and whether you kept it.
What you get
- Milestones that each end at a point you can confirm, with acceptance checks you can read in the Tickets fold.
- A test and CI milestone up front, so later fixes are reviewed and merged with a CI check behind them.
- One question per milestone with the crew’s assumptions, so you keep or change them before the project moves on.
- A Decisions fold that holds every question the crew asked you and your answer in your own words.
- A progress bar on the project page with one segment per ticket, and a ticket state of to do, in progress, in review, merged or blocked. A blocked ticket names the tickets it waits for.
- A plan that can grow. Smaller issues the reviewer finds become a new ticket in the right milestone.
To make an answer stand from now on, say so, for this project or for every project.
When something else fits
- For a single small bug, a full milestone plan may be more than you need, and a plain Claude Code session in your repo can be enough.
- If you want to steer a ticket that is already in progress, talk to the orchestrator in its session instead of re-planning the milestones.