Review rules

What review rules are

A review rule is one sentence, such as “Every API route calls requireAuth() before reading the request”. Codzee checks each pull request against your rules and leaves a labelled comment when one is broken. There are four kinds of rules:

Add a rule

1. Open Settings → Review rules.
2. Pick a template, or choose + Add rule to write your own.
3. Fill in the three fields below and save.

• Rule: write it like you’d tell a new teammate, one rule per box. Example: API handlers must validate request bodies with zod
• Applies to (optional, empty = all files): example src/api/**. Separate several patterns with commas. Other examples: **/*.sql, migrations/**, !**/*.test.ts
• Severity: Suggestion, Important (default) or Blocking.

Rule text is tidied up when you save: extra spaces and line breaks become single spaces, and a rule can be 1 to 500 characters.

Writing rules that work

Name the exact thing to check: which function, file or pattern.

Applies to: path patterns

Leave it empty and the rule applies to every file. Otherwise a file matches if it matches at least one normal pattern (or there are none) and no ! pattern.

Combine patterns with commas, for example src/**, !src/db/** means everything under src/ except src/db/. Up to 10 patterns per rule.

Severity

• Suggestion: a light comment; fine to ignore.
• Important: a normal review comment (the default).
• Blocking: fails the Codzee check until fixed. See below.

How blocking rules work

A blocking rule is checked on every review against the whole pull request. Codzee reports on each commit in two places: the check run Codzee review and the commit status codzee-app. If the PR breaks a blocking rule, both fail and the check lists each broken rule:

✖ Codzee review — 1 blocking rule broken · 1 comment posted · 1 major

1 blocking rule broken

- Every migration has a rollback — migrations/0042_add_orders.sql:3 — Adds the orders table with no down() to drop it.

and an inline comment points at the line:

🔶 Bug | Major · ⛔ Blocking team rule: "Every migration has a rollback"

Adds the orders table with no down() to drop it.

• Only when Codzee is sure. A rule counts as broken only when Codzee is sure, on a line the PR adds. When it is unsure, the check passes: Codzee never blocks a merge on a guess.
• Fixing it turns the check green. Push the fix and the next review passes the check.
• If the check can’t run, the Codzee review check shows neutral with “Couldn’t check blocking rules — push again to retry”, and the codzee-app status says blocking rules couldn’t be checked. A neutral check does not block merging, even when it is required. It never fails because of a hiccup on our side.
• To actually stop merges, a repo admin makes the check required: in GitHub go to the repo’s Settings → Branches → your branch protection rule → “Require status checks to pass before merging” and select Codzee review (or the codzee-app status). Without that, the check is red but merging is still possible.
• While reviews are paused (paused in settings, no plan, or the plan’s review limit reached), Codzee posts no check at all, so a required check waits, and blocks merging, until reviews resume.
• Blocking rules count toward the same plan limit as your other rules.

Focus and ignore rules

Ordinary rules whose text steers the review:

• “Be extra strict on input validation in src/payments/**” (important)
• “Don’t comment on style or naming in legacy/**” (suggestion)
• “Ignore generated files in src/gen/**” (suggestion)

Org-wide and repo rules

When you create a rule you choose whether it applies to all repositories or to one repository. In a repository’s view, an org-wide rule has one switch, On for this repo. Turn it off and the rule stops applying to that repository only. For example, the org rule “Use logger, never console.log” can be Off for this repo on acme/legacy-cli while staying on everywhere else.

A repository’s own rules come first. If one disagrees with an org-wide rule, Codzee follows the repository’s rule. For example, with the org rule “Use logger, never console.log” and the acme/tools rule “console.log is fine in scripts/”, Codzee won’t flag console.log in acme/tools/scripts/.

What you’ll see on the PR

A comment from a broken rule keeps Codzee’s usual label (what kind of problem and how serious) and adds the rule that triggered it, so a serious bug that also breaks a rule still reads as serious:

🔶 Bug | Major · ⚠️ Team rule: “API handlers must validate request bodies with zod”

createOrder reads req.body.items without a zod schema. Add OrderSchema.parse(req.body) before using it.

Rule set in Codzee settings · Manage rules

Suggestion rules use a 💡 instead of the ⚠️. The review summary adds one line, for example:

Checked against 6 team rules: 2 comments.

Limits

At the limit, “Add rule” is disabled and the page says “10 of 10 rules on Starter.” with a link to move to Team for up to 50 rules. If you are over the limit at review time, the extra rules are skipped and the summary says so: “2 rules skipped — your plan includes 10.” A repository’s own rules are kept first, then blocking rules, then important rules, then suggestions, then the oldest.

Coming next

Rules in your repo. Put a .codzee.md file in the repo root. Codzee reads it from the pull request’s base branch, so a PR cannot loosen its own rules. Only bullets under a ## Rules heading count; everything else is ignored.

# Codzee rules for acme/api

## Rules
- API handlers must validate request bodies with zod (src/api/**) [important]
- Every migration needs a down() rollback (migrations/**) [blocking]
- Use our logger, never console.log
- Don't comment on naming in legacy code (legacy/**) [suggestion]
- Prices are integers in cents, never floats (src/billing/**, src/orders/**)