Skip to content

Scenarios

Change an Existing Codebase

Use this route when the code works but its decisions were never written down. No documentation pass comes first: bmad-build reads the repository on every run and follows what it finds. Start small, and add planning only when the work calls for it.

The example is the room booker, two years old. Its author has left, and nobody remembers how a booking ends when nobody shows up. Next up is the check-in feature.

Change an Existing Codebase, step by step Give agents a project context, learn the code if nobody knows it, make a small change with bmad-build first, then take the route the larger change needs. ANY TIME bmad-project-context rules agents must follow CLARIFY · optional Learn the code if nobody knows it BUILD bmad-build a small change first NEXT The next route for a larger change

  1. Give agents a project context (recommended): a short, verified block in AGENTS.md on how to run the tests, where things live, and what not to change. It adopts an AGENTS.md or CLAUDE.md you already maintain. See Start in an Existing Codebase.

    /bmad-project-context
  2. Learn the part you will change, if nobody knows it. bmad-walkthrough takes you through the code at your pace.

    /bmad-walkthrough src/bookings/expiry.ts

    bmad-deep-recon writes a cited account of how the code works and why, with no recommendation; deciding what to change stays with you, Sofia, and the build. Ask it factual questions, and when it shows its plan of questions, add your own in the same chat.

    /bmad-deep-recon before we add check-in, how do bookings end today, and what depends on that?
    Where does the booking expiry timer run today, and what depends on it?

    Hand the account to Sofia when she writes the initiative so the tickets cite it; a build with no ticket finds it among the planning documents.

  3. Make a small change first, one session’s worth, to see how the build handles this code. Pinning today’s behavior with a test is a good first change before a feature changes it.

    /bmad-build add a test that pins how a booking ends today when nobody shows up
  4. Take the route the next change needs. Check-in is more than one session, so it goes to Build from a Conversation or Plan a Feature as a Team. One session’s worth goes to Make a Small Change.

A project-context block in AGENTS.md that every later session reads, a cited account of how the code you are about to change works, and one small change built the way this codebase works.

bmad-build reads the repository first, notes what to reuse and what must not change, and matches the code it finds. To break a pattern on purpose, say so in the request and write why in the ticket, so later sessions follow the new rule. Start in an Existing Codebase explains why.

When Sofia slices work on existing code, she reads the code to see where deployment splits. Where it contradicts a requirement, she adds a Source conflict: line and offers the correction.

To follow this route step by step on a working app, see Walk Through an Existing Codebase. New to BMad? Start with Install BMad.