Agent Instruction Files

An instruction file carries only what an agent must know before opening any file. Everything that explains a specific line belongs next to that line.

Why It Accumulates

Writing to the instruction file is always the cheaper move. The right comment location has to be found; the instruction file is a single known path that appends cleanly and never conflicts with surrounding code. Any agent will take that path, and nothing pushes back — type checkers and dead-code tools catch unused symbols, never a repeated paragraph.

The cost arrives later. A duplicated explanation has two copies and only one of them moves when the code moves, so the instruction file drifts first — usually into a wrong path or a renamed symbol. A nearby comment is easier to update alongside the code, but can still drift; verify its accuracy rather than assuming proximity makes it current.

Apply the Placement Test

First check whether the paragraph is accurate, necessary, and adds guidance the model would otherwise lack. Remove obsolete, duplicate, or unhelpful advice with a reason; do not relocate it merely to preserve its words. Keep unresolved policy questions in place until clarified. For useful content, answer three yes/no questions about the paragraph.

1. Is there a single file that could carry this as a comment, and would an agent open that file while doing the work the paragraph concerns? Both halves must hold to answer yes. Answer no when no single file owns the fact, when the agent needs it before it knows which file to open, or when the owning file cannot carry a comment at all — a lockfile, a manifest without comment syntax, a generated artifact, a binary.
2. Is it a prohibition rather than an explanation? "Never translate between protocols" is a prohibition: an agent must know it before choosing an approach, and choosing an approach happens before any file is opened. "This request is form-encoded because the endpoint rejects JSON" is an explanation.
3. Does seeing it require two or more files? Directory conventions, cross-module invariants, dispatch maps, and the testing strategy qualify. Anything visible in one file does not.

Then apply the answers directly: