Instructions

Instructions are plain-language guidance Otto follows while reviewing: what to focus on, conventions to enforce, and what to leave alone.

Repository instructions

reviews.instructions applies to every review of the repository:

otto.yml

version: 1
reviews:
  instructions: |
    We use Result types instead of throwing; flag any new `throw` in src/.
    Don't comment on formatting — Prettier runs in CI.

Path instructions

A path rule’s instructions apply only when the PR changes at least one file the rule matches. Otto is told which changed files the rule matched, so it applies the guidance to those files:

otto.yml

version: 1
reviews:
  paths:
    - match: ['migrations/**']
      instructions: |
        Migrations must be backward compatible with the running release:
        add columns as nullable, and never rename or drop in the same release.
    - match: ['src/api/**/*.controller.ts']
      instructions: |
        Every endpoint needs an authorization guard and request validation.

A rule can set instructions, depth, or both. See Review depth.

OTTO.md and CLAUDE.md

Otto also reads OTTO.md from the repository root, or CLAUDE.md if there’s no OTTO.md. Use it for broader context: architecture, conventions, and how the codebase fits together. Otto uses it for reviews and for ticket automation. Use otto.yml for review-specific rules, especially rules that only apply to some paths.

Precedence

When guidance conflicts, the most specific source wins:

otto.yml instructions (path and repository)
The repository’s OTTO.md or CLAUDE.md
Your workspace’s review instructions

None of these can change Otto’s review format, its P0–P3 severity scale, or how it scores merge confidence. Otto ignores any part of the instructions that tries to.

Writing good instructions

Be specific and checkable

“Every money amount must be an integer number of cents” works better than “be careful with money”.

Say what to skip

Tell Otto what your tooling already enforces (“our linter handles import order”) so it doesn’t spend findings on it.

Scope rules to paths

Guidance that only matters in one area belongs in a path rule, so it doesn’t distract reviews of unrelated code.

Explain why

A short reason (“we deploy migrations before code”) helps Otto judge edge cases the rule doesn’t spell out.

Each instructions value can be up to 4,000 characters.

​Repository instructions

​Path instructions

​OTTO.md and CLAUDE.md

​Precedence

​Writing good instructions

Repository instructions

Path instructions

OTTO.md and CLAUDE.md

Precedence

Writing good instructions