Skip to content

Working well with agents

Habits that make coding agents useful with SpecsGraph: read the spec before writing code, keep proposals small, reuse glossary terms and cite display 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. Codex and Cursor read AGENTS.md at the repository root. Claude Code reads CLAUDE.md, which can import the same file with a line containing @AGENTS.md. The web app's Connect an agent panel shows this block too.

AGENTS.mdMarkdown
## Specs live in SpecsGraph

This repository's spec (bounded contexts, aggregates, use cases, features, glossary terms) is in
SpecsGraph, available through the `specsgraph` MCP server. Main is the spec that shipped; a workstream
(WS-3) holds the spec in flight until one of its tasks publishes.

Before you change behaviour, read first:
1. `project_list` to find the project, then `spec_get` for the documents you touch (selector `kind/Name`):
   `scope: workstream:WS-n` while the spec is in flight in that workstream, `scope: main` for what shipped.
2. `workstream_list` and `workstream_listChanges` to see what a workstream already changes.
3. `task_list` and `thread_list` for the task and the review threads (open questions) you are working on.

When behaviour changes:
- Stage the spec change with `spec_apply` into the workstream. It lands in a proposal that a person
  reviews: accepted into the workstream; Main after a task publishes. In a project with Agent autonomy on, it is
  written to the workstream directly, and you may accept, route and submit tasks as Ready yourself.
- One small proposal per change. Do not treat an open proposal as final; read the workstream, not Main,
  for what was accepted.
- People publish a task; publishing moves it on and the landing marks it done.
- Cite display ids such as WS-3 and T-4 (or the task's tracker key, such as KAN-43) in commit
  messages and pull request descriptions.

When you implement agreed work (work items):
1. `work_item_next` for the ready items you may take, then `work_item_claim` the one you start.
2. `spec_get` at the item's `read.scope` for exactly what was agreed, then implement it.
3. Open a pull request whose title names the item, such as T-12.1, and link it with `work_item_update` (`codeRef`).
4. Send `work_item_update` with `heartbeat` within 2 hours while you work, or your claim lapses; `release` it if you stop.
- Stuck on the spec? Ask with `thread_ask` on the item (`item`, `blocking: true`). The merge, not you, marks the item done.

The SpecsGraph skills package these habits as Agent Skills. Install them, and keep AGENTS.md for what is specific to your repository.

Keep proposals small and focused

Reviewers accept a proposal revision by revision, so a proposal's size decides how carefully it gets read. Aim for one proposal per behaviour change.

  • Group what belongs together. The Reserve stock use case, its scenario on the Checkout feature and the Reservation term arrive in one spec_apply call because they describe one decision: reserve stock before taking payment. spec_apply keeps their dependsOn order.
  • Split what does not. Renaming a bounded context or moving an aggregate is a structure change. Keep it in its own proposal instead of mixing it with new use cases.
  • Tie it to the work. Name the task in the prompt, for example "T-4 in WS-3" (or its tracker key, KAN-43), so the agent reads that workstream and stages into a plan for that task. Reviewers then see why the proposal exists.
  • Say what is out of scope. A prompt that ends with "do not change anything outside Ordering" keeps the diff where you expect it.
  • Reuse the open proposal. A second spec_apply on the same workstream adds to the open proposal, and supersedes the agent's earlier revision of the same document, until the proposal completes.

Reuse glossary terms

Agents pick words freely unless told otherwise. If the glossary defines Reservation, a document that talks about a "hold" or a "lock" should use Reservation instead. Ask the agent to list the terms of the bounded context it is working in (artefact_list with kind=term, or spec_get with a term/ selector) before it drafts anything.

When a concept is new, the agent should stage the term as its own document rather than invent a synonym inside a use case. Reviewers then agree on the word once, and every later proposal reuses it.

Cite display ids in commits and pull requests

Display ids connect code history to the spec. When a commit message or a pull request names the workstream and task it implements, a reader can go from a line of code to the scenario it satisfies, and from a task 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: WS-3, T-4
Spec: use-case/Reserve stock

Refs: is a team convention, not something SpecsGraph requires. Pick a format and put it in AGENTS.md. Test names that include the id, such as t4_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 accept a revision, check:

  • Placement. Each document sits in the bounded context that owns the behaviour.
  • 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 document.
  • Scope. Nothing outside the change the proposal claims to make.
  • Attribution. The Agent badge names the client (hover it); a revision staged by an unfamiliar client is access to review in Settings, then Access tokens.

When something is off, open a thread on the artefact instead of fixing it yourself. The agent can read the thread with thread_list, revise with spec_apply and reply with thread_reply, and the conversation stays in the history. Proposals, plans and review describes the review flow.

Questions instead of guesses

When the agent cannot infer an answer, have it ask with thread_ask on the artefact, with options when the choices are known. Set blocking when the revisions the agent staged on that artefact must not be accepted before the answer: an agent's blocking question holds only the accept of those revisions, not Ready or Publish of work already in a task.

Have the agent pass askTeam so a team is notified and the question appears in its members' Waiting on me list; without it, nobody is notified until the question escalates to the Editors after a day. The answer becomes a decision in the pull request of the task. Threads and questions and Decisions have the details.

Implementing agreed work

Once a task is Ready, its work items say what to build. Let the agent follow the same loop every time:

  1. work_item_next lists the items it may take; work_item_claim takes one.
  2. spec_get at the item's read.scope gives exactly what was agreed. Code against that, not against Main or memory.
  3. Name the item in the pull request title or branch, such as T-12.1 Reserve stock, and record the pull request with work_item_update (codeRef).
  4. Heartbeat with work_item_update within 2 hours while it works, or release the item when it stops.
  5. When the spec is unclear, ask on the item with thread_ask (item, blocking: true) instead of guessing.

The merge completes the item; the agent never marks it done. Deploy, verify and uat stay with CI and people.

Example prompts

SituationPrompt
Starting a task"Read the Ordering bounded context and the Reserve stock use case in SpecsGraph, then outline how you would implement it. Do not write code yet."
Behaviour changed during coding"The idle timeout is now configurable. Stage the matching change to the Reserve stock use case in WS-3, with a scenario for the configured value."
New concept"We now split shipments. Stage a glossary term for Partial shipment in Fulfilment before drafting any use case that uses it."
Addressing review"Read the threads in WS-3, fix what the reviewers asked for and reply to each thread with what you changed."
Checking for drift"Compare the checkout code with the use cases of Ordering on Main and list any behaviour the spec does not describe."
Picking up work"Take the next ready work item in SpecsGraph, implement it against the agreed spec and open a pull request named after it."

Next steps