Good Code Review

A checklist for reviewing code, for people and for agents. A card is one rule that a reviewer marks PASS, FAIL, or N/A. Each card has a FAIL example and a PASS example.

Choose a review

To review by hand, pick the level that matches your input and work through its checklist. Only stable cards are vetted.

• Change reviewChecks a diff or pull request: scope, size, compatibility, tests, and the description. Input: diff / PR.12 stable, 23 draft
• Function auditChecks one file or function: names, errors, concurrency, and security at the call level. Input: file / function.33 stable, 23 draft
• Module auditChecks a package or path: boundaries, state, dependencies, and the public surface. Input: package / path.6 stable, 21 draft
• Service auditChecks one running service: its API, failure handling, limits, and security. Input: service.21 stable, 27 draft
• System auditChecks a design that spans services: shared data, caches, migrations, and failure modes. Input: cross-service design doc.12 stable, 7 draft
• Codebase auditChecks a whole repository: CI gates, dependencies, setup, and conventions. Input: repo.11 stable, 6 draft
• Production auditChecks a release or launch: rollout, rollback, alerts, and load. Input: release / launch.6 stable, 4 draft
• Incident auditChecks an incident and its follow-up: evidence, guards, and owned actions. Input: incident.2 stable, 2 draft

Scope a review

To review only some concerns, such as performance, use the Concerns page.

Start a review with an agent

Paste this to your agent:

Read https://goodcodereview.com/llms.txt and use it to review my code.

To install it as a skill (Claude Code, Codex, Cursor, and other tools that read skills/<name>/SKILL.md), run:

npx skills add n0nuser/goodcodereview

To install it as a Claude Code plugin, run:

/plugin marketplace add n0nuser/goodcodereview
/plugin install goodcodereview@goodcodereview

Report format

Report each check as PASS, FAIL, or N/A with file:line evidence. A FAIL carries the card's severity. Any block FAIL means request changes. A should-fix or discuss FAIL goes in the review but does not block.

FAIL [block] chg-expand-contract - src/a.py:42 - renames the column and drops the old one in one migration
FAIL [should-fix] chg-one-concern - src/b.py:7 - a logging rewrite rides along with the bug fix
PASS chg-breaking-change-taxonomy - src/c.py:15 - no signature or return shape changes
N/A chg-perf-claim-evidence - the description makes no performance claim

Packs

A pack adds language-specific cards on top of the levels. Use one with the level that matches your input.

Python pack

Writing CSS? good-css.com has rules for reviewing CSS.