> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fullotto.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Instructions

> Tell Otto what to look for in a repository and in specific paths.

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:

```yaml otto.yml theme={null}
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:

```yaml otto.yml theme={null}
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](/configuration/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](/automation/lifecycle).

Use `otto.yml` for review-specific rules, especially rules that only apply to some paths.

## Precedence

When guidance conflicts, the most specific source wins:

1. `otto.yml` instructions (path and repository)
2. The repository's `OTTO.md` or `CLAUDE.md`
3. Your workspace's [review instructions](/reviews/workspace-settings#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

<AccordionGroup>
  <Accordion title="Be specific and checkable">
    "Every money amount must be an integer number of cents" works better than
    "be careful with money".
  </Accordion>

  <Accordion title="Say what to skip">
    Tell Otto what your tooling already enforces ("our linter handles import
    order") so it doesn't spend findings on it.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Explain why">
    A short reason ("we deploy migrations before code") helps Otto judge edge
    cases the rule doesn't spell out.
  </Accordion>
</AccordionGroup>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.