six-layer-agent-architecture
A six-layer mental model specifically for claude-code proposed by tw93 in 2026-04-27-claude-code-architecture-governance-engineering. The thesis: failure modes in Claude Code are almost never single-layer; optimizing one layer in isolation creates problems elsewhere.
Scope: this frame is Claude-Code-shaped — its layer names map directly to claude-code primitives. It is not a universal Agent-architecture frame. For a parallel decomposition of a different Agent product, see openclaw‘s 5-layer architecture and the comparison below.
The six layers
| Layer | Job | Tells Claude |
|---|---|---|
CLAUDE.md / rules / memory | Long-term context | what is |
| Tools / MCP | Action capability | what can be done |
| [[claude-skills | Skills]] | On-demand methodology |
| [[claude-hooks | Hooks]] | Deterministic enforcement (bypasses model judgment) |
| [[claude-subagents | Subagents]] | Isolated workers |
| [[verifier-loop | Verifiers]] | Closing the loop |
Failure modes when layers are over-/under-developed
CLAUDE.mdtoo long → contaminates its own context.- Too many tools → model can’t pick correctly; tool definitions also crowd the budget (context-engineering).
- Subagents fanning out without isolation → state drift, no governance.
- Verification skipped → no signal what failed when something breaks.
Five diagnostic surfaces
A complementary frame in the same article — when something’s wrong, look at:
| Surface | Question | Where it lives |
|---|---|---|
| Context | What’s resident vs. on-demand? | CLAUDE.md, rules, memory, Skills |
| Action | What can Claude actually do right now? | built-in tools, MCP, plugins |
| Control | What must be constrained / blocked / audited? | permissions, sandbox, hooks |
| Isolation | What needs its own context and permissions? | subagents, worktrees, forked sessions |
| Verification | How do we know it’s done and right? | tests, lint, screenshots, logs, CI |
Heuristic from the source: unstable results → look at context loading order; runaway automation → look at the control surface; long sessions degrading → mid-task artifacts polluting context (start fresh) (2026-04-27-claude-code-architecture-governance-engineering).
When to use this frame
It’s tw93‘s framing — keep attribution. Useful as a triage checklist when a Claude Code project misbehaves in a way that’s not obviously a single-cause bug.
Contrast with OpenClaw’s 5-layer frame
tw93‘s second source (2026-04-27-agent-principles-architecture-engineering) walks through openclaw using a different 5-layer decomposition: Gateway / Channel adapters / Pi Agent / Toolset / Context+Memory. Same author, different system, different layers. The takeaway is the layers are product-shaped, not universal:
- The Claude Code six-layer frame is shaped by the coding-collaborator product surface — you need a contract file (
CLAUDE.md), tool/MCP boundary, on-demand methodology (Skills), deterministic enforcement (Hooks), isolation (Subagents), and an output verifier. - OpenClaw’s five-layer frame is shaped by the personal-assistant daemon product surface — you need an external connection layer (Gateway), per-platform adaptation (Channels), the Agent runtime, the toolset, and the context+memory store.
What’s shared across both is the harness thesis: every production failure traces to one of acceptance baseline / execution boundary / feedback signal / fallback. Use the layer names appropriate to the product; use Harness as the cross-system frame.