# Code review checklist

URL: https://codepanel.ai/guides/code-review-checklist

A copyable code review checklist in six groups: the one CodePanel's reviewers run on each pull request, how to grade a miss, and which items belong in rules.md.

A code review checklist is the list of questions every change is checked against: does it do what it says, is it tested, is it safe, does it follow the project's rules. The useful version is twenty-one one-line items in six groups, each checkable from the diff, so a person or an agent can run it the same way.

CodePanel reviews its own repository, where Claude Code writes the pull requests and answers the reviews. The checklist below starts from what CodePanel's reviewers are told to check: an agent runs whatever list you give it, line by line, and vague items get vague findings.

## The checklist CodePanel's starter panel runs

Every [reviewer](/docs/reviewers), whatever its role, gets the same task from the code (`convex/actions/ai/prompts.ts`):

- Bugs and logic errors
- Security vulnerabilities
- Performance issues
- Missing error handling
- Maintainability concerns
- Violations of the repository's review rules, when any are given

Two lines matter more than the list. Reviewers are told to report problems "in or caused by the change", not long-standing issues in untouched code, and to ground every finding in a line they can see. A reviewer that cannot see the code a claim rests on says what would need checking and marks the finding low confidence.

Each starter role then narrows the list (`convex/agents/presets.ts`):

| Role | What it is told to check |
| --- | --- |
| Bugs & Security | Logic errors, unhandled edge cases and errors, race conditions, missing auth or permission checks, injection, unvalidated input, leaked secrets |
| Tests & Maintainability | Changed behaviour with no test, tests that cannot fail, dead or duplicated code, misleading names, functions doing too much |
| Docs & Best Practices | The repository's own rules (quoting the rule each finding breaks), the official docs of the frameworks the diff uses, and docs the change makes wrong |
| Design & UX | Design-system reuse, accessibility, loading, empty and error states, narrow layouts, unclear copy. Skipped on rounds that change no UI file |

All four end with one instruction: report only concrete problems in the changed code, "each with the file, what goes wrong and when". Security (a deeper pass for auth, payments and secrets), Performance, and API & Migrations are in the Add reviewer picker but not in the starter panel. Tiers and effort are in [Reviewers](/docs/reviewers#roles).

## The code review checklist, ready to paste

Use it as a pull request template, or give it to the author agent to run before pushing and to a reviewing agent to run on the diff. Drop lines your CI already checks.

```markdown
## The pull request
- [ ] The description says what changed and why, and matches the diff: nothing described is missing, nothing in the diff is undescribed.
- [ ] One purpose. Unrelated refactors, renames and reformatting are in their own pull request.
- [ ] Anything the author could not run or check is stated.

## Correctness
- [ ] Each changed condition, loop and early return is right for empty, null, zero, one and maximum input.
- [ ] Every call that can fail (network, disk, parse, database) has its failure handled or passed up on purpose, never swallowed.
- [ ] Two requests or retries running at once cannot double-apply or lose an update.
- [ ] Callers of a changed function, and anything that depends on a changed response shape or schema, still work.

## Tests
- [ ] Changed behaviour has a test that fails without the change.
- [ ] The test asserts a result, not just that the code ran.
- [ ] Error and edge paths are tested, not only the happy path.
- [ ] No test was deleted, skipped or loosened to make the build pass.

## Security
- [ ] Input from outside (requests, files, webhooks, model output) is validated before it reaches a query, a shell, a path or HTML.
- [ ] Every new endpoint or function that touches user data checks who is asking, on the server.
- [ ] No secret, token or key appears in the diff, logs or error messages.
- [ ] Each new dependency is needed, pinned, and the one you meant to install.

## Docs and comments
- [ ] README, docs and examples that the change makes wrong are updated.
- [ ] New config, flags, commands and environment variables are documented where users look.
- [ ] Comments say why, not what, and none describe code that no longer exists.

## Project rules
- [ ] The repository's own rules (CLAUDE.md, AGENTS.md, .codepanel/rules.md) are met.
- [ ] The change uses the existing helper or component instead of a new copy of it.
- [ ] No dead code, commented-out code or leftover debug output.
```

Two notes on using it:

- **A checklist does not do the reviewing.** A 2022 study in *Empirical Software Engineering* ([Gonçalves and colleagues](https://doi.org/10.1007/s10664-022-10123-8)) gave 70 professional developers, mostly novices, three review tasks with original and seeded defects. The authors report that the guided checklist was the more effective aid for a simple review, while the plain checklist supported efficiency and effectiveness in a complex one; they found no strong relationship between the guidance given and review performance. The checklist sets what gets looked at; the reviewer still has to read.
- **Security is one group here, not the whole job.** The full treatment is in [Secure code review](/guides/secure-code-review). A secret in a pull request goes to the review providers with the rest of the diff ([Security and data](/docs/security)), so the secrets item is the author's to keep true before the push.

## Grade a miss by what fails

A checklist produces hits of very different weight, and an agent that treats every hit as a task will fix a missing comment as eagerly as a data-loss bug. CodePanel's reviewers apply one rule, worth copying:

> critical or warning only when you can name what fails, for whom, and how, from the code as it stands.

A gap that only makes a future mistake more likely, such as thin tests, missing docs, naming, duplication or dead code, is a suggestion. The orchestrator is given a matching rule when it decides which findings to post. Items grade differently depending on what you can name. For example:

| Hit | Grade |
| --- | --- |
| "The new branch has no test." Or: "This helper duplicates `formatDate`." | Suggestion, a [nit](/glossary/nit). Nothing is known to fail |
| "The new branch divides by the item count, which is zero for an empty cart; the checkout page errors." | Warning. Input, failure and who it hits are named |
| "The webhook handler writes before it verifies the signature." | Critical or warning, depending on what an attacker can write |

Grade each checklist group the same way before you adopt it, and say so when a group can only produce suggestions, so nobody blocks a merge on it. At CodePanel's default gate level (`warning`), only critical and warning findings are [blocking](/glossary/blocking-finding) until they are answered, and suggestions do not hold the pull request. The status blocks merging once you make `CodePanel` a required check ([merge gate](/docs/merge-gate#gate-levels)). The severity labels are defined in [Findings](/docs/findings#severity).

## Split the checklist by who reads it

Three readers use the checklist differently:

| Reader | Gets | Where it lives |
| --- | --- | --- |
| Every reviewer | What the code cannot tell it: invariants, deliberate conventions, mistakes the codebase keeps attracting | `.codepanel/rules.md`, read from the base branch on every round |
| The author agent | How to work and how to answer a review: run the tests, wait for the review, fix or rebut each finding | `AGENTS.md`, `CLAUDE.md` or Cursor rules |
| Everyone | The generic list above | The pull request template |

A generic item does not belong in `rules.md`. Every reviewer is already told to look for missing error handling, so "handle errors" in the rules file adds nothing and uses up the 16,000-character context budget. A rule belongs there only when a reviewer could not know it from the diff ([Writing review rules that agents follow](/guides/review-rules-for-agents)). What goes in the agent's own file is in [AGENTS.md](/agents/files/agents-md), [CLAUDE.md](/agents/files/claude-md) and [Cursor rules](/agents/files/cursor-rules).

CodePanel's own `rules.md` shows how small the file can be. As of 17 October 2026 it is 1,370 characters: one section of design rules scoped to `src/**/*.{tsx,css}`. One of them reads "Colour means something", and says to flag a severity colour used as decoration. On PR 172, which rebuilt the benchmarks pages, a reviewer raised a warning that cited it:

> The 'Only B' segment of the head-to-head bar uses fill-suggestion, a severity colour, to identify a model.

A violation of the repository's rules is a finding, and the Docs & Best Practices role is told to quote the rule each one breaks. Claude Code rated this one `up fixed` (merged 17 October 2026).

## Turn the project-specific items into rules

Make each project-specific item something a reviewer can check from a diff: a path and what to flag. A level-two heading that is a file pattern scopes the rules under it, so they reach reviewers only when the pull request touches a matching file ([Repo context](/docs/repo-context#scoped-rules)).

```markdown title=".codepanel/rules.md"
## src/payments/**
- Every call that creates a charge or a refund passes an idempotency key. Flag one without, since a retry would apply it twice.

## **/*.test.ts
- Flag a new .skip or .only, and a deleted or weakened assertion, unless the pull request says why.

## src/api/**
- Every handler calls requireUser(ctx) before it reads or writes. Flag one that touches the database first.

## src/**
- Outbound HTTP goes through src/lib/http.ts. Flag a bare fetch anywhere else.
```

Each rule makes one checklist line concrete: payments is the retry line, the test rule the skipped-test line, the handler rule the who-is-asking line, and `fetch` the existing-helper line. Merge the file first: reviewers read it from the base branch ([why](/guides/review-rules-for-agents)).

To try it with your agent, give it the [Repository setup](/docs/agent-setup) prompt to draft `rules.md` from your existing instructions, or the [Quickstart](/docs/quickstart) prompt to connect the repository and run the first review. The whole loop, from review to merge, is in [AI code review](/ai-code-review).