GitButler

Git client backed by Tauri, Rust and Svelte.

42 lines that open with the precedence order between instruction sources.

Documents

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

The file, explained

What makes it useful

A repo map, a working-style list and two pointers to nested instruction files. Second shortest in the directory.

Techniques in this file

Quoted passages are verbatim. Open one to see it in the source.

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.

Source excerpt starting at line 5.
Apply all relevant instruction files. If instructions conflict, resolve them inthis order: 1. Explicit human instructions2. Nearest nested `AGENTS.md`3. 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.

Source excerpt starting at line 23.
- Treat questions about the codebase as read-only unless the user asks for changes.

03 / From this file

Reproduce before adding machinery

A behavior bug is to be reproduced in a failing test first, and the existing loops and classifications in the target file surveyed as candidate homes for the fix. The tests, rather than the diagnosis, are named as what sets how much implementation the fix needs.

Source excerpt starting at line 35.
  hosts; let the tests, not the diagnosis, set how much implementation the fix needs.

04 / From this file

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 / From this file

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.

Source excerpt starting at line 29.
- Before declaring shared behavior done, check each applicable surface and contract  (desktop, web, Lite, CLI/TUI, N-API, SDK, and docs) and update it or explicitly  determine that it is unaffected.

Put it to work

Borrow this for your repo

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

How the file is organized

  1. 01Precedence
  2. 02Repo Map
  3. 03Working Style
  4. 04Scoped Instructions
Read this revision on GitHub ↗

Context your instructions cannot carry

GitButler's file tells an agent how the codebase works. It cannot tell it which bug three customers hit this week. Modem keeps that context current and attaches it to the work.

Try Modem