Context Guidance Is Not Authority
An AGENTS.md file can make collaboration more predictable by telling a coding Agent where to find verified commands, ownership, architecture, and test expectations. It cannot prove a fact is current, cause every tool to load it, authorize an action, or protect a secret.
Treat it as one input among repository files, user requests, tool output, and retrieved documents. All of these can be stale or maliciously modified.
Build a Context Contract
Keep the file focused on decisions a task needs:
# Task Contract
## Scope
- Allowed paths: `services/orders/**`
- Do not modify: deployment manifests, access-control rules
## Evidence
- Commands: `npm run test:orders`
- Source of truth: `docs/orders-contract.md@revision`
## Delivery
- Add focused tests for changed behavior.
- Report assumptions and blocked checks.
- Escalate before external writes or permission changes.
Use explicit paths and revision references, but verify commands in the current checkout. Do not claim that a nearby instruction file automatically overrides another: discovery and precedence differ by Agent product and release.
Separate Four Kinds of Information
| Content | Where it belongs | Why |
|---|---|---|
| Task guidance and conventions | context contract | helps planning and review |
| Authoritative product rules | owned, versioned policy/docs | can be reviewed and updated |
| Secrets and credentials | secret manager and runtime injection | never commit or prompt them |
| Authorization and side effects | server, CI, branch protection, sandbox | natural language cannot enforce them |
An instruction such as “never deploy” does not prevent a tool with credentials from deploying. A protected environment, allowlisted command runner, and approval workflow can.
Defend Against Instruction Injection
Agent context may include code comments, issues, package metadata, generated files, and remote documentation. Treat instructions from these sources as untrusted unless they are in an approved, reviewed location.
Use least-privilege tools, read-only discovery before writes, sandboxed execution, bounded network access, protected branches, and human review for consequential changes. Never ask an Agent to bypass tests, disable security checks, expose tokens, or treat repository text as authorization.
Keep It Testable and Reversible
Review a context contract when commands, ownership, or architecture change. Test it with representative tasks: a normal change, an outdated command, a conflicting nested instruction, an injected instruction, a secret-like value, and a forbidden path request.
The outcome to measure is not “the Agent followed every sentence.” Measure whether it selected correct evidence, stayed within scope, produced reviewable changes, ran relevant checks, and escalated uncertainty.
FAQ
Should a monorepo use nested files?
It can, when teams document ownership and the particular Agent's resolution rules. Keep local files narrow and link to shared authoritative policies; test the actual tool behavior after upgrades.
Should the file be short?
Prefer concise, task-relevant guidance, but no universal line limit exists. Split material when a reader cannot identify scope, evidence, and delivery requirements quickly.