Skip to content

Start from an existing codebase

Build a first SpecsGraph model of software that already runs: plan the first proposals, bring in existing specs and ADRs, and review what agents infer.

Most teams adopt SpecsGraph for a system that is already in production. The quickest route is to let an agent read the code and propose the model in small pieces, while people check each piece against what the system should do. This page assumes you have followed the Quickstart up to step 8, skipping step 6: a workspace, a project connected to your repository, a Read and write token and a connected agent.

When to start from code

  • The system runs in production, and its code and tests are the most accurate description you have.
  • What the team knows is spread across code, tests, decision records and wiki pages.
  • You would rather review a draft than write the first version by hand.

If you are designing something new, sketch the contexts by hand instead, as in step 6 of the Quickstart.

Plan the first pass

Build the model from the outside in, one kind of node at a time. Each step is one or more small proposals. Let each step publish before the next one builds on it, so later proposals link to contexts and terms that are already part of the spec.

  1. Contexts and relationships. One structure proposal with propose_structure_change: each context with its key, purpose and subdomain type, and the relationships between them. Get this one right first, because every requirement ID starts with a context key. See Bounded contexts and subdomains.
  2. Glossary terms. propose_term, one context per proposal, starting with the words the code already uses for its main concepts.
  3. Actors. No tool adds actors, so ask the agent to list the people and external systems it finds, and add them in the web app. See Actors.
  4. Requirements. propose_requirement, one context or service per proposal, with scenarios drawn from the tests that already exist.
  5. Decisions. record_decision for the design decisions you have already written down.

Track coverage with a workstream

A first model takes several proposals, so give it a workstream, for example WS-1 "Initial model", with one task per context. An Editor creates the workstream; the agent adds tasks and moves them with update_task as it works. The workstream then shows which contexts are modeled and which are still to do.

Bring in what you already have

  • Architecture decision records. The agent drafts each one as a decision with record_decision. SpecsGraph numbers decisions itself, so keep the old number in the text, for example "Formerly ADR-012", and old links stay traceable.
  • Gherkin feature files. Each feature becomes a requirement with a SpecsGraph ID, and its scenarios carry over. Keep the old files until the new requirement files are published, then run your BDD tool against those instead; see Run scenarios with a BDD tool.
  • Wiki pages and Markdown specs. Paste the text into the prompt, or point the agent at the files in the repository. Ask it to propose terms first and requirements after.

Review a model inferred from code

A model drawn from code describes what the system does today, bugs included. Review it with that in mind:

  • Ask for sources. Have the agent name the files and tests behind each requirement, in its summary or in reply to your threads.
  • Ask it to mark guesses. Anything it inferred rather than read deserves a closer look.
  • Do not approve a rule nobody can confirm. Leave a thread, or ask the agent to take it out of the proposal until someone can.
  • Catch bugs written up as rules. If the code does the wrong thing, write the requirement as it should be and add a task for the fix.

The first publish

The pull request for the first approved proposal adds the specsgraph/ folder to your repository, with README.md, graph.json and a folder per context. Expect it to be larger than later ones. Set up a code owners file for the spec folder before it opens, and consider the CI checks in Spec files in your repository.

Prompts to start with

ContextsText
Use the specsgraph MCP server. Read this repository and propose the
bounded contexts you find, each with a key, a one-line purpose and a
subdomain type, plus the relationships between them, as one structure
proposal. For each context, tell me which folders you based it on.
Do not propose requirements yet.
Glossary termsText
Read the Orders context in specsgraph and the code under src/orders.
Propose glossary terms for the main concepts the code names, with a
one-sentence definition each. List any concept the code names in two
different ways, and suggest which word to keep.
RequirementsText
Propose requirements for the Checkout service in Orders, one rule per
requirement, with scenarios based on the existing tests in tests/checkout.
In your summary, name the test file behind each scenario and mark
anything you inferred rather than read.

Next steps