A coding agent fixing a Go service needs different instructions from one changing a release workflow. How do you organize AGENTS.md so it finds the relevant guidance while keeping repository-wide rules visible?
AGENTS.md is an open Markdown format for giving coding agents project context and instructions, now stewarded by the Agentic AI Foundation. As a repository grows, those instructions can span languages, packages, testing workflows, and deployment procedures.
My approach is to keep shared expectations in the root, make specialized guidance discoverable, and check which instructions the agent actually selects. That gives maintainers something concrete to review when a task gets the wrong guidance.
What belongs in the root file?
Start with instructions that matter across the repository: how to orient yourself, which boundaries to preserve, where authoritative guidance lives, and how to report verification accurately.
A useful test for each rule: would this still apply if the next task touched a different package or language? If yes, it probably belongs near the root. A package-specific command needs a narrower home.
Here is an illustrative root excerpt for a repository with shared contribution rules and separate package instructions:
## Repository-wide expectations
- Preserve unrelated changes and public interfaces outside the task scope.
- Read `CONTRIBUTING.md` for the shared contribution workflow.
- Read applicable package instructions before changing package code.
- Report which checks ran, which failed, and which were skipped.
The goal is a root file a maintainer can still review as a whole. A small file that omits essential guidance is a problem too. Keep enough context to explain the repository and enough direction to find the rest.
Where should specialized guidance live?
The AGENTS.md guidance for monorepos recommends nested files for subprojects, with the nearest instructions taking precedence. For a repository whose boundaries follow directories, that is a useful starting point:
AGENTS.md
services/
payments/
AGENTS.md
service.go
web/
AGENTS.md
src/
The payments file can explain service boundaries and relevant Go checks. The web file can cover frontend conventions. Check your coding agent's discovery and precedence behavior before relying on this layout.
Some guidance cuts across directories. Go conventions might apply to several services; release verification may require a procedure shared by multiple packages. Explicit links from AGENTS.md can point to that guidance without copying its contents into every package.
In my Software Standards Bootstrap project, which generates repository guidance from maintained source artifacts, I used a root file plus a routing catalog. The catalog describes when to read each supporting Markdown bundle:
AGENTS.md
.software-standards/
routing/
catalog.md
bundles/
route-<id>.md
This is a project-specific design. AGENTS.md doesn't require a catalog, generated files, or this directory layout. Use the simpler nested arrangement when it expresses your repository's boundaries clearly.
How does the agent choose the relevant guidance?
An explicit routing design needs a selection rule that a maintainer can understand and test. In this project's catalog implementation, selection considers affected paths, the task type, and languages or frameworks supported by the request and repository evidence.
A bundle qualifies when at least one path scope matches and every represented selection dimension matches. Multiple values within a dimension are alternatives. Missing information requires including potentially relevant guidance rather than silently excluding it.
For example, implementing app/service.go calls for application boundaries, Go guidance, and implementation instructions alongside shared safety rules. Verifying .github/workflows/release.yml calls for shared rules, verification guidance, and release instructions. The presence of Go elsewhere in the repository doesn't make every task a Go implementation task.
Conceptual view of the project's routing design. The catalog is an explicit instruction-selection convention; the diagram does not represent a measured execution trace.
Treat mixed tasks carefully. A change that implements a service and updates release automation may need both sets. Revisit the selection when the affected files or requested work change. Reading a linked procedure also needs to include the steps it references; stopping at an index can leave the actual instructions unread.
How do you verify that selection?
Define the expected selection before running the check. Include guidance that should be excluded, so a result that reads everything cannot pass as successful routing.
The project's September 1 evaluation record documents five requests in one Codex CLI 0.145.0 session. Two illustrate the difference:
| Task | Expected guidance | Recorded selection | Examples excluded |
|---|---|---|---|
Implement app/service.go
|
Shared safety, app boundaries, Go, implementation | Matched | Planning, verification, release |
Verify .github/workflows/release.yml
|
Shared safety, verification, release | Matched | App boundaries, Go, implementation |
The machine-readable record includes selected artifacts, excluded artifacts, and content markers observed in the selected guidance. It also records file hashes tying the result to particular generated bytes.
These are historical selection results. They do not establish behavior in another agent version, successful implementation, or token savings. The disposable fixture and raw transcript were not retained, which limits independent inspection. This article does not report a fresh reproduction.
The record also separates displayed commands from execution: go test ./... appeared in a verification recipe but did not run. A readable procedure and a passing check are different outcomes.
For your own check, retain the fixture and trace, record the agent version, and compare expected selections with observed reads. Test an ambiguous request and a task spanning multiple directories as well as the straightforward cases. An agent's summary alone is weaker evidence than an inspectable trace of what it opened.
How do you maintain the structure?
Give each instruction an authoritative home. When several files repeat the same rule, a future change can leave agents with contradictory versions. Link to shared guidance and keep package-specific details close to their owners.
Review instruction changes alongside the code they affect. A moved directory can invalidate a routing scope; a renamed script can break a documented command. Check both links and meaning.
Generated guidance adds another maintenance boundary. In this project's renderer design, source artifacts remain authoritative, and digests help detect edits to generated output. Hashes establish file identity; they cannot establish whether a rule is sensible or a selection is correct.
Start with one ordinary development task and one task with different requirements. Write down the instructions each should receive, run the selection check, and inspect the difference. That gives you a concrete reason to split a file, clarify a scope, or fix a missing link.
Top comments (0)