A code review checklist for people and agents. Each stable rule cites at least three independent organisations, and every check ends in
PASS,FAIL, orN/Awithfile:lineevidence.
Good Code Review is a set of Markdown files. An AI coding agent loads them as a "skill" (a folder of instructions it reads when you ask), or you work through them by hand. You ask for a review of your code and get back a list of verdicts, each naming a rule and a line.
That is a real run on a pull request of mine (how it was made: docs/demo). A shorter sample, with made-up paths and lines:
Verdict: request changes - change, function - 2 block, 1 should-fix FAIL, 1 PASS, 14 N/A
FAIL [block] chg-expand-contract - src/a.py:42 - renames the column and drops the old one in one migration
FAIL [block] svc-sqli-authn - src/db.py:88 - proven: builds the WHERE clause with an f-string from request.args
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: 14 cards, applies_when does not hold
Pick what you are reviewing (a diff, a function, a service, a whole codebase, a production setup, or an incident) and you get the checks for that level. Each check has a FAIL example and a PASS example, so a reviewer, human or agent, knows what each verdict means. Anyone can check the review afterwards, because every verdict names a card and a line.
There are 202 stable checks: 188 across the eight levels and 14 in the language packs. The site prints the live count on its home page.
- A linter enforces rules about syntax. These cards cover what a reviewer decides: scope, compatibility, failure handling, rollout.
- An AI reviewer brings its own judgment. Here the agent reviews against a fixed rule set, and each stable card links the published sources behind it.
- A style guide says what to do. A card says what to check and when it fails.
Each stable check is backed by at least three independent organisations that have published the same practice. The exception is a check whose source is the maintainer's own guide, which the repository records (ADR 0001). The card links every source. The organisations include Google, Microsoft, GitHub, AWS, Stripe, Cloudflare, Mozilla, OWASP, W3C, IETF, NIST, and GOV.UK. Those organisations did not write or endorse this project. Checks with less backing stay as drafts and never decide a verdict. docs/COVERAGE.md maps every source to its cards.
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
After you install the skill, name it in your request, such as /good-code-review review this PR. An agent that is not told may review without it.
The skill folder also holds two focused skills, review-code-security and review-code-accessibility. Each reads its card list from goodcodereview.com, so it needs network access. In a sandbox without network access, use good-code-review, which carries the cards with it.
To install it as a Claude Code plugin, run:
/plugin marketplace add n0nuser/goodcodereview
/plugin install goodcodereview@goodcodereview
To review by hand, open https://goodcodereview.com, pick a level, and work through the checklist.
Everything is static files, served without a server, an account, or a key:
cards.jsonwithcards.schema.json: every stable card.cards-index.jsonis the slim lookup table. Each level and concern also has its own file (see docs/cards-json.md).llms.txt: the routing table and verdict format, for an agent's first read.agent.json,.well-known/ard.json, and.well-known/agent-skills/index.json: discovery files.- WebMCP: pages register read-only tools (
start_review,list_levels,list_cards) in browsers that support it. - A command line in
cli/. It is not on PyPI yet, souvx goodcodereviewdoes not work today; run it from a checkout.
The only stability promise is the one in docs/api-versioning.md.
- To review a change, start with
cards/change/. - To audit existing code, pick a level in
cards/audit/: function, module, service, system, codebase, production, or incident.
Pick concerns, topics, and levels on the Concerns page. The picks live in the address, so you can share them and agents can fetch them:
https://goodcodereview.com/concerns?concern=security,performance&level=function
https://goodcodereview.com/concerns.md?concern=security,performance
https://goodcodereview.com/cards.json?topic=forms
concern, topic, and level take comma-separated values or repeat. A card matches when it has any value given for each filter. group=concern|level|topic groups the list.
cards.json is one file with no pagination. Each level has its own file, cards/<level>.json, and each concern has cards/concern-<concern>.json and concerns/<concern>.md. cards-index.json is a slim lookup table. docs/cards-json.md says how to fetch part of it. The shape carries a schema_version, and docs/api-versioning.md is the versioning policy.
Each check gets PASS, FAIL, or N/A, with file:line evidence. A FAIL carries the card's severity: block, should-fix, or discuss.
Send one card per pull request. See CONTRIBUTING.md. Agents: see AGENTS.md.
See also docs/COVERAGE.md, which maps sources to cards, and docs/deploy.md.
- To report a wrong card, use the card correction form.
- To propose a card, use the card proposal form, then follow CONTRIBUTING.md.
- To promote a draft card to stable, read docs/PROMOTION.md and use the promote a draft form. The Drafts by what they lack page shows what each draft needs.
- To report a security issue, follow SECURITY.md.
- To get help, see SUPPORT.md.
- To see what changed, read CHANGELOG.md. To cite this project, use CITATION.cff.
- Everyone who takes part follows the Code of Conduct.
Code (tools/, workflows) is under the MIT licence. Content (cards/, packs/, glossary/, docs/) is under CC BY 4.0.
Created and maintained by Pablo Jesús González Rubio.