# Guide coding agents with repository files and guidance

At the end of this guide, every coding agent that works on your repository follows the same house rules, and the AI reviewer weighs pull requests against your team's standards. Rules that belong to the code live in files in the repository; rules that belong to a project or the whole workspace live in Volobox. Anyone who can push to the repository can change its files; project guidance needs a project **Admin**, and workspace guidance needs an administrator.

## Before you begin

- A repository linked to a Volobox project. See [From a task to a pull request](/docs/task-to-pull-request).
- Push access to the repository, for `AGENTS.md` and `REVIEW.md`.
- The project's **Admin** role, to edit agent guidance and approve learned notes.

## Where each rule goes

| Where | Who reads it | Use it for |
| --- | --- | --- |
| `AGENTS.md` in the repository (or `CLAUDE.md` when there is no `AGENTS.md`) | Every coding agent working in the repository, and the AI reviewer | How to build, test and change this code: commands, conventions, layout. |
| `REVIEW.md` in the repository | The AI reviewer | What a review should weigh and flag. |
| **Workspace guidance** | Every agent on every run, coding sessions and coding assignments included | Standing instructions for the whole organization. |
| Project **Agent guidance** | Agents working in the project: chat, coding sessions, coding assignments, workflow runs about the project | Instructions that hold for this project only. |
| Project **Learned notes** | Agents working in the project | Facts the team agreed are true ("We release on Thursdays"). |
| A team agent's **Coding instructions** | The coding agent in sessions that agent's work opened | How this particular agent wants work done, for example a frontend agent and a backend agent. |
| **Note for the agent** when you start work | That run's coding agent | Scope and approach for one task. |

Guidance wins over notes when they disagree. Workspace guidance is read first and project guidance narrows it.

## Write AGENTS.md for the repository

Coding agents in Volobox are told to follow the repository's agent instructions: `AGENTS.md`, or `CLAUDE.md` when the repository has no `AGENTS.md`.

1. Create `AGENTS.md` at the repository root.
2. Write the commands an agent must run, the conventions it must keep, and what it must not touch. Keep it short and specific; it is read on every task.
3. Commit it to the default branch.

```text title="AGENTS.md"
## Layout
- api/ is the ASP.NET Core API. web/ is the React front end (Vite, TypeScript).
- Database migrations live in api/Migrations. Never edit an existing migration; add a new one.

## Before you finish
- API: run `dotnet build` and `dotnet test` from api/.
- Web: run `npm run lint` and `npm test` from web/.
- Fix every failure you caused. Do not disable or skip a test to make it pass.

## Conventions
- API errors use the shared ProblemDetails format in api/Errors. Do not invent new error shapes.
- New UI text goes through the translation files in web/src/locales/en.json.
- Dates are stored in UTC and formatted only in the UI.

## Do not
- Commit secrets or .env files.
- Change the public API routes under api/Controllers/Public without saying so in the pull request.
- Add a new npm or NuGet dependency without explaining why in the pull request.
```

> **Tip:** Put the build and test commands in your preview manifest's `verify` steps too. `AGENTS.md` asks the agent to run them; `verify` makes Volobox run them before the pull request opens. See [Add verify steps](/docs/write-preview-manifest#add-verify-steps).

## Write REVIEW.md for the AI reviewer

Every AI review round reads the repository's `REVIEW.md`, then the repository's `AGENTS.md` (or `CLAUDE.md`). Both are taken from the branch the pull request targets, not from the pull request itself, so a pull request cannot rewrite the rules it is reviewed by. A change to `REVIEW.md` applies to reviews once it is merged.

1. Create `REVIEW.md` at the repository root.
2. Write what reviewers should treat as important, what is only polish, and what to leave alone.
3. Merge it into the branch pull requests target.

```text title="REVIEW.md"
## Treat as Important
- A database migration that drops or renames a column without a data migration.
- An endpoint under api/Controllers that skips the [Authorize] attribute.
- User input written to logs or HTML without encoding.
- A behavior change with no test that covers it.

## Treat as a nit
- Naming and formatting that the linter does not enforce.
- Missing comments on private methods.

## Leave alone
- Generated files under web/src/api/generated.
- Lockfiles, unless a dependency changed without a reason in the pull request.
```

The AI review is advice. It never approves, never requests changes, and never blocks a merge; the people on the pull request decide.

## Set workspace and project guidance

1. **Workspace guidance:** an administrator opens **Organization Settings** → **AI** → **Workspace guidance**, writes the instructions in markdown and selects **Save**. The next agent turn applies it.
2. **Project guidance:** a project **Admin** opens the project, selects the **Settings** tab → **Agent guidance**, writes the instructions and selects **Save**. It reaches coding assignments in the task prompt and coding sessions in their first message.

![The Fieldwork project on its Settings tab with Agent guidance selected: a Markdown box holding the project’s standing instructions for agents, about personal data, offline tests, user-facing text, the pilot changelog and pull requests, and a Save button.](https://volobox.io/docs/images/project-agent-guidance.light.webp)

*Agent guidance on a project's Settings tab: the project's instructions for agents in markdown, and Save.*

Write guidance as instructions ("Ask before closing a task", "Update docs/CHANGELOG.md after a user-visible change"). Leave one-off task detail to the task description.

## Approve learned notes

Learned notes are facts, not instructions. An agent proposes one when someone settles something in a conversation, and a project **Admin** decides it.

1. Open the project's **Settings** tab → **Learned notes**, or the **Note for the team** card in your **Inbox**.
2. Read the sentence under **waiting for a decision** in full. Agents will repeat it as fact.
3. Select **Approve** or **Decline**. To write one yourself, select **Add a note**.
4. Pin the few notes an agent must never get wrong. Pinned notes are carried into every agent prompt on the project; the rest are searched when relevant.

Coding agents get the project's notes after its agent guidance, so a note never reads as an amendment to the instructions.

## Give a team agent coding instructions

1. Open the agent's settings and select **Coding**.
2. With **Writes code** on, write **Coding instructions** (at most 4,000 characters) and select **Save instructions**.

They reach the coding agent on every turn of a session the agent's work opened, under the workspace and project guidance, which wins where they disagree. The agent's **Charter** does not reach the coding agent.

## Check that it works

1. Open a coding session on the repository in **Ask** mode.
2. Ask: "What does this repository tell you to run before you finish a change?"
3. The agent answers from `AGENTS.md`.
4. On the next pull request, request an AI review and check that its findings follow `REVIEW.md`.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| The AI review ignores a change to `REVIEW.md` | Rules are read from the branch the pull request targets. Merge the change first. |
| An agent ignores `CLAUDE.md` | The repository also has an `AGENTS.md`, which takes its place. Move the rules into `AGENTS.md`. |
| An agent follows a convention the team dropped | It is probably an approved learned note. **Retire** it under **Learned notes**. |
| You cannot see or edit **Agent guidance** | It is limited to project **Admins**. Ask one to update it. |
| Workspace and project guidance disagree | Both are sent and the project block is read last. Write the project block as a refinement, not a contradiction. |

## Next steps

- [From a task to a pull request](/docs/task-to-pull-request)
- [Write a preview manifest](/docs/write-preview-manifest)
- [Agents](/docs/agents)
- [Coding sessions and the task-to-PR loop](/docs/coding)
