Repository instructions for agents

The instruction file is loaded into every session, whether or not it is relevant. That makes it the most expensive text in the repository, and the rule that follows from it: every line must change what an agent does.

1. Write the hazards, not the tour

An agent can read the code. It cannot know what happened the last time someone ran the obvious command.

The test for a line: would a competent engineer get this wrong on their first day, in a way the code does not warn them about? If not, cut it. Architecture descriptions, folder tours and stack lists are re-derivable in seconds and consume the budget that the hazards need.

2. Every prohibition carries its consequence

"Never run npm run build directly" gets optimised away by a reader who has a good reason and no information. "Never run npm run build directly — it bakes .env.local localhost URLs into the production bundle, silently" does not, because now the reader can see what they would be trading.

The consequence is also what lets an agent reason about the edge case you did not anticipate. A rule with no reason is only ever followed literally.

3. State defaults out loud, especially inverted ones

Anything where the safe option is not what happens by default deserves its own line, in plain language, including which way round it is:

deploy.sh defaults to production. scripts/* default to staging. They are opposite, and the mismatch has shipped the wrong build.

A rule that contradicts intuition needs restating more than a rule that agrees with it.

4. Keep it short enough to be read whole

A long file is skimmed, and skimming defeats the purpose. Aim for something a person would read in full before starting work.

When it grows, the answer is not smaller fonts — it is moving material out:

• Standing facts and hazards stay in the instruction file. Always loaded.
• Task procedures move to a skill, loaded only when that task comes up. "How to review content", "how to author a lesson", "how to cut a release" are skills. "Never deploy from a stale worktree" is an instruction.
• Reference material moves to a doc, with a one-line pointer from the instruction file saying when to read it.

The pointer matters: read Docs/branching.md before you deploy or cut a branch is a line that earns its place, because it fires at the right moment.

5. Stale instructions are worse than none

An instruction file is trusted. When it is wrong, it produces confident wrong work, and the error is hard to find because the agent is doing exactly what it was told.

• Put a date on anything time-sensitive, and write dates absolutely. "Since 2026-09-12, production deploys are manual" stays true; "recently" does not.
• When a rule changes, edit the file in the same commit as the change. A follow-up commit does not happen.
• Delete rules whose hazard no longer exists. A guard now enforced in CI does not need a paragraph; one line saying the guard exists is enough.
• Periodically check each claim against the repo. Named scripts, flags and paths are the things that rot first.

6. Where the file lives, and how many

• One per repository at the root, named whatever the tools in use expect. If several agents are used, keep one canonical file and have the others point to it or mirror it — two drifting copies is worse than one imperfect file.
• Subdirectory files for genuinely separate concerns in a monorepo, kept short.
• Never put credentials, tokens or customer data in it. It is committed, it is read by tooling, and it is quoted back in transcripts. Say "ask the owner" and name what is needed.

7. Descriptions are triggers, not summaries

For any skill you factor out, the description is the only thing read when deciding whether to load it. Write the situations, in the words that will appear in a request:

Bad:  Documentation for our content review process.

Good: Audit course content for a year level or path, produce ranked findings,
      and drive fixes through dry-run scripts. Use for any request to review,
      audit, check or find gaps in content, decks, questions or exams.

Name the verbs and the nouns a person would actually use. A skill that never triggers is worth nothing however good its body is.

8. Test it by starting fresh

The only real check. Open a new session with no context and ask for something the file is supposed to govern.

• Did it take the safe path without being told?
• Did it look for the thing the file says exists?
• Did it repeat a mistake the file was written to prevent? Then the line is missing, buried, or too polite. Sharpen it and put it higher.

When an agent makes the same mistake twice, that is not an agent problem. It is a missing or weak line, and the fix belongs in the file — that is how the file grows honestly.

9. The instruction file is a record of scar tissue

Its best form is a list of things that have actually gone wrong, each with what to do instead. It reads oddly to a newcomer — a strange mix of the specific and the severe — and that is correct. It is not documentation. It is the set of things that cost someone a day.

Checklist

• Every line changes what an agent does; tours and stack lists removed
• Every prohibition states its consequence
• Inverted or surprising defaults stated explicitly
• Short enough to read whole; procedures moved to skills, reference to docs
• Pointers to docs say when to read them
• Dates absolute; rules updated in the same commit as the change
• Obsolete rules deleted; named paths and flags verified against the repo
• One canonical file; no credentials
• Skill descriptions written as triggers, in the requester's words
• Tested from a fresh session; repeated mistakes turned into new lines