The_Layering_Solves_the_Problem

Running agents across more than twenty repositories taught me that the solution is not a better manual. It is no monolithic manual at all. Instead, rules live in a four-layer context resolution order:

Layer 1 - Fleet baseline. Everything that is true everywhere gets written once, at the fleet level. Code standards (TypeScript strict mode, no any types), security practices (try/catch on every external call, no hardcoded secrets), git workflow (conventional commits, always branch, semantic-release), language policy (UK English for personal brand surfaces, US English for commercial). This is the global baseline. It appears in one file (~/AGENTS.md) and is the source of truth for every agent, every project, every repo.

Layer 2 - Harness layer. The Claude Code harness has its own rules - persona dispatch, model tiering, worktree safety, MCP configuration, skill references, memory hygiene. These are not coding standards; they are orchestration standards specific to how agents coordinate across tools and projects. They live in one file (~/.claude/CLAUDE.md), separate from the project handbook, so that non-Claude agents operating in the same repos are not confused by infrastructure that does not apply to them. A Codex agent reading a repo does not need to know which Claude agent is delegated to handle code review.

Layer 3 - Project handbook. Each repository carries its own AGENTS.md - stack-specific rules, environment variables, commands that are true only for that project. FitCheckerApp runs Tier 1 testing; Labs runs Tier 2. GEOAudit needs specific Mapbox configuration; a utility toolkit does not. This is where per-project specialisation lives. An agent working in one repo reads the repo handbook and learns what is different from the baseline - and learns it from a file that is co-located with the code, not buried in a cross-project archive.

Layer 4 - Scoped rules. Within a project, each repository carries a top-level CLAUDE.md that defines Claude-specific wiring (which persona owns which module). Adjacent to the four-layer resolution order - but outside it - agents carry session-scoped memory and project-level planning rules that are situational enough to live outside the canonical reference chain.

What this means in practice: an agent touching the Labs UI layer reads ~/AGENTS.md, ~/.claude/CLAUDE.md (Claude harness), labs/AGENTS.md (project handbook), and labs/CLAUDE.md (project Claude-specific). No other files. Nix, the agent who works the UI, reads a clear scope contract: this is what is true everywhere (layer 1), this is how Claude coordinates work (layer 2), this is what is true in Labs (layer 3), this is what is true when you are working on Labs with Claude (layer 4). Every rule is in exactly one place. Every place is the right place.

An agent working in a different project (FitCheckerApp, GEOAudit) reads the same layer 1 and 2, then different layer 3 and 4 files. The baseline rules still apply. The harness rules still apply. The project-specific rules change because the project is different. This is the resolution order, baked into the system: general, then specific, then more specific, then situational.

What_Forced_This_Architecture_into_Existence

Until May 2026, each repo carried a single CLAUDE.md - Claude-specific instructions and general project conventions living side by side in one file. That worked as long as Claude Code was the only agent reading it. It stopped working the day a Codex CLI wrapper became a real tool in the fleet, with Cursor and Aider sessions likely to follow. A survey run against the existing repos found nine of ten CLAUDE.md files were "mixed" - persona names interleaved with genuine stack conventions, environment variables, and gotchas. To a Codex agent, a persona pointer is noise: it does not know who the named persona is and does not need to.

The fix was structural, not editorial. Every repo splits into AGENTS.md (canonical, tool-agnostic - any agent reads it) and a thin CLAUDE.md shell (Claude-specific layers only: persona pointers, /skills, MCP configuration), with the fleet baseline promoted to a single file so per-repo files could link rather than duplicate. One project had already converged on the inverse of the mixed pattern - a one-line CLAUDE.md that did nothing but import AGENTS.md. That file became the template the rest of the fleet migrated to. The layer 1 / layer 2 / layer 3 / layer 4 structure formalised what the split had already started: layer 1 (fleet baseline) absorbed the standards that used to live copy-pasted across every repo; layer 2 (harness) took everything Claude-specific that a non-Claude agent has no use for; layer 3 (project handbook) is where per-repo specificity survives contact with a second and third coding agent; layer 4 (the repo's CLAUDE.md) exists for what changes faster than the first three layers can absorb without going stale themselves.

The_Case_Study_-_OpenAI's_Codex_Team

The pattern I built and refined is not unique. In February 2026, OpenAI published a report on harness engineering in their own Codex team - a group running 1 million lines of code and accumulating 1,500 pull requests over 5 months of intensive development. At that scale, they too abandoned a monolithic agent instruction manual. Their rationale was identical to mine: the manual was a centralised document attempting to govern every agent, every context, and every decision path. As the codebase scaled, the manual became a graveyard of stale rules, contradictions, and dead procedures. The solution they converged on was the same structural move - breaking the monolithic instruction set into modular, state-driven context files. General rules in one layer, project-specific configuration in another, situational context injected based on what the agent is currently touching.

OpenAI did not call it a four-layer resolution order. They called it modular, state-driven context. The principle is identical. The manual did not scale because no manual scales. A rule hierarchy does.

Maintainability_Is_Not_a_Writing_Problem

The temptation, when faced with a decaying manual, is to rewrite it. Make it clearer. Add better indexing. Use a tool that enforces consistency. The actual problem is that you are trying to solve a system-architecture problem with a documentation solution. A monolithic manual is unmaintainable by definition - not because the writing is poor, but because centralisation works only when the set of rules is small enough to fit in one place, and when the rules are stable enough that updates do not threaten the coherence of the whole.

Both conditions fail at scale. The set of rules grows: fleet baseline, project standards, situational rules, operational exceptions. Stability fails: a new project introduces a tool nobody else uses; an external service changes its authentication method; an operational incident reveals a gap in the ruleset. When you update the manual, you are not just fixing one rule - you are updating the central record that every agent depends on. The cognitive load is massive. The coordination overhead is massive. The drift is inevitable.

The layered approach distributes that load. The fleet baseline does not change often - code standards and security practices are stable. The project handbook changes when a project's stack changes, not when someone's workflow changes. The scoped rules and memory change rapidly, but they are small enough to maintain easily. Each layer is sized for its rate of change.

This is why OpenAI's internal Codex team built the same structure. It is not about writing style. It is about the system architecture determining what can be maintained without constant rewrites.