Context Engineering · ~7 min

The Layer Stack

Your instructions arrive from four sources at once. Knowing which one wins — and where it physically lands — is how you stop an agent from "ignoring" a rule.

Why this, for you: the assembly layer that sits on top of everything you've learned. It's the answer to "why did the agent ignore my CLAUDE.md rule?" (priority #1) and the design model for harnesses with skills and sub-agents (priority #2). It also explains the @AGENTS.md primacy nuance from Lesson 03.

Instructions stack in layers, each more specific than the one above it. On a conflict, specificity wins — the layer closest to the task usually overrides the ones further out.

more specific →

① System prompt — platform/tool default: role, permissions, baseline

② Project instructions — AGENTS.md / CLAUDE.md: applies to every task

③ Skill content — SKILL.md: this task type only

④ User message — the immediate intent; overrides all above

Precedence is a behavioral tendency, not a rule the model enforces. Contradictions between layers produce unpredictable output — so each convention must live in exactly one layer; the others point to it or stay silent.

"Always write tests" in CLAUDE.md, then a user message "skip tests for now" → the agent skips them. Correct for the immediate task, but it just overrode your project convention. That's the stack working as designed — and why duplicating a rule across layers is a drift bomb: change one copy and you've authored a silent contradiction.

Three edges that bite

① Sub-agents break the stack

A sub-agent starts fresh — its own system prompt, none of the parent's project instructions, skills, or history unless explicitly passed at invocation. Layering without an injection protocol is "operationally equivalent to having no project layer for sub-agents." Debug what the sub-agent received, not what the parent had.

② `@`-import is verbatim concatenation at load time

Claude Code expands @path imports at session start — pulled in verbatim, equivalent to concatenation. So position is real: @AGENTS.md on line 1 injects that file into primacy, making the end of CLAUDE.md the true global tail (Lesson 03). Broken imports fail silently — rename the target and the agent just loads fewer rules, no error.

③ Compliance degrades with stack depth

Each layer adds to total instruction volume, and past the compliance ceiling the lowest-priority rules (usually the project layer) get silently dropped. Ten rules in a flat prompt beat forty spread across four layers.

# CLAUDE.md — @import pulls the canonical file into primacy @AGENTS.md # injected verbatim at the very top ## Claude Code # Claude-specific extras live below, in one place - Use worktrees for experimental work.

When an agent ignores a rule: diagnose by layer

Position? Buried in a long file's middle → it's in the weak-attention zone (Lesson 02). Move it to an edge or repeat it.
Conflict closer to the task? A user message or skill may be overriding the project rule by specificity.
Is it a sub-agent? Then the project layer probably isn't in its context at all.
Past the ceiling? Too many rules in the stack — prune before adding.

↪ Your win: one rule, one layer — and an injection protocol for sub-agents

Each convention lives in exactly one layer. Project = every task; skill = this task type; user = right now. Others point or stay quiet.
Never duplicate across layers — it's a contradiction waiting for one half to change.
Pass critical constraints into sub-agents explicitly — they inherit nothing.
When a rule is "ignored," run the four-step layer diagnosis before rewriting the rule.

Retrieval practice — recall, don't peek

Question 1On a conflict between layers, which tends to win?

Question 2How much of the parent's project instructions does a sub-agent inherit?

Question 3A Claude Code @-import loads the referenced file…

Question 4As you add instruction layers, low-priority rules tend to be…

Question 5 · spaced recall from Lesson 05An API signature written into a CLAUDE.md is…

Ask me anything. Want to trace the actual assembled layer order of your content/ harness (system → @AGENTS.md → CLAUDE.md → rules → skills)? Or see how .claude/rules/ with paths: changes the load timing vs an @-import? Say so — next up is where we'll pause lessons and run the full audit-instruction-file skill across everything.

✎ Feedback