The decision framework
You now understand all six layers. The remaining question is: for any given piece of configuration, which layer does it belong in? Here is the decision flow you should follow every time.
Step 1: Is this knowledge Claude needs in every session?
Yes → Put it in CLAUDE.md. Build commands, project architecture, universal coding standards. Keep it under 200 lines. If it is growing beyond that, split into @imports or .claude/rules/.
Step 2: Is this knowledge that applies to a specific area of the codebase?
Yes → Put it in .claude/rules/ with a paths field. React component conventions for src/components/**, API patterns for src/api/**, database rules for migrations/**. These load only when Claude touches matching files.
Step 3: Is this a workflow or task-specific procedure?
Yes → Make it a skill in .claude/skills/. PR review checklist, deployment procedure, changelog generation, code migration steps. Skills load on-demand and can be invoked manually with /skill-name.
Step 4: Does this task require isolated execution?
Yes → Make it an agent in .claude/agents/. Heavy exploration, restricted-access review, parallel work, test generation. Agents run in their own context and optionally in their own worktree.
Step 5: Does the agent need domain knowledge before starting?
Yes → Wire skills into the agent using the skills field. Review standards, testing conventions, architecture maps. The agent starts with full knowledge instead of inferring from code.
Step 6: Does this rule need deterministic enforcement?
Yes → Add a hook in .claude/settings.json. Auto-linting, blocking dangerous commands, protected files, audit logging. Hooks fire automatically and can block actions — they do not depend on Claude's choice.
The one-line rules:
- Always-on knowledge → CLAUDE.md
- Scoped knowledge → Rules with paths
- Task recipes → Skills
- Isolated workers → Agents
- Informed workers → Agents with skills
- Guaranteed behaviour → Hooks
