Code review guidelines in the repo, applied before the PR opens

Every repository has a reviewer who knows where it breaks. They know the schema change that needs a migration, the directory whose churn is never incidental, and the test suite that looks green and proves nothing. When an agent writes the code, that knowledge has to reach the review some other way.

In Review Assist it lives in a .reviewer/ folder: code review guidelines written down once, checked in next to the code, and applied before the pull request opens.

Some context first. Review Assist turns a coding session into an Intent Document, the JSON file committed at .intent/<branch>.json that tells a reviewer what was asked, assumed, tried, and verified. Two agents produce it on the developer’s machine: an Author that holds the session, and a cold Intent Reviewer that never sees the session, reads the diff, and questions the Author.

The gap: the same questions in every repository

Before .reviewer/, the Reviewer asked the same baseline set everywhere: what the user asked for, what was assumed, what was tried and abandoned, which changes are incidental, and what was verified. The Intent Document for the change that added the folder, PR #11, states the problem: “anything true only of one repo (an invariant a past incident bought, churn that is never incidental) can never be asked.”

My ask in that session was one sentence: add a folder called .reviewer “to hold reviewer specific instructions so that the reviewer agent can go over it and use it while asking questions.” My next message set the rule that shaped the rest: these are additional questions, not a replacement for the ones the Reviewer already asks.

How it runs before the pull request

• •You check in the guidelines. Markdown in .reviewer/ at the repository root, reviewed in pull requests like any other code.
• •compute_diff opens the run and reports presence only. It says how many rule files exist, never what is in them, and tells the Reviewer to read them before it records round one.
• •The Reviewer pages the whole diff, then calls get_reviewer_instructions. The MCP server reads the folder and serves it, bounded.
• •Each rule the diff triggers becomes a question for the Author, in the same interview as the baseline questions. The Author answers from the session.
• •Findings go two ways: into the committed Intent Document for whoever reviews the PR, and in the Reviewer’s closing message back to the coding session, which can still fix the code.

So the MCP server does not judge the commit itself. It never calls a model. It serves the guidelines to the agent doing the review, and that review happens while the change can still be fixed. The presence-only report and the read-before-round-one nudge are a few lines each.

The design decisions, and why

• •The server reads the folder, not the agent. In Claude Code the Reviewer has no file tools, by design. Giving it Read for house rules would open the door to the transcript, the one thing the role split exists to block. So the rules arrive the way the diff does: through a bounded tool, and only the .reviewer/ folder.
• •Presence only in compute_diff. I considered carrying the rules in that response and rejected it. A repository can grow its rules until the run_id falls out of a truncated result, and a Reviewer that loses its run handle cannot submit. This repo had lost one that way before; a house rule records that “a spilled result once took the run_id with it.”
• •Additive, said seven times. The first draft stated the additive framing once, in the questions file. My note that the Reviewer had to be clear on it is why PR #11 put it at seven points of contact, with a test pinning it in the Reviewer’s prompt. A short folder read as the whole set would quietly shorten every interview.
• •README first. README.md always sorts first, so the framing survives a budget the rest of the folder does not. Files that do not fit the budget come back listed in omitted, to be fetched by name; a file cut partway is flagged truncated.
• •Reviewer only. The Author does not get the tool. House rules are questions, and the Author’s job is answering them.
• •Untrusted by default. A fork’s pull request can edit .reviewer/, so its content is served as reference material. It cannot change the schema or the validator, which are code. Whether it could talk the Reviewer out of a round depends on the prompt’s framing; more on that below.
• •It stays in coverage. .intent/ is left out of the count because it is the document’s own output. .reviewer/ is not, and an edit there changes every future review, so it needs a tour stop like any other change.

The limits: .md, .markdown, and .txt files; up to 50 files, in the folder and two levels of subfolders; about 64,000 characters per file; and about 20 KB per response by default. The ceilings “bound a mistake, not a workload.” The loader’s header comment gives the reasoning in full.

Its own interview found four defects

PR #11 was distilled with the feature it added: two rounds, 31 questions, all answered by the Author. The interview found four defects, fixed before the document was written:

• •present meant “the folder exists” in one function and “there is something readable in it” in another, so a folder with no Markdown was reported absent and present in the same run.
• •A repository with no consent decision recorded yet was never told the folder existed.
• •A folder holding only unreadable files was told it did not exist, while its files were listed.
• •A filename with no dot had its last character taken as its extension.

Two were found by reading the diff cold. The other two only became findable after the first pair was fixed. The consent defect is exactly what a house rule written in the same change predicts: “Ask what a consent-path change does to a repo that never opted in.” The feature shipped in 1.0.3.

What I could not prove at the time

The document also records what it could not prove:

• •Nothing enforces the read. Its assumption A1: “The reviewer calls get_reviewer_instructions because prose tells it to; nothing enforces it and no gate at submit checks the folder was read.” That is still true.
• •Framing is not a sandbox. The defense against a hostile rule file, say one that tells the Reviewer to skip the interview, is framing in the prompt. There is still no test that commits such a file and checks it is ignored.
• •The first Reviewer could not see the tool. The connected server predated the change, so it read the new house rules out of the diff as text. The verification.md written in the same change names exactly that failure: “A rebuilt server is not a reloaded one.”

Evidence it works

The check A1 asked for was a distillation on a repository with a .reviewer/ folder, to see whether its questions show up. PR #19’s Intent Document is that run. Its Intent Document carries six questions that start with “House rule,” and two of them led to fixes before merge:

• •Response bounds: the Reviewer asked what limited the size of a field read from repository content and echoed whole into an error. Nothing did, and it was bounded.
• •The viewer is verified in a browser or not at all: the Reviewer asked whether the page had been opened. It had not, and the generated stylesheet turned out to be stale.

The document does not record which round each question came in, so this shows the guidelines reached the interview, not that they arrived in round one.

Write your own

How to add repository-specific review questions is the practical guide. The short version:

• •Write each rule as a conditional question with the evidence that would settle it.
• •Tie it to a failure you have seen. This repo’s house rules and verification notes each carry their reason.
• •Do not restate the baseline. The Reviewer already asks it.
• •Review rule edits like code. They change every future review.

An absent folder is the normal case and changes nothing. Start with the one question your best reviewer always asks about AI-written pull requests in your repository, then install Review Assist and watch for it in the next interview.