⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
Maintaining AGENTS.md
Each line of an AGENTS.md costs tokens on every task in its folder, and an agent does not question
a wrong line. So these files contain only what an agent would get wrong without them.
How the files are loaded
- Claude Code reads
CLAUDE.md. EachCLAUDE.mdhere contains only the line@AGENTS.md, which imports theAGENTS.mdbeside it. Put rules inAGENTS.md. A newAGENTS.mdneeds thisCLAUDE.mdin the same change. - Claude Code loads the root file at session start. It loads an area file on the first read, write or edit of a file in that folder.
- Codex reads
AGENTS.mdfiles at session start, from the repository root down to the working directory. A session started at the root gets an area file only through the root rule that says to read it, so keep that rule.
Where a fact goes
| Fact | Place |
|---|---|
| A rule the code does not show, that most tasks there need | the nearest AGENTS.md |
| A rule a tool can check | the tool: ESLint, tsc, a test, CI |
| How a feature works, a walkthrough, a design reason | docs/dev/<topic>.md |
| A rule for one topic only | that doc, plus one routing row |
| Steps for a rare procedure | docs/dev/<topic>.md |
| A workflow an agent runs by name | .agents/skills/ |
| Why one line of code looks wrong | a comment on that line |
| An extension point for the Pro build | SEAMS.md in the private Pro repository |
| A fix, a feature, what changed | the commit message |
The routing row goes in the Docs table of the root AGENTS.md, or in the area file when only that
area needs the doc.
Test for a new line
Add a line only when every answer is yes:
- Would an agent get this wrong without the line? Try it, or point to the mistake it made.
- Is it invisible in the code? If a neighbouring file shows the pattern, leave it out.
- Can no tool check it? If one can, add the check and leave the line out.
- Do most tasks in this folder need it? If not, it goes in a doc.
- Does breaking it cost data, security, a failed deploy or a release?
When to update
Update in the same change when:
- a rule changes or stops being true;
- a file, function or command named in an
AGENTS.mdis renamed or removed; - agents made the same mistake twice and the test above passes.
Do not update when:
- you fixed a bug, added a route, a table, a setting or a feature;
- a refactor kept the rules;
- an agent offers to record what it learned;
- a command such as
/initgenerated the text.
Format
- One rule per bullet, at most three lines, in the imperative.
- Name the file, function or command.
- Give the reason in one clause when it stops a workaround.
<!-- Good -->
- Never add `image:` to `docker-compose.coolify.yml`: with both `image:` and `build:` Coolify still
builds and stops making rollback images.
<!-- Bad: describes the design and states no rule -->
`socialProviders.google` is a factory that returns the module-level `googleOptions` object.
better-auth builds the provider list once, but the provider keeps that object...
<!-- Bad: records one change -->
`0152_agent_execution_state.sql` adds the current execution marker to `agent_run`.
<!-- Bad: ESLint already fails this -->
Every language carries every key of `messages/en`.
Limits
scripts/agents-md.test.ts runs in CI on every pull request, and a failure blocks the merge. It
reads every tracked AGENTS.md and fails when:
- the file is over 10,000 bytes;
- a backticked path does not exist.
The path check covers file names with a common extension and paths under apps/, packages/,
docs/, scripts/, charts/ and .github/. It skips brace and wildcard forms and paths such as
.agents/skills/. A reference also passes when any tracked path ends with it, so after a rename
search for the old name by hand.
Over the limit, remove a line. Do not raise the limit. Claude Code loads an area file whole. Codex
cuts the combined text of the files from the repository root to the working directory at 32 KiB
(project_doc_max_bytes) and adds no marker. Two files at the limit stay under that cut.
No check covers the format rules or the CLAUDE.md files.
Reviewing a change to AGENTS.md
A change to an AGENTS.md affects every later agent task in that folder. Ask for the mistake the
line prevents. Reject a line that fails the test above, and move a good explanation to docs/dev/.
Measuring a change
For a large rewrite, compare old and new on a set of task-like questions in clean copies of the
repository, one copy per version, with a control copy that has no AGENTS.md. Compare correct
answers, tokens and turns. A rule that the control gets right is a candidate for removal.