AI code review rules

# AGENTS.md: rules for AI code reviewers

This repository is reviewed by AI reviewers (Claude Code Review, Cursor Bugbot, GitHub Copilot code review) as well as people.
Review rules live in review-only files, separate from coding instructions, and are kept short and testable.

## Which file each reviewer reads
| Reviewer | Reads | Notes |
|---|---|---|
| Claude Code Review (service) | `REVIEW.md` (root, plus subdirectory files) and CLAUDE.md files | Read from the base or default branch, never from the PR. Merge rule changes first. Protect the default branch or subdirectory files and severity overrides are ignored |
| Claude Code `/code-review` (local) | CLAUDE.md only | Does not read `REVIEW.md` |
| Cursor Bugbot | `.cursor/BUGBOT.md` (root always; nested ones for changed paths) | `.cursor/rules` does not apply to Bugbot |
| Copilot code review | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md` | Use `excludeAgent: "coding-agent"` for review-only instruction files |

## Writing review rules
- Define severity for this repo: what counts as blocking (wrong behaviour, data leak, unsafe migration) and what is a nit at most.
- Cap nits (for example "at most five per review").
- List what not to report: anything CI enforces (lint, format, types), generated paths, lockfiles, vendored code.
- List what to always check, as concrete, checkable rules ("new API routes have an integration test").
- Require evidence: behaviour claims must cite `path:line`, not infer from names.
- One rule per line. No style essays. Under ~60 lines per file.
- When a reviewer is repeatedly wrong about something, add a rule; when a rule never fires, delete it.

## When you are the author
Before opening a PR, read the review files above and check your diff against the "always check" rules yourself.
Use the `set-up-review-rules` skill to create or change these files.

# CLAUDE.md

@AGENTS.md

## Claude Code notes
- Skills from this loadout live in `.claude/skills/`: `set-up-review-rules`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "AI code review rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/ai-code-review-rules/ -->

# GEMINI.md

@./AGENTS.md

## Gemini CLI notes
- Skills from this loadout live in `.agents/skills/`: `set-up-review-rules`. Use them when their description matches the task.
- Follow AGENTS.md above; where this file and AGENTS.md disagree, AGENTS.md wins.

<!-- From the Agent Loadout "AI code review rules" v1.0.0 — https://loadout.jnw-it.com/loadouts/ai-code-review-rules/ -->

---
name: set-up-review-rules
description: Create or tune review-only instruction files for Claude Code Review, Cursor Bugbot and Copilot code review from one rule list. Use when setting up AI code review or when reviews are noisy or miss team rules.
---

# Set up review rules

1. **Collect evidence.** Read the last 10–20 AI review comments if available (`gh pr list --state merged --limit 20`,
   then `gh pr view <n> --comments`). Note false positives, noise categories and real misses.
2. **Write one rule list** with four sections: severity definitions, nit cap, do not report, always check.
   Start from `references/review-rules-template.md`. Every rule must come from evidence or a known team requirement.
3. **Generate the files** for the reviewers the team uses:
   - Claude Code Review: root `REVIEW.md`; subdirectory `REVIEW.md` only for path-specific checks.
   - Cursor Bugbot: `.cursor/BUGBOT.md` with the same content.
   - Copilot: `.github/instructions/code-review.instructions.md` using `references/copilot-review-instructions.md`.
4. **Keep coding rules out.** Rules that also apply while writing code belong in `AGENTS.md`, not in review files.
5. **Land it.** Open a PR with only these files. Remind the human that Claude Code Review reads `REVIEW.md` from the
   default branch, so the new rules apply to PRs opened after the merge, and that branch protection is needed for
   subdirectory files and severity overrides to count.
6. **Re-check** after a week of reviews: delete rules that never fired, sharpen rules that were misapplied.

# Review instructions

## What blocking means here
Blocking: incorrect logic, unscoped database queries, secrets or personal data in code, logs or errors, migrations that are not
backward compatible, removed authorisation checks. Style, naming and refactoring suggestions are nits at most.

## Cap the nits
Report at most five nits per review.

## Do not report
- Anything CI already enforces: lint, formatting, type errors, spelling
- Generated files under `<generated paths>` and lockfiles
- Test code that deliberately breaks production rules

## Always check
- <New API routes have an integration test>
- <Log lines do not include email addresses, user IDs or request bodies>
- <Database queries are scoped to the caller's tenant>

## Evidence
Behaviour claims need a path:line citation from the source, not an inference from a name.

# Copilot review-only instructions

Save as `.github/instructions/code-review.instructions.md`. `applyTo` limits which files the rules attach to;
`excludeAgent: "coding-agent"` keeps the file away from the Copilot coding agent so it is used for review only.

```markdown
---
applyTo: "**"
excludeAgent: "coding-agent"
---

<paste the same four sections as the shared rule list>
```