Agent instructions
Connecting an agent gives it Workstate's tools. Instructions tell it when to use them: search before it acts, cite what it found, check the ledger before it decides, and record the outcome when it finishes. Without them, an agent may use the tools only when you ask it to.
Where to paste them
| Client | Where the instructions go |
|---|---|
| Claude Code | CLAUDE.md in the project's root folder, or ~/.claude/CLAUDE.md for all your projects |
| Cursor | AGENTS.md in the project's root folder, or a rule in .cursor/rules with alwaysApply: true |
| Codex | AGENTS.md at the root of the repository, or ~/.codex/AGENTS.md for all your projects |
| Other clients and your own agent | The system prompt, or the client's setting for custom instructions |
A project file is shared through version control, so everyone on the project gets the same behaviour.
The instructions
Copy this block as it is, then adapt it as described below.
md
# Workstate: shared memory and decision record
Workstate holds what this team knows (code, documents, tickets and files) and the
ledger: an append-only record of what the team decided, what went wrong, and what was
tried. You reach it through two MCP servers: `rag-corpus` for search and `rag-ledger`
for the ledger. People and other agents use the same record, so check it before you
act, and add to it when you finish.
## Search before you act
- Before you explore code, answer a question about how something works, or change
something you have not seen, call `search_corpus` with a plain-language description
of what you need. Search first. Open files, or run exact-match searches, afterwards
to confirm the details.
- Narrow a search when you know where to look: `corpus` ("code", "wiki" or "ledger"),
`repo` (one name or a list), `language`, or `path_prefix`.
- A result is a passage, not the whole file. When you have the file, read the lines
around the passage before you rely on it.
- If a search finds nothing relevant, say so rather than guess. The content may not be
indexed yet, or may be in a namespace you cannot reach.
- After pushing changes that should be searchable at once, call `reindex_corpus`,
then wait a few minutes before searching again.
## Cite what you use
- Cite each result you rely on as `repo/rel_path:start_line-end_line`,
for example `payments-api/src/retry.ts:40-72`.
- Cite ledger topics by their id, for example `payments-0012`.
## Check the ledger before you decide or re-investigate
- Before a non-obvious decision, and before you investigate a bug or an incident, call
`ledger_search` to find earlier decisions, incidents, and approaches that were tried
and rejected. Filter by `type` (decision, incident, defect or investigation) or by
`status` when it helps.
- Read a relevant topic in full with `ledger_get`. Follow its current state, not an
older entry in its history.
- If a topic records that an approach was rejected or superseded, do not repeat that
approach without saying why.
## Record what you decide and find
When you make a real decision, find the root cause of a bug, handle an incident, or
finish an investigation whose finding is worth keeping, record it before you finish:
- Call `ledger_create` once for each distinct decision or finding. Give it a `type`
(decision, incident, defect or investigation), a one-line `title`, a `summary` that
frames the question as it stood, an `initial_state` that says briefly where it
stands now, and `repo`: the project it belongs to, such as the repository's name.
- Prefer several small topics to one broad one. "Use Postgres for the job queue" and
"Retry failed jobs with exponential backoff" are two topics, not one.
- Use `ledger_append` only to move the same topic on: a status change, a correction,
or the outcome. Use `set_state` for the new current state and `set_status` for the
new status, such as accepted or resolved.
- History is append-only. Never rewrite what a topic said. When a new decision
replaces an old one, create the new topic, then call `ledger_append` on it with
`supersedes` set to the old topic's id. That links the two and marks the old one
superseded.
- Keep the current state short: where things stand, not a growing report.
- Record what a future teammate or agent would regret not knowing. Do not record trivia.
- Tell the person the id of every topic you create.
## If the tools are missing
If the Workstate tools are not available, say so and carry on without them. Never
claim that you searched or recorded something when you could not.Adapt it to your team
Add what the generic text cannot know, below the block:
- Your projects. List the repositories and sources that matter, and what each holds, so the agent can narrow its searches with
repo. - Project names for the ledger. Say which
reponame to file topics under, for example one per repository, or one per team. A topic's id starts with this name, such aspayments-0012. - Your namespaces. If you connected more than one namespace, say which servers cover which. See the example below.
- Your conventions. For example, which decisions need a person's approval before the agent sets them to accepted.
Illustrative
The namespace names and ids here are examples.
md
## Workstate namespaces
- `rag-corpus` and `rag-ledger` cover the Engineering namespace: our code, the
engineering wiki and the platform tickets.
- `rag-corpus-ws-9f8e7d6c5b4a43210fedcba987654321` and
`rag-ledger-ws-9f8e7d6c5b4a43210fedcba987654321` cover the Client A namespace.
Use them only for Client A work, and never copy Client A content into the
Engineering ledger.For Claude Code
In Claude Code, each tool's full name includes its server's name, such as mcp__rag-corpus__search_corpus and mcp__rag-ledger__ledger_create. By default, Claude Code loads MCP tools on demand, through tool search, and naming the tools in full helps it find them. This is also why the server names in the configuration must match the ones in your instructions. See Server names. You can add a line such as this to the block:
md
In Claude Code, the Workstate tools are `mcp__rag-corpus__search_corpus`,
`mcp__rag-corpus__reindex_corpus` and `mcp__rag-ledger__ledger_*`. If they are not
loaded yet, load them by these full names, including `ledger_create` and
`ledger_append` before you finish a task.Check it works
Give the agent a task that touches something your sources cover, without mentioning Workstate. A well-instructed agent calls search_corpus or ledger_search before it answers, cites what it found, and records a topic when it makes a decision. Open Ledger in the console to see what it recorded.