Who it's for
Engineers who want agents to work the way their team works.
You'll be able to
Split what an agent needs to know into a short rules file, guides, folder rules and a notes file.
An agent starts every session knowing nothing about your repository. What it reads first decides how it works.
A short rules file at the top
Put one rules file, AGENTS.md, at the top of the repository. The AI tools the factory works with all read it, so there is no second rules file for each tool.
It holds the rules that apply everywhere: a map of the folders, who decides what, how work moves from spec to merge, what an agent must never do, and what to do when stuck. Each rule is one or two lines. For example:
## When stuck
After three failed attempts at the same problem, stop and hand over to a person with what you tried.
Keep the rules file short and put the detail in guides. A long rules file is not read.
The factory sets a target of at most 150 lines for it.
Guides hold the detail
A guide covers one topic: how we work, the gate, the checkers, data rules, adding a tool, recording progress. A rule in the rules file is one line that points to its guide: "Run the gate before you say a task is done", then the guide's name. One short index page lists the guides and says where to start.
Guides are for people and agents alike. Treat them like code: someone follows a guide to the letter, and the gate says whether it was right. Reading a guide against the folders can miss a step that doing it finds at once.
Rules for one folder
A folder with its own rules gets its own AGENTS.md. It starts by saying it adds to the file at the top, then lists only what is true in that folder. A frontend file might say:
- A page holds little: it calls the logic and shows components.
- A component gets what it shows as props and does not fetch.
- Only one settings file reads the environment.
The backend file says where logic goes and what a route may do. The top file keeps the rules that apply everywhere, so neither grows long.
A notes file for what you learned the hard way
Keep one notes file of gotchas: newest first, one or two lines each. The rules file tells the agent to read it before starting and to add to it when something bites. One entry: a version in a YAML tool list must be in quotes, because without them 3.10 is read as the number 3.1.
| What | Where | Size |
|---|---|---|
| Rules for everywhere | AGENTS.md at the top | Short, one line per rule |
| Rules for one folder | That folder's AGENTS.md | A few lines |
| How to do a job | A guide | As long as the job needs |
| Lessons learned the hard way | The notes file | One or two lines each |
Try it
In your own repository:
- Open your rules file, or write one. Move every rule longer than two lines into a guide, and leave a one-line pointer.
- Pick the folder agents get wrong most often. Give it its own rules file with three rules.
- Start a notes file with the last thing that cost you an hour.