GitButler Agent Rules: AGENTS.md Explained

Overview

GitButler's 42-line root file contains a repository map, a short working-style list, and two links to local instruction files.

Nested instruction files Behavioral framing Pointing at the source of truth

Documents

├── AGENTS.md — the nearest nested AGENTS.md
├── apps
│   └── lite
│       ├── 
│       └──  · symlink → AGENTS.md
└── crates
    ├── but
    │   ├── skill
    │   │   ├── 
    │   │   └──  · symlink → AGENTS.md
    │   ├── 
    │   └──  · symlink → AGENTS.md
    ├── 
    └──  · symlink → AGENTS.md

Techniques in this file

01 / Nested instruction files

A numbered precedence order

Three instruction sources are ranked in the opening lines: explicit human instructions, then the nearest nested AGENTS.md, then this file. The conflict case is answered before any rule is given.

5Apply all relevant instruction files. If instructions conflict, resolve them in6this order:7 81. Explicit human instructions92. Nearest nested `AGENTS.md`103. This file

02 / Behavioral framing

Questions treated as read-only

A question about the codebase does not imply permission to change it. The default is stated in one line at the top of the working style section.

23- Treat questions about the codebase as read-only unless the user asks for changes.

03

Reproduce before adding machinery

Reproduce a behavior bug with a failing test, then inspect existing loops and classifications for the right home. The tests determine how much implementation the fix needs.

35  hosts; let the tests, not the diagnosis, set how much implementation the fix needs.

04

Propose a new mechanism before building it

A fix requiring a new module, a new public API, or a parallel walk where one already exists is to be proposed in shape before implementation.

05

A cross-surface completion check

Before shared behavior is called done, each applicable surface is checked and either updated or explicitly determined to be unaffected. Six surfaces and docs are named.

29- Before declaring shared behavior done, check each applicable surface and contract30  (desktop, web, Lite, CLI/TUI, N-API, SDK, and docs) and update it or explicitly31  determine that it is unaffected.

Ideas for your repo

If you have nested instruction files, state the precedence order in the first paragraph.
State that a question is a question. Agents otherwise read "why does this happen" as "fix this".
List the surfaces that shared behavior has to reach, and require each to be checked or ruled out by name.