AI Agent Context

AI agents follow the same enforced rules as humans. A context file gives an agent just enough to be useful — how to build, test and lint, a short architecture summary, the non-negotiables, and links to the real standards, never copies of them.

The files

AGENTS.md holds the content. CLAUDE.md beside it is a two-line pointer. AGENTS.md is the cross-tool convention and we run more than one tool; a committed pointer file — never a symlink, we are a Windows shop — keeps every tool reading one source.

One AGENTS.md per build unit — any directory with its own build, test and lint commands — plus one at the repo root.

AGENTS.md              ← true for every stack: layout, commits, i18n, doc map
CLAUDE.md              ← two-line pointer
backend/AGENTS.md      ← .NET rules; wins inside backend/
frontend/AGENTS.md     ← Angular rules; wins inside frontend/
mobile/android/AGENTS.md
mobile/ios/AGENTS.md

A single-stack repo therefore has exactly one file. The nesting is load-bearing: without it, an agent working on a Swift screen reads four stacks of irrelevant rules on every task.

Precedence, when sources disagree: enforced CI and linter config → the repo’s ADRs → the repo’s AGENTS.md → this wiki. The wiki is the default; the repo is the authority for that repo.

What goes in

Section	Content
Commands	Build, test, lint — exactly as run, from the right directory
Architecture	A short summary. A topology sketch beats a paragraph
Non-negotiables	≤6 lines. Each names the safety mechanism it protects and the code that enforces it
What goes where	A table mapping “you want to add X” → the directory. This is the question agents most often get wrong
Links	To this wiki, to /docs/adr, to the committed config

It does not restate the linter, the branching model, or an ADR — it links to them, so there is one source of truth.

Budget

150 lines per file. CI fails the build over 200. One wc -l step — the same kind of gate as any linter, because “keep it short” without a number is not a rule.

Over budget means a rule belongs in config, in a test, or behind a link. Escape hatch: a documented override of a third-party agent skill, which has to be version-anchored and therefore verbose. Name it as such in the file.

A rule earns a line only if it names the incident that caused it or the check that enforces it. Generic prompting — “think first”, “keep it simple” — is already in the model. It costs budget and changes nothing.

Keep it true

Treat every claim in an AGENTS.md as a hypothesis, not a fact. When the code and the file disagree, the code wins and the file gets fixed in the same PR.

Re-verify each file against source at least twice a year. This is not theoretical: an audit of one of our repos checked its context file claim by claim and found seven materially false statements — behaviour described that the code did not implement, and a helper documented as live that was never called. Agents had been reasoning from all seven, because an agent does not doubt its instructions. The file was corrected the same day and the audit table kept. That loop is the standard: verify, correct, keep the receipt.

Reviewing AI-authored code

• The person who opened the PR authored the code. “The agent wrote it” is not a review answer — if you cannot explain a line, delete it before you push.
• AI reviewers comment; they never approve. A human reviewer of record is required on every PR no matter how many bots have commented.
• One AI reviewer per repo. Additional bots produce contradictory advice and a review nobody reads.

Where a human must drive

Agent drives	Human drives, agent assists
Features, tests, refactors, docs, migrations you will review line by line	Auth, permissions, and crypto
Boilerplate, mechanical renames, translation keys	Release and signing config, pipeline secrets
Investigation and code reading	Anything already logged as a known issue in the repo

In the right column an agent may propose a diff; a named human owns the merge.

Secrets and dependencies

• Never paste a secret, a customer record, or production data into an agent prompt or an AI tool’s config. Keys come from the pipeline’s secret store. Disabling a pipeline does not remove a key from git history.
• Agents run against local or seeded data. If a task needs production data to reproduce, it needs a human and a ticket.
• Third-party agent skills are dependencies. Pin the source and a content hash in a committed lock file, and review a hash change like any other dependency bump — an unpinned skill can silently instruct an agent to use an API your framework version does not have.

Tip

If an instruction in AGENTS.md could be enforced by the linter or a test instead, move it there. Prose guidance is a last resort.

See also: Examples · ADRs · Engineering Standards.