Review Policy File

Atlas Review lets you customize review behavior per project with an optional policy file. This is the fastest way to tell Atlas which paths deserve deep review, which files should be collapsed or skipped, and how strict the review should be overall.

Where To Find It

Open:

Atlas Settings
Review
Policy File

From there, Atlas shows:

a project selector
a JSON editor
starter examples you can insert
buttons to reload, load the starter, save, or reset the file

If the project does not have a policy file yet, that is normal. Atlas keeps using its built-in review behavior until you save one.

What Atlas Saves

When you save a policy from the app, Atlas writes it to:

.atlas/review-policy.json

This file is repo-owned, so it can live with the project and be shared with the rest of the team.

What The Policy Changes

The policy file affects how Atlas Review shapes and prioritizes review work for that project.

defaults changes global behavior like evidence requirements and recommendation caps.
linters controls the deterministic linter pre-pass Atlas can run before the main review.
promptAppend adds focused instructions for Atlas as a simple list of short prompts, such as asking it to treat billing or auth paths as high risk.
paths adds per-path shaping rules, for example making tests shallow, lockfiles collapsed, or generated output skipped.

Trusted Vs Local Preview

Atlas supports two ways to read the policy file for manual reviews:

Trusted base branch: use the policy from the trusted branch or PR base. This is the default.
Local working tree preview: preview policy edits that only exist in your local checkout.

Use local preview when you want to test policy changes before committing them.

Important:

manual reviews started from Atlas can preview the local working-tree policy
automatic and other authoritative review runs still use the trusted base-branch policy

That means you can safely experiment locally without changing the behavior of the review runs your team depends on.

Recommended First Edits

Most teams only need a few changes:

keep the linter pre-pass enabled when the repo already has supported tools configured
make tests shallow
mark generated output like dist or build as skip
collapse generated protobuf outputs like *.pb.go
collapse lockfiles and snapshots
push high-risk areas like auth, billing, or payments to deep
add a few short promptAppend entries for your most sensitive flows

The built-in starter examples in the app already cover these common cases:

Generated outputs
Go and protobuf-generated outputs
Tests and snapshots
Auth and payments
Migrations and config
Stack-aware defaults for Go modules and protobuf or Buf schemas when those files are present

Starter Example

{
  "version": 1,
  "defaults": {
    "requireEvidence": true,
    "allowPraise": false,
    "maxRecommendations": 8
  },
  "promptAppend": [],
  "paths": [
    {
      "glob": "**/*.test.*",
      "fileClass": "shallow",
      "promptAppend": "Review tests for correctness and regression coverage."
    },
    {
      "glob": "**/dist/**",
      "fileClass": "skip"
    },
    {
      "glob": "**/package-lock.json",
      "fileClass": "collapsed"
    },
    {
      "glob": "**/auth/**",
      "fileClass": "deep"
    }
  ]
}

Field Guide

`defaults`

Use this section to tune review behavior across the whole project.

requireEvidence: keep this on if you want findings grounded in evidence
allowPraise: usually keep this off unless you want positive callouts in reviews
maxRecommendations: caps how many recommendations Atlas should aim to return

`promptAppend`

Use this for short, high-signal guidance. Good examples:

“Treat billing and refund flows as high risk.”
“Call out missing permission checks and rollback gaps.”
“Focus on user-visible regressions, data loss, and broken migrations.”

Do not use this section for style preferences or team formatting rules. Prefer one short instruction per array item.

`linters`

This section controls the deterministic linter pre-pass that Atlas can run before the main review.

Use it to:

enable or disable linter pre-pass for the whole project
enable or disable specific tools
allow Atlas-managed fallback when a supported tool is missing from the repo

The supported linter keys are:

eslint
tsc
dotnet
dotnetFormat
semgrep

For full setup and behavior, see Linter Pre-Pass.

`paths`

This is the most useful part of the file for most teams.

Each path rule can include:

glob: which files it applies to
fileClass: how much review effort Atlas should spend there
promptAppend: extra guidance for that path

Supported fileClass values:

deep
structural
shallow
collapsed
skip

A practical mental model:

deep: high-risk source code that deserves full attention
structural: migrations, schema, and configuration where rollout or compatibility matters Protobuf contracts and Buf config usually belong here because backward compatibility matters more than implementation style.
shallow: lower-risk paths like tests where correctness matters more than style
collapsed: files Atlas should acknowledge without spending much effort on
skip: generated output and other files that should not consume review budget

Save, Reset, And Reload

Inside the app:

Load starter loads the default starter into the editor without saving it
Create starter file or Reset to starter writes the starter policy into the repo
Save policy normalizes and saves the JSON to .atlas/review-policy.json
Reload pulls the latest saved file back into the editor

Current Limits

JSON only in this release
Atlas normalizes the file when you save it
The file is optional until you decide to create it

When To Use It

Use a policy file when:

Atlas spends too much time on generated files or lockfiles
you want protobuf or RPC schema changes reviewed for compatibility while generated outputs stay collapsed
you want stricter review on auth, billing, payments, migrations, or infrastructure
you want tests reviewed for correctness without expanding into style feedback
you want a tighter cap on noisy recommendations