The Problem
Claude Code has five distinct context layers: CLAUDE.md, Rules, Skills, Agents, and Hooks. Each answers a different question. Put knowledge in the wrong layer and it either bloats every session, gets ignored, or fails to trigger when needed.
This compass gives you a mental model for deciding where to put what and why that layer is the right fit.
Architecture Map
Follow a real prompt through all five layers. We'll use ShopFlow, a fictional e-commerce store, to show what each layer looks like in practice.
A developer asks Claude to add a Stripe checkout page...
Decision Tree
Click through to find the right layer for your knowledge.
I have knowledge or guidance I want Claude to use. What kind is it?
The 5 Layers
Each layer has a purpose, a litmus test, and anti-patterns. Expand any layer to see the details.
Always. First thing you create.
Project identity in <200 lines. Tech stack, build commands, file structure, conventions that can't be inferred from code.
Sets the baseline context for every session. It's the README for Claude.
You need to encode layout patterns, architecture references, project-specific tool preferences (e.g., migration tools, testing patterns), or pointers to central documentation, especially in large, complex projects.
Modular .md files in .claude/rules/. Can be path-scoped with paths: frontmatter. Can reference external architecture docs, ADRs, wiki pages, or tool-specific conventions chosen for this project.
Rules bridge Claude to your wider knowledge base. They encode project-specific structural decisions: how code is organized, which patterns and tools are preferred here, where to find authoritative references. All without bloating every session.
You have deep knowledge about a technology, workflow, or domain that Claude should reference when relevant.
SKILL.md files with frontmatter. Auto-invoked by description matching, or manually via /skill-name.
Loaded on-demand, not every session. Keeps base context clean while making deep expertise available.
A recurring task benefits from a specialized persona with restricted tools and preloaded skills.
Agent .md files defining role, allowed tools, preloaded skills, and behavioral instructions.
Isolation. A code-reviewer doesn't need Write access. A researcher doesn't need Edit. Agents scope context and permissions to a role.
You need guaranteed, deterministic execution, not advisory guidance.
Shell commands triggered on lifecycle events (PreToolUse, PostToolUse, SessionStart, etc.).
Rules and CLAUDE.md are advisory. Claude might skip them. Hooks are code that runs.
Comparison Matrix
Side-by-side comparison of all five layers.
| Layer | Scope | Loads when? | Enforcement | Contains |
|---|---|---|---|---|
CLAUDE.md | Project | Always, every session | Advisory | Identity, conventions |
Rules | Project / User | Always or path-match | Advisory | Structure, architecture refs |
Skills | Marketplace | On-demand / auto-match | Advisory | Tech knowledge, workflows |
Agents | Marketplace | When delegated to | Enforced | Role, tool restrictions |
Hooks | Project / User | On lifecycle event | Enforced | Shell commands |
Project
Always, every session
Identity, conventions
Project / User
Always or path-match
Structure, architecture refs
Marketplace
On-demand / auto-match
Tech knowledge, workflows
Marketplace
When delegated to
Role, tool restrictions
Project / User
On lifecycle event
Shell commands
Advisory vs Enforced
Advisory
Claude shouldClaude reads these and follows them, most of the time. But it can choose to deviate if it judges something else is better.
Enforced
Claude mustThese execute mechanically. Hooks run as shell commands. Agent tool restrictions are hard boundaries. No discretion involved.
Scope Hierarchy
Click a scope to see what lives there. Higher scopes override lower ones.
Higher scopes override lower ones ↓
Skill vs Agent
Skill = the WHAT
Technology knowledge. How does Playwright work? What are the best practices for Vite config? How do we structure GitLab CI pipelines?
playwright skill: knows about locators, fixtures, Page Object Model, parallel execution patterns.
Agent = the WHO
A specialist who uses that knowledge. Has a persona, restricted tools, and a specific mindset. The agent preloads skills it needs.
test-writer agent: preloads playwright skill + has Write access to test files only + thinks about edge cases and isolation.
If it's just knowledge with no permission difference → Skill
Quick Decision Cheat Sheet
Official Documentation
CLAUDE.md files, auto memory, file hierarchy and loading order
Path-scoped rules, frontmatter, symlinks, user-level rules
SKILL.md structure, frontmatter, auto-invocation, supporting files
Custom agents, tool restrictions, skill preloading, isolation
Lifecycle events, hook types, deterministic automation
Practical patterns and examples for hook configuration
Permissions, environment variables, settings hierarchy
Distributing skills and agents across teams
Workflow patterns for getting the most out of Claude Code