Intent Files

A platform team at a large engineering organization has just finished agreeing on the rule everyone wants: no AI agent touches code under `payments/` or `auth/` without a human in the loop, no agent commits directly to a release branch, no agent installs a dependency that has not already been vetted. These are non-negotiable, security-and-compliance-grade, and they need to hold across four hundred repositories, not just the handful the platform team happens to watch closely. That part is, relatively speaking, the easy problem.

The next message in the thread is from a team lead three teams over, asking whether the org-wide file can also note that their service uses pytest instead of unittest, that their commit messages follow a specific format, and that their `legacy-billing/` directory — untouched in any meaningful way since 2019 — still requires a second reviewer on every change because of a data-migration risk nobody wants to relitigate. The platform team’s answer is correct and uncomfortable at once: no, none of that belongs in the org file. It belongs somewhere else. Where “somewhere else” actually is turns out to be the more interesting question, and it is the one this chapter answers.

What one file cannot hold

Chapter 4 named the shape a standing set of project principles takes: a constitution, in spec-driven development’s own vocabulary, or a CLAUDE.md / AGENTS.md file at project grain, loaded at the start of every session so an agent works from the same assumptions a senior engineer on the team already holds. That framing is correct as far as it goes, and it goes exactly as far as one project with one set of conventions. It does not survive contact with an organization running hundreds of projects, several of them containing at least one directory that plays by different rules than the codebase around it.

A single file asked to carry an org’s non-negotiables, one project’s testing conventions, and a legacy directory’s special review requirement has exactly two ways to fail, and most attempts at the flat-file approach eventually find both. Grown to completeness, it becomes the failure mode this Library already named for a single memory file: a standing document large enough that no session reads it in full, competing for attention against the actual task the same way any oversized context does. Kept deliberately short to dodge that fate, it loses precisely the specificity that made the narrower rules worth writing down in the first place — the legacy-billing reviewer requirement gets compressed into something so generic that an agent working three directories away has no way to tell whether it applies there or nowhere at all.

How layering actually works

The practical answer several tools converged on independently by 2026 is not one file but a small hierarchy of them, each layer inheriting rather than repeating the layer above it. An org-level baseline sets what must always be true, regardless of which repository a session happens to be working in. A project-root file adds the conventions specific to that codebase — which test framework, which lint config, which directories exist and what they are for — without restating rules that already apply everywhere. Nested, directory-scoped files add narrower rules still, read only when a session is actually working in that part of the tree.

This is not a hypothetical shape. The AGENTS.md specification builds it directly into the format rather than leaving it to convention: agents “automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions,” and the spec’s own worked example is OpenAI’s main repository, which by the format’s own account carries eighty-eight separate AGENTS.md files — one per package, each inheriting the root file’s conventions and adding only what that package needs. Cursor’s documentation describes the identical mechanism in near-identical language: nested AGENTS.md files are combined with their parents, “with more specific instructions taking precedence.” Claude Code arrives at the same behavior from a different angle — a topic file placed under `.claude/rules/` with `paths:` frontmatter loads only when a session reads a file matching that glob, and subdirectories are discovered automatically, so a rule at `.claude/rules/frontend/react.md` applies inside `frontend/` and nowhere else. GitHub Copilot’s path-specific instruction files compose the same way: when a file matches both a path-specific instructions file and the repository-wide one, Copilot’s own documentation states plainly that “the instructions from both files are used.”

Guidance versus enforcement

There is a second axis hiding inside the org-to-directory hierarchy that is easy to miss on a first pass: the layers do not only narrow in scope, they change in kind. Claude Code’s own documentation is explicit that a rules file — like CLAUDE.md itself — is “guidance Claude reads, not configuration Claude Code enforces”; for guaranteed behavior, it directs teams toward hooks and permissions instead. An organization’s non-negotiables are exactly the kind of rule that cannot safely stay advisory, because advisory-and-ignored is indistinguishable from absent until the moment it matters. That is presumably why, in the same product, the org-grade layer is not a prose file at all: managed-settings.json is documented as “enterprise-enforced settings” living at the system level, and settings deployed there are described as taking “precedence over everything” a project or a personal override might otherwise set.

Project and directory layers can afford to stay advisory, mostly because getting them wrong costs a code-review comment rather than a compliance incident. A test-framework preference or a commit-message format is worth writing down precisely, so an agent is not re-deriving it fresh every session, but it does not need a hook standing over it refusing to let a session proceed. It is a similar instinct to the one behind Anthropic’s own harness guidance choosing a structured JSON file over prose for a different kind of standing state, specifically because a model is less likely to casually rewrite a JSON file than a markdown one — the format itself resists drift. The org layer earns real enforcement because the cost of a miss is asymmetric; everything narrower earns the lighter weight of a file someone reads, because the cost of a miss there is a nudge back on track, not an incident report.

The layered-scope pattern

The discipline this table encodes is the one the previous volume kept returning to under different names: context is a finite resource, and a layer that inherits rather than repeats keeps every session’s working set close to what that session actually needs. A session working inside one narrow module has no operational reason to carry the specifics of the other thirty-nine modules’ local conventions in its context — layering is what keeps it from having to. Anthropic’s framing of the general problem applies here without modification: standing content gets loaded unconditionally because it is small and needed everywhere, and everything else waits for the moment a session’s actual work calls for it. A well-layered intent-file hierarchy is that same rule, applied to the instructions an agent reads before it starts rather than the files it reads while it works.

What a layered audit should check

Operon does not yet have a published distribution of how layered intent-file hierarchies actually perform across real organizations. The figures below are illustrative — offered as the shape of an audit worth running, not a reported result.

Maintenance is not optional

Layering solves the bloat-versus-specificity trade-off; it does not solve the discipline problem the earlier chapter on file-based memory already flagged for a single file, and a hierarchy multiplies that problem rather than dividing it. A project-root file still grows without bound if nobody prunes it — the same failure, one layer up from where a single flat file used to sit. Layers can also drift out of agreement with each other in a way one file cannot: an org baseline changes after an incident, and nobody checks whether the twenty project-root files that quietly assumed the old rule now contradict it; a directory’s actual conventions evolve as the people working there change practice, and the nested file three levels down goes stale because nobody remembered it existed to update. Both failures are invisible in the way that matters most — the file is still there, still gets loaded, and still states something confidently wrong.

The practical response is unglamorous and familiar from every other kind of standing documentation a team already maintains: an intent file needs an owner the way a service does, and a review cadence the way an on-call rotation does, not a one-time authoring exercise. A layered hierarchy needs one more habit with no single-file equivalent — an occasional audit for contradiction between layers, not only for growth within any one of them, run whenever the org baseline changes and periodically regardless of whether it has. Neither habit requires new tooling. Both require someone deciding the file is worth maintaining at the standard already applied to the code it instructs an agent to write.