Jerry Orta

Agent-legibility is an architecture, not a prompt. A large Nx monorepo is far too big to fit in any model's context, so the real question is not how to describe the repository in a single instruction but how to arrange it so an agent assembles the right context on its own — at the right depth, exactly when a task needs it. The answer this repository settles on is a layered set of committed instruction files: one small always-loaded core, and around it a graduated set of colocated, load-on-demand documents. The layering mirrors an agent's attention budget — a scarce, always-present center and a large, addressable periphery — and it is built deliberately from ordinary tracked files rather than from any private, per-user memory.

This note is the companion to the skills note. A skill encodes an action an agent performs; the files described here are the substrate those actions read from. Four layers make up that substrate, ordered from always-present to loaded-on-demand: the root CLAUDE.md, the colocated AGENTS.md pointers, the docs/ deep-dive library, and the docs-projects/ project memory. Each layer answers a different question, and each pays for its place in the context window differently.

The always-loaded core

Every session begins with exactly one file. The repository root holds a single CLAUDE.md, auto-injected at the start of every agent session, and there is no nested CLAUDE.md anywhere beneath it — one core, not a tree of them. Its job is not to hold the repository's knowledge but to hold the minimum an agent must never be without: the coding standards that apply everywhere (separate component files, signal inputs, inject() over constructor injection), the handful of commands that are easy to get wrong, the hard constraints that win every conflict, and, above all, a routing table into everything else.

The core keeps itself small by inlining almost nothing. It imports only two further always-loaded documents, referenced by path so they travel with it:

@docs/reference/commands.md
@docs/reference/important-notes.md

Everything more specific is left out of the core on purpose. A file that is always loaded is paid for on every single task, whether or not the task needs it, so the core admits only what every task genuinely requires. Restraint here is what keeps the center affordable.

Routing over inlining

The core's most consequential section is a table, not a paragraph. A Discovery Map lists areas of the system beside the one document that covers each:

| Area                | Path                                  |
| ------------------- | ------------------------------------- |
| Architecture        | docs/reference/architecture.md        |
| Angular conventions | docs/reference/angular-conventions.md |
| Testing             | docs/reference/testing-strategy.md    |
| Charts library      | docs/architecture/charts.md           |

The map carries addresses, not contents. The core does not explain how testing works; it records where the testing document lives, so an agent about to write a test opens one specific file rather than guessing or loading the entire docs/ tree. This is the central move of the whole design: routing over inlining. Inlining every convention would exhaust the context budget on the first task and bury the one relevant paragraph among fifty irrelevant ones. A routing table costs a few lines and defers the expense of each deep-dive to the task that actually incurs it. The core stays a legible page precisely because it delegates depth to the layers below.

Colocated pointers: AGENTS.md

Below the core sits a layer the core never has to enumerate, because it is discovered by position. Roughly eighty AGENTS.md files are distributed across the repository, each living directly beside the code or documents it governs — libs//store/AGENTS.md next to a domain's state, apps//backend/AGENTS.md next to its cloud functions, apps/jerryorta/app/src/content/AGENTS.md next to the very notes this file belongs to. None of them loads up front. Each is read at the moment an agent begins working inside its directory, and each is deliberately thin — a pointer to the conventions, reusable pieces, and review checklist that matter here, rather than a second copy of the global standards.

Colocation is what lets this scale. The convention for a store lives with the stores, so it is found by working on a store, not by remembering that it exists. This is the same instinct that governs the code itself — a self-contained domain owns its models, state, and UI together, as the domain-driven design note argues — extended from the source tree to the instructions that describe it. An agent that opens a directory has already, by that act, narrowed to the AGENTS.md that applies.

The deep-dive library: docs/

Where the AGENTS.md files are thin pointers, docs/ is the depth they point to. It is the repository's reference library, organized by kind rather than by location: reference/ for conventions and architecture, ai-instructions/ for role-organized procedures, reference, and standards, architecture/ for system designs, and features/ for individual capabilities. The Discovery Map in the core routes here, and a local AGENTS.md often routes here again more specifically. A document in docs/ is written once and addressed from many places.

One part of this library does not wait to be addressed at all. A set of standards fragments under docs/ai-instructions/standards/ is injected automatically the moment an agent edits a matching file, through a PreToolUse hook (.claude/hooks/inject-standards.sh) that fires on every write and infers which standard applies from the file's suffix and its library type. The effect is that the convention for authoring a component arrives precisely when a component is being authored — not recalled from the core, not looked up by name, but delivered by the act of editing. The deep-dive library is therefore reachable three ways: pulled by the Discovery Map, pointed to by a nearby AGENTS.md, or pushed automatically by the edit itself.

Longer memory: docs-projects/

The final layer keeps what a single task should not carry but a project cannot afford to lose. docs-projects/ holds the multi-session material — plans, reports, and per-domain project documents under projects/ — that outlives any one piece of work. A DOCUMENTATION-LIFECYCLE.md governs how a document enters, matures, and is eventually retired, so this layer does not simply accumulate. Where docs/ answers how the system works, docs-projects/ answers what is being built and why, across the many sessions a large effort takes.

This is also where the architecture's one deliberate exclusion is clearest. Everything described here is a tracked file in the working tree — committed with the code, reviewed in the same pull requests, and legible to every agent and every person who clones the repository. It is distinct from the agent's own memory, which records what a session learned rather than what the standards require, and which lives in a repository of its own outside every checkout. That separate register — observational rather than normative, and shared across every clone on a machine — is the subject of a companion post. The substrate described here is public by construction: the repository onboards an agent the same way it onboards a new engineer, from files that live in the tree.

Why it holds together

Four layers, one principle — and a dividend:

A single always-loaded core — one root CLAUDE.md with no nested copies carries only the standards, commands, and constraints every task needs, alongside a routing table into everything else.
Routing over inlining — the Discovery Map records addresses rather than contents, so the core stays a page and each deep-dive is paid for only by the task that opens it.
Colocated AGENTS.md pointers — roughly eighty thin files extend self-contained domains to the instructions that describe them, each found by working in its directory rather than by being remembered.
A routed deep-dive library — docs/ is reached three ways: pulled by the map, pointed to locally, or pushed automatically into an edit through the standards hook.
Longer-lived project memory — docs-projects/ holds the plans and reports that span many sessions, governed by a lifecycle rather than left to accumulate.

The principle underneath all four is a budget. Context is finite and always-loaded content is the most expensive kind, so the architecture spends its scarce center on the few things an agent must never lack and makes everything else addressable, colocated, and silent until a task calls for it. That is the substrate I hand to Claude Code, and the skills note describes the other half: the skills are the actions, and these files are the context every action reads from. The external counterpart to these internal files — the pinned upstream framework source an agent reads to ground a current API in what the framework does now — is the subject of a further note. How these files are read and rewritten across the full life of a feature — from a planned ticket to a merged change — is the subject of the workflow note. Arranged this way, a repository too large to hold in any single context becomes one an agent can nonetheless navigate on-pattern — because the files themselves know where it should look.