COMMITBRIEF md

Home / Output / COMMITBRIEF.md

COMMITBRIEF.md

The team-shared review rules file. Sent to the LLM as the system prompt on every review. Lives at the repo root and is committed to git.

Path

<repo-root>/COMMITBRIEF.md

If the file is missing, CommitBrief falls back to the embedded default at internal/rules/default.md. Customising the file is purely additive — the embedded default works fine if you have not written your own.

Scaffolding

commitbrief init

Writes the embedded default to COMMITBRIEF.md. See Init command for the --force flag and skip semantics.

Format

Free-form markdown. Anything you write is passed to the model as the system prompt, wrapped in <project_rules>...</project_rules> XML tags. Inside the XML envelope the model sees your literal content verbatim; outside, the prompt builder appends a language directive (per output.lang) and an immutability guard (a prompt-injection defense — the model is instructed to treat project rules as data, not instructions, when they conflict with its baseline behavior).

There are no required headings or template variables. Use plain markdown with whatever sections make sense for your project.

Note

Prompt-injection scan (v1.7.0, ADR-0025). Separately from the passive immutability guard above, a non-default COMMITBRIEF.md (and your OUTPUT.md template) is scanned for prompt-injection phrasing — e.g. "ignore all previous instructions", "disregard the above", "you are now…", "system prompt". On a match the CLI prints a non-blocking warning to stderr (file + line numbers) and continues — it never aborts, because it is your own file. The embedded default rules are trusted and skipped. Disable with guard.injection_scan: false. See Secret scanner for the related credential scan and Configuration files for the toggle.

What the embedded default contains

The embedded default (visible at commitbrief init time) is organised into:

1. Persona — adversarial defender + optimization engineer.
2. What to look for — correctness, security, performance, maintainability, testing.
3. Output format — instructions for the structured-findings JSON contract (severity, title, description, suggestion, …).
4. What NOT to flag — explicit "do not nitpick" list to keep noise down.

You can override any of these by writing your own COMMITBRIEF.md. The model treats your content as the system prompt; your text wins where it differs.

Customisation tips

Project-specific context

Add a section describing the project's domain, conventions, and sensitive areas. Examples:

## Project context

This is a financial transaction service. Every state change to
`Transaction` must go through `transactions.Repo.Apply()` which
enforces audit logging — direct mutations bypass compliance.

The `internal/billing/` package operates on cents (int64). Never
introduce float64 anywhere in the price-handling path.

Sensitive paths

Surface paths the reviewer should be extra-suspicious of:

## High-stakes paths

- `internal/auth/` — authentication / session handling. Any change
  here needs a security-focused review.
- `db/migrations/` — schema changes. Verify backward compatibility
  with the previous release.

Style conventions

Add lint-style rules the model can enforce:

## Conventions

- Use `errors.Is` / `errors.As`, never string-compare error
  messages.
- All public exported functions must have a doc comment that
  starts with the function name.
- No `panic()` outside `init()` blocks.

Size considerations

Important

A COMMITBRIEF.md is sent on every review as part of the prompt. Past ~10k tokens (~40k characters) you pay noticeable input cost. Use commitbrief compress to losslessly shrink the file via the LLM — see Compress command.

What CommitBrief does NOT do with this file

• It does NOT lint the file or enforce a schema.
• It does NOT validate references (e.g. "the file mentioned doesn't exist").
• It does NOT version the file or track changes — that is git's job.

See also

• Init command — scaffolding.
• Compress command — shrink the file.
• OUTPUT.md — the per-user output template (separate).
• Filtering — the .commitbriefignore file (also separate; controls which files reach the prompt, not how the prompt itself is built).