Coding

Guide

Guide coding agents with repository files and guidance

Tell coding agents and the AI reviewer how your team works: AGENTS.md, REVIEW.md, workspace and project guidance, learned notes.

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.
  • 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

WhereWho reads itUse 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 reviewerHow to build, test and change this code: commands, conventions, layout.
REVIEW.md in the repositoryThe AI reviewerWhat a review should weigh and flag.
Workspace guidanceEvery agent on every run, coding sessions and coding assignments includedStanding instructions for the whole organization.
Project Agent guidanceAgents working in the project: chat, coding sessions, coding assignments, workflow runs about the projectInstructions that hold for this project only.
Project Learned notesAgents working in the projectFacts the team agreed are true ("We release on Thursdays").
A team agent's Coding instructionsThe coding agent in sessions that agent's work openedHow this particular agent wants work done, for example a frontend agent and a backend agent.
Note for the agent when you start workThat run's coding agentScope 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.
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.

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.
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.
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

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

Next steps