Write an AGENTS.md that earns its place in the context

On 17 October, Reddit user No-Friendship-1586 reported repeated large test runs despite adding instructions to AGENTS.md and other files. A reply asked whether the intended file was loaded at all. Without a repository or command log, the cause remains unknown. Adding another reminder would leave that question unanswered. ^[1]

Keep repository instructions focused on recurring project facts the agent cannot reliably infer: working commands, important boundaries and authoritative examples. Add a rule for a specific mistake, and verify that the running client receives it.

That is our proposed editing rule, not a claim that a particular file length improves every model. The AGENTS.md format deliberately leaves the headings to the project. It supplies a predictable home for build instructions, tests and conventions, rather than a required template with sections to fill. ^[2]

The practical problem is deciding what deserves to be there. A generated repository tour can look comprehensive while omitting the one fact that stops a migration from damaging an existing customer workflow.

Start with the next expensive mistake

Consider a hypothetical subscription service. It has a web package, a billing worker and generated API clients. An agent regularly edits the generated client instead of its schema. It also runs a root test command that never exercises the billing package. Those two mistakes justify instructions. A paragraph announcing that the project uses TypeScript probably does not.

Write the instruction at the point where it changes the decision:

API clients under packages/client/generated are generated output.
Change api/schema.yaml, then run the existing generate:client script.
For billing behavior, run the billing package's documented test command.
The root smoke test does not cover billing retries.

These paths and commands are illustrative, not instructions tested against a real repository. In your own file, verify that the generator exists, that it runs from the stated directory and that the test command selects the expected suite. Otherwise the instruction merely gives an incorrect command more authority.

GitHub's repository-instruction guidance explicitly calls for validating build commands and documenting their prerequisites. That is a stronger standard than copying commands out of an old README. ^[3]

Separate permanent knowledge from this week's task

The root file should remain useful after the current ticket closes. “Use integer minor units for stored amounts” may belong there if it is a genuine project invariant. “Add the annual discount to the checkout screen” belongs in the task. A half-finished implementation belongs in a handoff note.

This table is a NO FEED organization proposal. Claude Code's own guidance makes a similar distinction between always-relevant project instructions, path-scoped rules and procedures loaded as skills. ^[4]

A pointer needs a reason to follow it. “See docs” tells the agent almost nothing. “Before changing invoice rounding, read docs/billing/rounding.md; it defines settlement behavior” connects the file to a decision. Prefer a stable path and symbol over a copied code block that will drift after the next refactor.

HumanLayer's Kyle describes using a root CLAUDE.md of fewer than sixty lines and linking to focused documents. That is an attributed team's practice, not evidence that sixty lines is an optimum. Its useful contribution is the maintenance idea: keep the detailed explanation with its owner. ^[5]

Verify which file the harness actually loads

AGENTS.md and CLAUDE.md are not interchangeable configuration files in every tool. As documented on 19 October 2026, Claude Code's default AGENTS.md selection depends on whether CLAUDE.md or CLAUDE.local.md files exist in the working directory or its ancestors. Its documentation also describes settings that change this choice. ^[4]

Do not maintain two full copies and assume that editing either updates the running agent. Choose one maintained source, use a documented import or supported configuration where appropriate, and inspect the loaded files in the actual client. Claude Code documents /context for this inspection. GitHub, meanwhile, documents separate repository-wide, path-specific and agent-instruction mechanisms. ^[3]

Our September upgrade analysis^[6] covers the historical consequences of instructions that never load. Here the decision is narrower: maintain a small, useful contract once loading is established. Do not import a version-specific workaround indefinitely because an older article mentioned it.

Make boundaries observable

“Never break billing” is an aspiration. “Preserve the public invoice identifier; the importer fixture covers an existing customer's export” names a behavior and a place to check it. The agent can use that information to investigate an unfamiliar change, and a reviewer can challenge its result.

Instruction text is not an access control. Claude's documentation distinguishes behavioral guidance from enforced settings. If a task must not write to a production system, configure the available credentials and tools accordingly; do not rely on a sentence in a Markdown file to remove a capability. ^[4]

Avoid turning that distinction into a hundred prohibitions. For the hypothetical billing repository, a focused instruction could identify generated files, the stable export contract and the approved development dataset. It does not need to narrate every possible destructive command. Put enforceable restrictions in the appropriate environment controls and keep explanatory context close to the affected work.

Review the file through an actual task

Our proposed review is simple: take a recent task that required repeated corrections and replay its setup, without publishing changes. Ask the agent to identify the relevant instructions, locate the authoritative example and select the check that covers the intended behavior. Inspect those selections before deciding that more prose is needed.

If it chooses the wrong suite, improve the testing instruction. If it locates the correct rule but violates it, adding another identical sentence is unlikely to resolve the underlying problem; investigate the task, conflicting context and enforcement. If it spends time reading irrelevant architecture, move that detail out of the always-loaded file.

Maintain the instruction alongside the change that invalidates it. A renamed package, replaced generator or retired deployment path is also a documentation edit. Give each unusual rule a short rationale so the next maintainer knows whether to update it or delete it.

For your next instruction-file edit, name one repeated mistake and the exact line intended to prevent it. Verify the command or reference in that line, then remove one stale rule. That produces a reviewable improvement without pretending the file can guarantee agent behavior.