Skip to content

Working well with agents

Habits that make coding agents useful with SpecsGraph: read the graph before writing code, keep proposals small, reuse glossary terms and cite requirement IDs.

Point the agent at SpecsGraph before it writes code

An agent that reads the spec first writes code that matches it. Put that instruction in the file your agents read at the start of every session, so nobody has to repeat it in prompts. Many clients read AGENTS.md at the repository root. Claude Code reads CLAUDE.md, which can import the same file with a line containing @AGENTS.md.

AGENTS.mdMarkdown
## Specs live in SpecsGraph

This repository's requirements, glossary and design decisions are in SpecsGraph,
available through the `specsgraph` MCP server. Treat active requirements
as the source of truth for behavior.

Before you change behavior:
1. Read the affected context with get_context and the requirements you touch.
2. Check the glossary with list_glossary_terms and use those words in code.
3. Look for a recorded decision with list_decisions before reversing an earlier choice.

When behavior changes:
- Propose the spec change in SpecsGraph as one small proposal per change.
- Cite requirement IDs (for example ORD-12) in commit messages and PR descriptions.
- Do not treat an open proposal as final. People review and approve it.

Keep proposals small and focused

Reviewers approve a proposal as a whole, so its size decides how carefully it gets read. Aim for one proposal per behavior change.

  • Group what belongs together. ORD-12, ORD-13 and BIL-04 arrive in one proposal in Northwind Commerce because they describe one decision: reserve stock before taking payment.
  • Split what does not. Renaming a context or reclassifying a subdomain is a structure change. Keep it in its own proposal instead of mixing it with new requirements.
  • Tie it to the work. Name the task in the prompt, for example "Specify the email sent when a reservation lapses" in WS-3, so the agent moves it with update_task. Then link the proposal to that task in the web app, so reviewers see why it exists.
  • Say what is out of scope. A prompt that ends with "do not change anything outside Orders" keeps the diff where you expect it.

Reuse glossary terms

Agents pick words freely unless told otherwise. In Northwind Commerce the glossary defines Reservation, so a proposal that talks about a "hold" or a "lock" should use Reservation instead. Ask the agent to call list_glossary_terms for the context it is working in before it drafts anything.

When a concept is new, the agent should propose the term with propose_term rather than invent a synonym inside a requirement. Reviewers then agree on the word once, and every later proposal reuses it. Domain glossary covers how terms are defined and linked.

Cite requirement IDs in commits and pull requests

Requirement IDs connect code history to the spec. When a commit message or a pull request names the requirement it implements, a reader can go from a line of code to the scenario it satisfies, and from a requirement to the code that changed for it.

Commit messageText
Reserve stock for each line item when checkout starts

Creates one reservation per line item and rejects checkout when any
item is out of stock.

Refs: ORD-12, BIL-04
Spec-Proposal: spec/checkout-reserve

Refs: is a team convention, not something SpecsGraph requires; Spec-Proposal: matches the trailer SpecsGraph writes on its own spec commits, described in Branches and pull requests. Pick a format and put it in AGENTS.md. Test names that include the ID, such as ord_12_reserves_every_line_item, make the link visible in test output too.

Review agent proposals like code

An agent's proposal deserves the same attention as an agent's pull request. Before you approve, check:

  • Placement. Each requirement sits in the context that owns the behavior.
  • Scenarios. Given, When, Then steps are specific enough to test, and the failure paths are covered, not only the happy path.
  • Vocabulary. Terms match the glossary, and any new term arrives as its own glossary change.
  • Scope. Nothing outside the change the proposal claims to make.
  • Reasoning. A non-obvious choice has a draft decision attached, so the next reader knows why.

When something is off, leave a comment on the node instead of fixing it yourself. The agent can read the thread, revise and reply, and the conversation stays in the history. Proposals and reviews describes the review flow.

Example prompts

SituationPrompt
Starting a task"Read the Orders context and ORD-12 in SpecsGraph, then outline how you would implement it. Do not write code yet."
Behavior changed during coding"The idle timeout is now configurable. Propose the matching change to ORD-13 in SpecsGraph, with a scenario for the configured value."
New concept"We now split shipments. Propose a glossary term for Partial shipment in Fulfilment before drafting any requirements that use it."
Addressing review"Read the threads on spec/checkout-reserve, fix what the reviewers asked for and reply to each thread with what you changed."
Checking for drift"Compare the checkout code with the active requirements in Orders and list any behavior the spec does not describe."

Next steps