Agent docs hygiene: route rules to the right scope

In a Codex repository, the task request is one layer of instruction. 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 the broader rules.

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.

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.

The useful contract is narrow: Codex can find a short path from repository policy to local constraints, and structural checks can verify the declared files and their shape. When scoped guides also govern captures and maintained notes, a durable knowledge-base write path can keep authored records separate from generated catalogs and backlinks. People still own the truth of each rule, the coverage patterns, and the decision to remove guidance that no longer changes the work.