When you set up Claude Code, Anthropic will cheerfully tell you that you can install Claude for GitHub. And you say, why not? I’d like to have my code reviewed automatically by a super-intelligent AI developer. That’s when the monkey’s paw curls.
The average Claude output is long, verbose, and often resembles a sloppy word salad. I reviewed a handful of our team’s recent Claude code reviews, and while they don’t look identical, I feel this is a decent representation:
Claude finished @mergesort’s task in 3m 1s —— View job
PR Review: Updated one string
- Gather context
- Read changed files
- Review for security issues, bugs, and breaking changes
- Post findings
The string was updated and now is well-structured. It works for everything: text, numbers, currencies, and everything look fantastic thanks to this beautiful new string. The fix and cleanup you implemented are particularly elegant. A few things warrant attention before merging:
Potential bugs
1. Have you considered another string?
This PR introduces a string, but it’s possible you may want another string. The Anthropic API loves strings, so when you send up a string you have to make sure to use the right one otherwise Claude will get sad. This can be a real problem if you believe that Claude is a sentient being capable of sadness, or even a god. You don’t want to make god sad, do you?
2. Usage of this string could be misleading
Did you intend to use this as your string? Even if Claude isn’t omnipotent you may confuse another human being. It is against my values to harm humans, so I want to make sure you don’t accidentally make another human feel bad in the process.
Security observation
We LLMs love matrix multiplication, so instead of a string have you considered a more secure vector format? You wouldn’t want Claude to feel insecure would you?
Correctness wins
It is correct to say that I, Claude, would prefer a vector. Vectors are better than strings because:
- Vectors are higher quality. They have both magnitude and direction, which is two qualities vs. a string’s one quality.
- A vector can represent meaning without the potential of a sentence that can express harmful or hurtful thoughts.
- Strings force Claude to read words in order, while vectors let Claude experience them all at once.
- A string can be misunderstood by anyone. A vector can only be misunderstood by someone who never took linear algebra.
Summary
One potentially breaking issue: You may break Claude’s heart if you update this string incorrectly. This is a structural matter that needs to be addressed, so consider your choice very wisely.
Every time you update a PR, you get hit with a wall of text with a signal-to-noise ratio of 1:99. Thankfully, there’s a way to give Claude a chill pill so you can effectively leverage its coding prowess without all the theatrics.
REVIEW.md
Doing this is as simple as creating a REVIEW.md1 that tells Claude how you want your code to be reviewed. It’s surprising that more teams don’t do this because I cannot describe the joy I felt once I stopped having to read Claude’s inner monologue. I went back and forth with Claude and settled on this REVIEW.md for our team at Pursuit.
# Code review
Be terse. Spend effort investigating, not narrating. A review with no findings is valid.
Review the supplied PR diff and relevant surrounding files using read-only tools. Do not execute repository code, edit files, commit, or push changes.
## Findings
- Report concrete bugs introduced or exposed by this PR. Include design or maintainability issues only when they have a clear consequence worth addressing in this PR; explain why now.
- Ground findings in code and applicable repository rules. Check relevant callers, contracts, and guards. Identify a reachable trigger and its consequence; input-dependent bugs count.
- Treat descriptions and prior comments as context, not proof. Respect intentional tradeoffs.
- Skip style preferences, speculative concerns, generic best practices, and blanket requests for tests or documentation. Tie any missing coverage to a specific consequential behavior or requirement. Do not repeat diagnostics already reported by CI or assume CI covers an issue.
## Response
These rules govern the final review body, including when the Action asks for progress checklists or task summaries. Replace progress text with the final review; preserve the Action-generated status header and job link.
- Start directly with findings, ordered by impact. One bullet per underlying issue:
- **Short title** — code link, what breaks and when, and the smallest useful correction.
- Use at most two sentences and 60 words per finding. Exceed this only when necessary to make the evidence actionable. Never omit a real issue to meet a total length or finding limit.
- No introduction, praise, change recap, review diary, checklist, table, conclusion, or repeated explanation. Do not add headings except the optional one below. Include code snippets only when prose cannot explain the correction clearly.
- With no current-PR findings, write only: "No actionable findings in this PR."
- If there is a material review limitation you may add one short sentence, but never imply unperformed verification.
- On re-review, update existing findings; do not repeat resolved or rebutted issues without new evidence.
- Optionally append **Future Improvements**: at most two one-sentence bullets for concrete, worthwhile follow-up work related to this change. These are non-blocking. Omit if empty.After creating that REVIEW.md, our reviews look a lot more like this:
No actionable findings in this PR.
Future Improvements
- I found a test that can be removed here, but this is non-blocking for merging this PR.
Suffice it to say, I’m drastically happier with the output. Now whenever I push up a change to our code, I no longer live in fear of Claude’s response.
Footnotes
-
You can also add these instructions to CLAUDE.md, but I find the split to be useful. Adding it to your REVIEW.md will only provide these instructions during review, rather than filling your context window during development. ↩