---
title: "5-layer agent runtime - three document layers"
date: 2026-05-08
author: "Daniel Henneberger"
description: "Memory, knowledge, and delegation are the three Claude Code layers most teams quietly lose control of. They are documents in disguise — and they rot the same way every other doc rots."
tags: ["claude-code", "agents", "skills", "memory", "platform"]
cover: "/blog/claude-codes-middle-layers.svg"
---

There is a useful piece of vocabulary going around right now: Claude Code as a [five-layer agent runtime](https://todatabeyond.substack.com/p/claude-codes-5-layer-agent-development) — `CLAUDE.md` (memory), Skills (knowledge), Hooks (guardrails), Subagents (delegation), and Plugins (distribution).

It is a clean way to look at the system. It also makes the failure pattern obvious.

Hooks and plugins are mechanical. A hook is a script; it either fires or it doesn't. A plugin is a manifest; it either installs or it doesn't. Engineering orgs already know how to manage scripts and packages.

The other three are not mechanical. **Memory, knowledge, and delegation are documents.** A `CLAUDE.md`, a `SKILL.md`, a subagent's system prompt — they are prose written by humans, read by a probabilistic model, expected to remain true as the codebase moves underneath them.

That is a documentation problem. And documentation problems do not get better when you give them to engineers as a side quest.

This post is about the middle three.

![CLAUDE.md goes stale past the 200-line ceiling](/blog/claude-md-rot.svg)

## Layer 1: the memory layer is already breaking

`CLAUDE.md` is the most-used and least-managed file in modern engineering repos. The official guidance is that it should be ["under roughly 200 lines"](https://code.claude.com/docs/en/best-practices); past that, *"Claude ignores half of it because important rules get lost in the noise."*

That is not a hypothetical. The community is living it:

- "Past 200 lines it stops reading the bottom anyway… mine keeps growing and Claude ignores 80% of it past a point." — [BSWEN](https://docs.bswen.com/blog/2026-04-23-prevent-claudemd-bloat/)
- "Claude would adhere to the instructions somewhat reliably at the beginning and end of the conversation, but was likely to ignore during the middle where the real work is being done." — [HN thread](https://news.ycombinator.com/item?id=46102048)
- A friend on the same thread tells Claude to address him as "Mr Tinkleberry." That is his canary. When Claude stops calling him Mr Tinkleberry, he knows the file is no longer being read.

Then there is the precedence problem. Claude walks the directory tree concatenating every `CLAUDE.md` it finds. The order is documented inconsistently enough that Anthropic has [its own open issue](https://github.com/anthropics/claude-code/issues/18964) about it, and a separate issue ([#54955](https://github.com/anthropics/claude-code/issues/54955)) noting the behavior *"differs from intuitive behavior where closer/more specific files should take precedence."* In a monorepo, you also load every parent file whether you want to or not — issue [#20880](https://github.com/anthropics/claude-code/issues/20880) describes a 40k-character Go-microservices root rule sheet being loaded inside a UI subdir, with no way to opt out.

And then it goes stale. Rules in `CLAUDE.md` outlive the code they describe. Auto-memory writes new entries you never reviewed. Conventions drift. The on-call engineer onboarding next month gets a different `~/.claude/CLAUDE.md` than yours, so their Claude does different things in the same repo. Anthropic shipped `/team-onboarding` in v2.1.101 specifically because, in the words of the Panaversity guide, *"the frontend developer's Claude inserts Python docstrings into React components, the backend engineer's Claude adds TypeScript-style imports to FastAPI routes."* [That guide is here](https://agentfactory.panaversity.org/docs/General-Agents-Foundations/claude-code-teams-cicd/claude-md-configuration-hierarchy).

There is no linter. There is no `claude memory diff`. There is no expiry. There is no test that the rule "use functional components" still matches the code. There is no review step on auto-memory writes. Memory is treated as a config file, but the failure mode is documentation rot.

![Skill activation is a coin flip](/blog/skill-coin-flip.svg)

## Layer 2: the knowledge layer is sprawling before most teams notice

Skills were supposed to be the answer to a 400-line `CLAUDE.md`. *"A skill's body loads only when it's used,"* per the [official docs](https://code.claude.com/docs/en/skills), so long reference material costs nothing until you need it. Modular knowledge. On demand.

In practice, the failure modes show up almost immediately:

- **Sprawl.** A 15-day [audit diary on dev.to](https://dev.to/shimo4228/15-days-of-skill-sprawl-in-claude-code-lessons-from-3-audits-27em) reports six parallel projects sharing incompatible skill sets for eight days before anyone noticed. By day 11, the author was running an audit every two to three days. Recommended ceiling, per [Nimbalyst](https://nimbalyst.com/blog/claude-code-skills-guide/): "Eight to twelve well-chosen skills cover most of a senior developer's day. More than that starts incurring a context tax."
- **Activation is a coin flip.** A 650-trial study found *"approximately 50% activation rate — essentially a coin flip"* on whether the right skill fires for a given prompt ([Ivan Seleznov, Medium](https://medium.com/@ivan.seleznov1/why-claude-code-skills-dont-activate-and-how-to-fix-it-86f679409af1)). The mechanism is description-matching against a *"1% of context window"* budget that silently truncates as you add more skills ([claudefa.st](https://claudefa.st/blog/guide/mechanics/skill-listing-budget)).
- **Rot.** "Claude Code skills quietly rot as repos, standards, and tooling change… a skill is stale when it no longer matches how good work should actually be done in the current codebase." A stale skill *"can keep resurrecting patterns the team deliberately moved away from, creating a loop where the team keeps cleaning up outputs that the skill itself keeps steering back into existence."* — [qcode.in](https://qcode.in/claude-code-skills-will-rot-unless-teams-track-their-expiry-dates/)
- **Untested.** Anthropic concedes the gap: most skill authors *"are subject matter experts, not engineers. They know their workflows but don't have the tools to tell whether a skill still works with a new model, triggers when it should, or if it actually improved after an edit."* ([Anthropic blog](https://claude.com/blog/improving-skill-creator-test-measure-and-refine-agent-skills))

And the bigger gap: **the institutional knowledge an org actually has does not live in `.claude/skills/`.** It lives in Slack threads, Confluence pages, design docs, and the heads of three senior engineers. That is the gap between "we have skills installed" and "Claude knows how this team actually does things." It is not a skill problem. It is a documentation pipeline problem.

## Layer 4: the delegation layer is fragile in exactly the place teams trust it

Subagents are how you stop the main context from collapsing at two-thirds. They run *"in their own context and return only the summary"* ([code.claude.com](https://code.claude.com/docs/en/sub-agents)). When they work, they are the single biggest quality lever in the whole runtime.

The catch is what teams put in `agents/code-reviewer.md`. That file is a system prompt — a document — describing how *your team* reviews code. And it has the same management problems as any other document, with extra failure modes on top:

- **Routing is unreliable.** Anthropic's own troubleshooting docs say *"use explicit prompting: mention the subagent by name."* The router is itself an LLM matching free-text descriptions; there is no test suite for "does the right subagent fire for this prompt?" ([ksred](https://www.ksred.com/claude-code-agents-and-subagents-what-they-actually-unlock/) is blunt: *"Auto-selection of custom agents remains unreliable… explicit invocation is the only reliable trigger."*)
- **Config drift across the team.** Every engineer has their own `~/.claude/agents/`. There is no `extends:` mechanism — feature request [#4800](https://github.com/anthropics/claude-code/issues/4800) names this exactly: *"teams sharing Claude Code configurations across multiple repositories currently must manually copy files between projects, leading to configuration drift and maintenance burden as teams scale."*
- **Verification is on you.** Subagents return summaries. The parent agent *summarizes the summary.* That is two lossy passes between "the work" and "what the main agent now believes." [Alex Dorand](https://medium.com/@alexdorand/prevent-claude-code-lying-9a09c3f64155): *"I have lost over $250 to figure out that Claude Code is not truthful all the time… I trusted Claude when it said all was done, only to discover a few minutes later that it was not."*
- **Authority is per-tool, not per-action.** A subagent either has `Edit` or it doesn't. There is no native concept of "this agent can open PRs but not merge," "this one can comment but not push." Skills and subagents [don't reliably inherit permissions from settings.json](https://github.com/anthropics/claude-code/issues/18950).
- **Cost.** Multi-agent workflows run [4–7x](https://code.claude.com/docs/en/agent-sdk/subagents) the tokens of single-agent ones; ksred reports Agent Teams hitting 15x. There is no per-agent budget. Opus has *"a known tendency to over-spawn subagents,"* with simple tasks consuming 50K tokens through unnecessary delegation.

And again, the deeper gap: the subagent prompt that says *how your team reviews code* is a doc. It will drift from how your team actually reviews code. There is no review step that catches that drift.

## The pattern

Three layers. One pattern.

Each one is a folder of documents that the agent reads as ground truth. Each one rots. Each one sprawls. Each one fails silently — Claude does not throw a compile error when `CLAUDE.md` contradicts the code, when the skill description loses the routing lottery, when the subagent prompt describes a workflow nobody uses anymore.

The thing engineering orgs are missing is not a sixth layer. It is the same thing they have always been missing: a documentation pipeline that survives change. Source-grounded. Versioned. Reviewed in PRs. Drift-detected against the code.

## Where Mari fits

Mari is AI content management for coding agents: the record of everything your AI writes. The thesis we keep coming back to: [documentation is a background-agent-shaped problem](/blog/we-need-background-agents). Bounded. Repetitive. Anchored in code, PRs, and Slack, sources of ground truth an agent can pull from and cite back.

That same thesis is what makes Mari the right place to put the middle three layers. The loop that keeps a runbook honest, [detect the change, write or update, verify every fact, owner signs off, watch for drift](/), is the same loop that should govern the documents governing your agents.

Concretely:

- **Memory.** `CLAUDE.md` is a doc. Mari treats it like one: versioned, source-grounded, kept under the 200-line ceiling, and diffed when the codebase moves. When the rule "use functional components" stops matching the code, that is drift, and it shows up on the record like any other stale fact.
- **Knowledge.** Skills are [documents too](/blog/skills-are-documents-too). Every fact a skill makes about your system gets a source and an owner. Workflow skills and fact skills stay separate, because facts change faster than reasoning, and every change ships as a PR you can review.
- **Delegation.** A subagent's system prompt is a doc describing a role. Mari watches it the way it watches a runbook: pinned to the parts of the repo it operates on, flagged when those parts move, reviewed by a human before the fix ships. The gap between "how the code-reviewer agent thinks code is reviewed" and "how the team actually reviews code now" becomes a tracked signal, not a surprise.

We are not trying to replace `.claude/`. We are trying to give `.claude/` the same record your docs get: a source, an owner, a sign-off on every fact, and a watcher for when the code moves on.

The 5-layer framework is the right map. The middle three layers are where teams quietly lose, because they are documentation, and documentation does not maintain itself.

Mari is what maintains it.

If you'd rather see it live, [book a demo](https://calendly.com/d/dtn2-w7x-bbm/mari-guru-intro), or open an issue on [GitHub](https://github.com/MariHQ/mari) and pull on the thread.

— Daniel