For AI agents: this page as Markdown · llms.txt · JSON Schema

#Writing rules for your repository

A Rerail rule checks a coding agent's work as it goes. When the work breaks a rule, Rerail tells the agent in the session ("steers" it), and the agent fixes it.

Start with /rerail-create in your coding agent ($rerail-create in Codex):

The agent tests each draft, reads it back, and adds it only after you say yes.

#Which rules are worth having

Rules from your repo's own conventions pay off; generic style rules do not.

A rule is worth writing when:

• you have corrected the agent on it, or written it down as a standard;
• the repo already follows it almost everywhere;
• following the steer can never break working code;
• nothing else (a linter, formatter or type-checker) enforces it.

Suggesting rules has the full scoring.

#Evidence from your sessions

rerail rules evidence lists what Rerail recorded for the repository that could become rules. It changes nothing.

rerail rules evidence [--repo <dir>] [--days <n>] [--limit <n>] [--json]

● acme-web: 42 sessions in the last 30 days (claude-code 30, codex 12), 310 prompts.
  Corrections: 9.
    2026-10-12 claude-code [standing instruction] Don't use console.log, we use the logger in src/log.ts
      after: Edit src/api/orders.ts
  Risky commands:
    force push ×2  git push --force origin feature/x
  Steers by rule:
    n-no-sync ×12
  Standards files: AGENTS.md, CONTRIBUTING.md, eslint.config.js

#Two kinds of rule

Code rules check the files the agent edits; command rules check the commands it runs.

• A code rule is a rerail.policy/v1 document: globs for scope, clauses that match text, paths or syntax.
• A command rule is a conversation rule that matches input.command.

Guides:

• Writing a code rule
• Writing path and text rules: text and paths in any file
• Architecture rule examples: rules that hold a design in place
• Writing a command rule
• tool-call-rules.md: regex technique for command rules

#Testing a draft

A draft is the rule plus the cases it must catch and pass; test it before adding it.

rerail rules test and rerail rules add read this envelope, not the bare rule. rerail rules test --help prints it.

{
  "kind": "code",
  "rule": { "format": "rerail.policy/v1", "id": "local:…", "revision": 1, "mode": "steer", "description": "…", "scope": { "include": ["…"], "exclude": [] }, "clauses": ["…"] },
  "cases": {
    "caught": [{ "path": "src/a.ts", "content": "…" }],
    "passed": [{ "path": "src/a.ts", "content": "…" }]
  }
}

Writing path and text rules has complete drafts to start from.

rerail rules test draft.json            # validate, run the cases, list the matches across the repo; writes nothing
rerail rules test draft.json --json     # the same, listing every match and every file the rule could not check
rerail rules add draft.json             # store it in your library and add it, on, to this repo
rerail rules approve <id>               # after reading it: it steers instead of running in Log
rerail rules export --output rules.json # your rules, to read or edit one

Before adding a draft, check:

• Cases. All pass, including a near miss: code that looks like a violation but is not.
• Repo matches. Each is a real violation, and there are a handful, not hundreds. Hundreds mean the repo's convention says otherwise.
• Message. Following it cannot break working code.

Rule quality has the gates, the five kinds of harmful steering, and the fix ladder for a misfiring rule.

#Steer or Log

A rule's mode decides whether the agent hears about a violation.

• Steer (steer) tells the agent in the session. Use it when you are sure of the rule.
• Log (log) records it and tells no one. Use it on trial, or when existing code breaks it too often.

A rule from /rerail-create is never block. It belongs to the repository it was made in, unless you keep it to one worktree.

#Approving a rule

A rule you add with rerail rules add, or an agent writes, runs in Log until a person approves its message.

Say yes to /rerail-create after its read-back, or approve on the rule's page in the dashboard. An edit needs approval again.

#A rule for one worktree only

A JSON file in the worktree's .rerail/rules/ folder is a rule that runs in that worktree only.

Use it for a branch experiment, a migration in progress, or a convention on trial. Each file holds one rule document (the draft's rule, without the cases).

feature/                  a linked worktree of the repository
└── .rerail/
    └── rules/
        ├── no-legacy-client.json
        └── use-new-logger.json

Keep the folder out of Git unless you mean to share it: add .rerail/rules/ to .git/info/exclude.

This worktree's own rules, in /src/acme-web-feature/.rerail/rules (pack worktree, here only): 2
  Not running: this repo is not set up yet, so no rule runs here. `rerail start` sets it up.
  local:no-legacy-client (code, steer)
    waiting for approval, runs in Log until then: rerail rules approve local:no-legacy-client
  local:use-new-logger (code, log)
  left out: draft.json: clauses Too small: expected array to have >=1 items

A worktree's own rules has every check Rerail makes.