Writing the rules once for the AI agents: a guide with a size budget, and a gate that checks it

Our AI coding assistants read one short guide before every task. It has a size budget, module cards instead of repository searches, and a verify script that fails when the rules drift. What is in it and why it is small.

Most of the code in a modern project is touched by an assistant at some point, and an assistant starts every session knowing nothing about your project. What it reads first decides whether its change fits or has to be reviewed back into shape. In Flightpack that first read is one file, AGENTS.md, and the most deliberate thing about it is that it is short.

One guide, kept under a budget

The guide is 72 lines. Its size budget is 8 KB, and the verify script checks it. The reason is cost: the guide is loaded into every session and into every sub-assistant that session starts. A guide that grows by a paragraph a week is paid for on every task for ever. So the budget is a rule, and the check fails the build when it is broken.

What goes in it

Only what an assistant would otherwise get wrong, and what is expensive when it does:

• The non-negotiables. PostgreSQL syntax only, with the common MySQL habits named; the authorisation guard; the rule that being signed in is not authorisation; the layering line; translations that travel in pairs; and never to invent a route, column, permission or command name.
• What it may run without asking, and what it must ask first. Tests, type checks and builds run freely. Installing packages, rewriting lint fixes, migrating the real database and anything destructive need a person. Writing this down once is cheaper than answering the same prompt every day.
• How to verify. One script runs the fast gates and a quality ratchet before a task may be called done.
• How to record work. The tracker is used through a tool, never by hand, and a task that still needs a human run in a real environment is marked Done in code, not Done.

Cards instead of searches

Searching a whole repository for a keyword is how an assistant spends its budget and still misses the point. Each module has a short card under ai/context/modules: its routes, stores, views and permissions. The rule is to search the index for the module, read that one card, then read a line range of the code. A script regenerates the cards, and the end-of-session hook runs it, so a card does not quietly go stale when a route is added. The same folder holds a recipe file for the jobs that repeat: a new endpoint, a list page, a string, a permission.

A ratchet instead of a promise

An instruction is a request. A check is a fact. The quality ratchet keeps a per-file count of the things the rules forbid and allows that count to fall, never to rise. An assistant that adds a forbidden pattern fails the gate in the same session, with no review needed to catch it. When a fix lowers a count, the baseline is updated by a command that refuses to accept a rise.

Several sessions, one tree

Sessions here share a working tree, so the guide has a rule for commits: add new files by name and commit only your own paths, never reset, stash or commit everything. It reads like fussiness until two sessions edit one tree on the same afternoon.

What it does not do

• It does not replace review. A short guide makes the first draft fit better; a person still reads the diff.
• It does not guarantee obedience. That is why the rules that matter most are also checks.
• It needs maintenance. The module cards and the recipes are the parts that drift, which is why they are generated or checked.

What I would tell another small team

Related reading: how a package plugs into the core and one command to set up, one command to verify.

Write the guide your assistant reads first, and keep it small enough to load every time. Put what it must never get wrong in it, put what changes often in generated cards, and turn every rule that matters into a check. The size budget is the part people skip and the part that pays most. The layering rule it carries is explained in the architecture on one page.