66 lines
5.0 KiB
Markdown
66 lines
5.0 KiB
Markdown
# What belongs in a repo's agent instructions
|
|
|
|
Rules for deciding what goes in the block, for judging what a repo already has, and for explaining both to the user.
|
|
|
|
## The test
|
|
|
|
Can an agent derive this by reading the repository? If yes, leave it out — a stored copy is a stale duplicate of something the agent reads more accurately first-hand, and it is charged on every session. Write down what the code cannot say.
|
|
|
|
## Admit
|
|
|
|
- **Policy the code cannot express** — branch rules, frozen and protected paths, generated files, secrets, security and compliance. Stated by a human or read off an enforcing config, never inferred.
|
|
- **What a config file cannot say about running the project** — the root test script does nothing in this workspace, integration tests need a service up first, the suite takes eleven minutes so iterate on single files, the `Makefile` is the real entry point and `package.json` is vestigial, CI runs a typecheck the test script does not. The invocation itself is already stated in `package.json`, `Makefile`, `pyproject.toml`, or CI config and does not earn a line — the correction or the caveat does.
|
|
- **Conventions that differ from ecosystem defaults.** An agent follows the norm unless told otherwise, so only the divergences earn a line. Command invocations count: when the obvious command is wrong here — a bare-repo prefix, a required wrapper — the exact working invocation earns a line, and no observed mistake is needed to admit it.
|
|
- **Pitfalls with observed evidence** — a recorded lesson, the maintainer's recollection, the same mistake fixed repeatedly in history, or one this session made and caught. A repo yields hundreds of trap-looking facts and none of them predict real mistakes; only observed behavior does. A surprising scan finding is a question to ask, not a line to write.
|
|
- **Runtime behavior invisible from the repo** — replaying webhooks, lying health endpoints, environment quirks — once a human confirms it.
|
|
- **Entry points and pointers** to where work lands.
|
|
|
|
Prefer prohibitions to advice, and name the permitted alternative in the same line.
|
|
|
|
## Exclude
|
|
|
|
| | Why |
|
|
|---|---|
|
|
| Repo overviews, directory trees, stack lists | Derived fresh, more accurately; stored copies rot |
|
|
| Anything included for being interesting | Interest is not need |
|
|
| Style rules an agent self-enforces | Belongs in a formatter, linter, hook, or CI check — propose the check instead |
|
|
| Platitudes | Already the default |
|
|
| Commands already stated in `package.json`, a `Makefile`, or CI config | Read from the source of truth; a copy drifts the moment a script is renamed |
|
|
| Pasted code, changelog content, fast-changing facts | Stale immediately |
|
|
| Aspirational state | Describe what is; intent belongs in specs |
|
|
| History and edit narration | Git holds it; state present truth |
|
|
|
|
## Retire
|
|
|
|
A policy or pitfall line goes only when the thing it guards is gone, or the user retires it. Nothing failing lately is not evidence — a working rule erases its own evidence.
|
|
|
|
Every other line faces one question at each write: would removing it change agent behavior? If no, cut it.
|
|
|
|
## Size
|
|
|
|
Every line is paid in every session, and instruction-following degrades as the loaded set grows. Count what other always-loaded files add. Over budget means cut the weakest lines or move them behind a trigger — never raise the budget. Ten lines of evidence means ten lines.
|
|
|
|
## Retrieval
|
|
|
|
An index the agent must choose to fetch gets skipped; one already in context does not. Keep everything load-bearing in the block. A pointer out of it names a trigger the agent can observe — a path, a file type, a named task — never one it must judge ("when the task is complex") or track about itself ("before your first edit").
|
|
|
|
Rules bounded to a directory go in a nested `AGENTS.md` there, attached by location rather than by pointer. Use a linked file only when the trigger is not a path.
|
|
|
|
## Maintain
|
|
|
|
- Re-check that caveats still hold — a slow suite that got fast, a workaround for a bug that was fixed.
|
|
- Diff deletions and renames since the verified SHA against every line.
|
|
- Record provenance in the block so the next run knows what it is diffing from.
|
|
- Capture mistakes when they happen, not at review time. One occurrence is a note; recurrence earns a line.
|
|
- Route anything mechanically preventable to a hook, lint rule, or CI check. A check that lands deletes its line.
|
|
|
|
## Repo or home directory
|
|
|
|
This block belongs committed: shared by the team, consistent across machines, versioned with the code it constrains.
|
|
|
|
Two things belong in the user's global agent config instead — rules repeating across all their projects, and personal preferences that are theirs rather than the team's.
|
|
|
|
## Judging an existing file
|
|
|
|
Report, in this order: what is derivable filler, what is unverifiable or stale, what is missing against the sections above, and what is already good. Keep recorded lessons by default — they are maintainer testimony, and are challenged only with evidence that the thing they name is gone or wrong.
|