Customizing Code Review

By default, the automated code review agent evaluates every pull request using a generic rubric. That works fine out of the box, but it doesn't know what your linter already catches, which paths in your codebase are security-sensitive, or how your team likes to structure TypeScript. The .obvious/review/ directory is how you teach it.

Once configured, reviews are tailored to your codebase: noise goes down, signal goes up.

How it works

Place a review/ directory inside .obvious/ at the root of your repository:

.obvious/
└── review/
    ├── overlay.md
    ├── scoring-model.md
    ├── category-overlays.md
    └── comment-examples.md

All four files are optional. You can start with just one. The review agent picks up whatever is present and incorporates it into every PR evaluation for that repository.

The four configuration files

overlay.md — your primary entry point

This is the most important file to start with. overlay.md defines the rules that make your codebase different from a generic project:

• Tooling-handled rules. If Biome, ESLint, or TypeScript strict mode already catches something, tell the reviewer to skip it. This is the single biggest lever for reducing noise.

• High-scrutiny paths. Flag directories that need extra attention — authentication middleware, payment processing, anything where a subtle bug has outsized consequences.

• Architecture references. Point the reviewer to your AGENTS.md or other documentation so it understands your module boundaries and conventions.

Here's a concrete example:

## Tooling-Handled (skip these)
- Import ordering — handled by Biome
- Unused variables — handled by TypeScript strict mode

## High-Scrutiny Paths
- `apps/api/src/auth/**` — authentication, security-critical
- `apps/api/src/billing/**` — payment processing

## Architecture
- See AGENTS.md for module boundaries
- Drizzle ORM patterns in apps/api/src/db/

Even a short overlay.md like this makes a meaningful difference. The reviewer stops flagging things your toolchain handles and pays closer attention to the paths that matter most.

scoring-model.md — severity thresholds

The review agent scores each finding on a 0–100 scale and maps that score to a severity level:

Score	Severity
≥ 90	Blocker
≥ 75	High
≥ 60	Medium
< 60	Suggestion

scoring-model.md lets you define how findings are scored across dimensions like evidence strength, confidence, false-positive risk, fix locality, and scope fit — and adjust where the thresholds sit for your team's standards.

Most teams don't need to touch this file initially. It becomes useful when you want to calibrate how aggressively the reviewer flags issues, or when your team has a specific bar for what constitutes a blocker vs. a suggestion.

category-overlays.md — domain-specific rules

This file organizes rules by technical domain. You can define standards for:

• TypeScript — type patterns, inference conventions, strict mode expectations

• React — component structure, hook rules, prop handling

• Backend / API — request validation, error handling, response shapes

• Database — query patterns, migration conventions, ORM usage

• Testing — coverage expectations, assertion style, test organization

category-overlays.md is where you encode "how we do things here" in enough detail that the reviewer can apply it consistently across PRs. Keep entries specific and actionable — vague guidance doesn't translate well into review behavior.

comment-examples.md — calibrate the signal

This file has two sections:

High-signal examples — the kind of review comments you want to see: specific, grounded in actual code, with a concrete suggested fix.

Noisy patterns to suppress — comments the reviewer should avoid. Common examples:

• "Consider improving the types here"

• "Add more logging"

• "This could be refactored"

Providing a few examples of each helps the reviewer understand your team's bar for what's worth saying vs. what's noise.

Getting started

The minimum viable setup is a single file: create overlay.md and add a few lines about what your toolchain already handles. That alone will reduce duplicate findings immediately.

.obvious/
└── review/
    └── overlay.md

From there, add the other files when you have a specific need:

• Reviews too noisy on a particular domain? Add domain rules to category-overlays.md.

• Severity calibration feels off? Configure thresholds in scoring-model.md.

• Reviewer is leaving generic comments? Add suppression examples to comment-examples.md.

You don't need to configure everything upfront. Start small, iterate as you notice patterns.