Agent docs hygiene: route rules to the right scope

Agent instructions fail when the right rule lives at the wrong scope. A giant root guide hides local constraints in unrelated detail. A missing package guide lets an agent choose the wrong command, ownership boundary, or release step. Both failures repeat because every new task starts from the same routing mistake.

An AGENTS.md file is a Markdown instruction file for a coding agent. Codex loads AGENTS.md files by scope: global defaults, repository rules, and the files on the path from the project root to the working directory. Guidance closer to the work can refine broader policy with constraints owned by that boundary.

That search path supports a small documentation system: the root routes, scoped guides decide, and two checks cover declared boundaries and file shape. The checks cannot tell whether a rule is true, current, or useful. They make missing and malformed guidance visible before a coding agent starts from the wrong assumptions.

Put universal rules at the root

Keep universal policy and links in a short root guide. Put detailed explanations in canonical files, and add a scoped guide only where ownership or workflow changes. One useful hierarchy looks like this:

repository/
├── AGENTS.md                  # universal rules and links
├── WRITING.md                 # canonical internal prose guidance
├── STYLE.md                   # canonical public-copy guidance
├── konsistent.json            # boundaries that require a guide
├── packages/
│   └── example/
│       └── AGENTS.md          # package-specific decisions and checks
└── projects/
    └── example/
        ├── AGENTS.md          # product-level decisions and checks
        └── src/
            └── AGENTS.md      # only when source work needs distinct rules

The map is a routing example. A small, uniform repository may need only the root file. A scoped guide earns its place when a boundary owns different data, tests, release steps, or failure modes. If it repeats an ancestor, remove it.

A package guide can name public entry points, test setup, and its release gate. A product-data guide can require a deterministic registry and complete metadata. The root needs neither detail. Rules should become more concrete as their scope narrows.

Check only the boundaries you declare

Konsistent is a structural convention checker. Its configuration can declare which directories must contain an AGENTS.md. This shortened example covers project and package roots:

{
  "$schema": "node_modules/konsistent/konsistent.schema.json",
  "version": "v1",
  "conventions": [{
    "name": "owned-boundaries-have-agent-guides",
    "paths": [
      "projects/*", "!projects/AGENTS.md",
      "packages/*", "!packages/AGENTS.md"
    ],
    "must": {
      "haveType": "directory",
      "haveFiles": ["AGENTS.md"]
    }
  }]
}

When this configuration runs through konsistent check, a matching directory without the file fails the check. The guarantee stops at the configured paths. A new kind of boundary remains invisible until someone adds its pattern, so the configuration belongs in the same review as repository layout changes.

Check guide shape separately

A companion script can check the format inside every discovered guide. For example, a repository can require exactly two headings: # Contents and # Guidelines. Contents maps useful direct children. Guidelines states the rules that change work inside that directory.

const required = ["# Contents", "# Guidelines"];
const headingPattern = /^[ \t]{0,3}#{1,6}(?:[ \t]+.*)?$/gmu;

function checkGuideShape(source: string): void {
  const headings = source.match(headingPattern) ?? [];
  if (headings.join("
") !== required.join("
")) {
    throw new Error("guide headings are missing, reordered, or extra");
  }

  const bodies = source.split(headingPattern).slice(1);
  if (bodies.some((body) => body.trim() === "")) {
    throw new Error("guide sections must be non-empty");
  }
}

konsistent check checks declared coverage. The illustrative shape function checks heading order and non-empty sections. Together those mechanisms catch absent files and broken structure. They cannot check whether listed commands work, whether ownership changed, or whether Codex will follow a vague rule. That distinction matches the bounded guarantees in types and property tests.

Change guidance with the boundary

When an owned boundary or its workflow changes, update the nearest guide in the same change. Then run the structural convention command and guide-shape checker configured by the repository. When repeated feedback becomes a prose rule, update the canonical writing guide and point scoped files to it instead of copying the checklist across the tree. Rationale, history, examples, evidence, and plans can stay in repository-adjacent agent memory, where an agent can pull them when the task needs context.

Use scoped guides when local work differs

Use nested guides when teams, packages, or products have different workflows that a root file cannot state without exceptions. Keep one root guide when the repository is small and uniform. More files add maintenance, and every added guide on the loaded path consumes instruction context.

Treat agent documentation as a routing system: the root carries universal policy, each nested guide adds only the constraints that change local work, and both change with the boundary they describe. Presence and shape checks can prove that declared guides exist and follow a reviewable format. They cannot prove that a command works, a rule is current, or the chosen scopes are complete. People still own the truth of every rule and the decision to remove guidance that no longer changes the work.