Writing AGENTS.md

Keep agent instruction files lean enough that every rule in them binds.

Physics: resident context

An AGENTS.md or CLAUDE.md (COPILOT.md, .cursorrules — any harness instruction file) is not documentation. It is a fragment of the system prompt: the harness injects it verbatim into every session, before the task is known, and it never unloads. A skill loads on demand; this file is resident. Three consequences govern everything below:

• Every line taxes every task. A rule relevant to 5% of sessions spends attention in the other 95%.
• Rules dilute each other. Instruction-following is a budget: the more rules resident, the weaker each one binds. A bloated file doesn't enforce more — it enforces less, and the critical rule drowns in the noise.
• The reader is a frontier model. It already knows git, testing, the language's idioms, and general best practice, and it can read the codebase. It needs decisions, not knowledge, and it parses a crisp rule without an example.

The file that survives these constraints is a delta: the difference between stock agent behavior and what this project needs. Everything that isn't delta is rent paid for nothing.

The rent test

Run on every line written, kept, or proposed. A line stays only if all three hold; a line that fails is deleted or relocated, never softened.