AGENTS.md and policy files for AI code review

Most repos already write down how they want code changed. That might be an AGENTS.md for coding agents, a CLAUDE.md, or a REVIEW_POLICY.md for humans. MergeJudge reads these files and gives them to the AI reviewer, so the AI pull request review follows your repo's rules and not just generic advice.

There are three places to steer the review:

File	What it is	What it controls
AGENTS.md, CLAUDE.md, REVIEW_POLICY.md, APPROVAL_POLICY.md	Plain-language policy	What the AI reviewer should look for and how strict it should be
.mergejudge.yml	Config	Lanes, protected paths, review mode, rubrics, provider, which policy files are read
Feedback on the MergeJudge comment	Signals	Lessons that can turn into a proposed .mergejudge.yml change, which a human reviews

The policy-file basics (caps, the copy-paste REVIEW_POLICY.md template, policy_files / policy_exclude) are on Policy files. This page covers how the pieces fit together, and how to use AGENTS.md for code review.

How policy files reach the reviewer

• Default list. With no config, MergeJudge looks for REVIEW_POLICY.md, APPROVAL_POLICY.md, AGENTS.md and CLAUDE.md at the repo root.
• Base branch only. Files are read from the tip of the base branch, never from the PR head. If a PR edits AGENTS.md, that change does not affect the PR's own review. It applies from the next review after it's merged.
• Trusted vs untrusted. Policy text goes into the system prompt as a trusted <repo_policy> block. The PR's title, body and diff go in a separate untrusted block, and the model is told to ignore instructions inside it.
• Stricter only. Policy can raise a lane (auto → review → block). It can never lower one below what the deterministic rules decided.
• Size cap. 8 KB per file and 8 KB in total by default (policy.max_each_bytes, policy.max_total_bytes). When the files are too long, the space is shared fairly so one long file doesn't crowd out the others, and the review reports the truncation.

This works the same with the GitHub Action, the hosted GitHub App and the runner, because they share one review engine.

Using AGENTS.md for code review

If you already keep an AGENTS.md for coding agents, you don't need a second file. Add a short section aimed at the reviewer. Keep it to what is specific to your repo. The model already looks for bugs, security holes and broken logic.

## Code review

Reviewers (human or AI) should check:

- Every new HTTP handler under `src/api/` checks authorization on the resource, not only "logged in".
- Database migrations are additive. Dropping or renaming a column needs a linked plan in the PR body.
- Changes to `src/billing/` always go to a human reviewer, even when small.
- No tokens, cookies or raw personal data in logs.

Don't comment on:

- Formatting and import order (the linter handles it).
- Typo fixes in comments and docs.

The section is read like any other policy text, under the same 8 KB cap. If your AGENTS.md is long and mostly about build commands, put the review rules in REVIEW_POLICY.md instead and skip the agent file:

# .mergejudge.yml
policy_files: [REVIEW_POLICY.md]   # read only this file
# policy_exclude: ["CLAUDE.md"]    # or keep the defaults and skip one
# policy_files: []                 # or turn policy injection off

Policy text vs .mergejudge.yml

Use policy files for judgement and .mergejudge.yml for hard rules.

• "Anything under deploy/ must be looked at by a human" is a hard rule. Put it in lanes.protected, so the deterministic rules enforce it even when no AI provider is configured:

  lanes:
    protected:
      - ".github/**"
      - "deploy/**"
      - "**/auth/**"
      - "**/migrations/**"
      - "src/billing/**"   # added for this repo

  If you set lanes.protected, it replaces the default list, so copy the defaults you want to keep. The example above shows only some of them; the full default list is in the config reference.

• "New endpoints should check authorization on the resource" needs judgement. Put it in the policy file, so the AI reviewer applies it.

How MergeJudge learns your repo's rules

MergeJudge doesn't quietly rewrite its own rules. Learning collects signals, and any change to the rules arrives as a pull request to .mergejudge.yml that a human has to review and merge.

Signals

• Feedback boxes. The MergeJudge comment on each PR ends with checkboxes (Correct / Too lenient / Too strict / Wrong reason / Missed something), plus a wrong / right box for each failed rubric criterion. Ticks only count from people with write access. Bot comments are ignored.

• Notes. A writer can comment:

  /mergejudge learn migrations in this repo always need a rollback note in the PR body

• Lessons are appended to lessons/lessons.jsonl on a separate mergejudge-learning branch, never to the PR under review.

With the hosted GitHub App, MergeJudge also looks at what people did afterwards:

• A PR that was laned auto and then reverted, or followed by a linked fix (for example "Fixes #123"), counts as evidence that a path should be protected.
• A human merging a PR that was left in review or block counts as evidence that a rubric criterion may be too strict. Only human merges count here. Bots and PRs marked as agent work are ignored.
• Inline findings that writers dismiss again and again ("false positive", a thumbs-down, a thread resolved with no code change) are moved out of the inline comments, and then hidden. This never changes a lane, label, rubric result or check.

The GitHub Action learns from explicit feedback only, meaning the checkboxes and /mergejudge learn. Merges and reverts alone don't create lessons there.

The proposal PR

A scheduled run (weekly on the hosted service; in the Action, the schedule you set) or a manual one reads the lessons. Once there are enough (learning.propose_after, default 10), it opens or updates one PR from mergejudge/proposal-learning. It can suggest only two kinds of change to .mergejudge.yml:

• More protected paths. It adds <dir>/** to lanes.protected after at least 2 reverts or linked fixes of auto PRs touching that directory.
• Rubric notes. It adds a short note to rubrics.notes.<id> when at least 3 PRs from at least 2 different people say a criterion was wrong.

The PR body lists the evidence. It carries the do-not-merge and needs-human labels, is always laned block by MergeJudge itself, and is never approved or merged by MergeJudge. A guard re-parses the config before and after each edit. It refuses anything else: it can't remove a protected path, loosen lanes.auto, touch .github/, change the provider, or add a note to a security criterion.

You can tune the thresholds under learning.proposal, set edits: false for report-only proposals, or turn learning off with learning.enabled: false. Full details: Learning.

Checklist

1. Add a "Code review" section to AGENTS.md, or a REVIEW_POLICY.md (template), and merge it to the default branch.
2. Move hard rules into lanes.protected in .mergejudge.yml.
3. Tick the feedback boxes when a review is wrong, or comment /mergejudge learn ….
4. Review the weekly proposal PR like any other change.