Agents & Coding
Where Each Rule Goes in a Claude Code Repo
CLAUDE.md for what is true every session, skills for what you need sometimes, hooks for what must never be skipped.
Annoying if ignored once: CLAUDE.md. A disaster if ignored once: a hook.
CLAUDE.md should not hold everything, @AlekVectis writes. Here is his split, checked against the Claude Code documentation.
| File | What it holds |
|---|---|
| CLAUDE.md | What is true every session: build and test commands, the odd repo rules. Keep it short |
| .claude/settings.json | Permissions, committed so the team gets them. A deny on Read(./.env) keeps secrets unread |
| .claude/settings.local.json | Your own overrides for one project, kept out of git |
| .mcp.json | Project MCP servers, so anyone who clones the repo gets the same tools |
| .claude/skills/name/SKILL.md | Procedures you need only sometimes, like release steps. Loads when the task calls for it |
| .claude/agents/ | Subagents with their own prompt and tool list, such as a reviewer that can read but not edit |
| hooks, in settings.json | Anything that must happen every time. A PreToolUse hook that exits with code 2 blocks the call |
The docs add two details for anyone writing a guard hook. Exit code 1 is only a non-blocking error, so a policy hook should exit 2. And a hook’s if filter is best effort, so the docs suggest permission rules for a hard allow or deny.
On a long task, @AlekVectis notes, Claude drifts from instructions. A hook just runs.
Sources
- @AlekVectis on X · Oct 23, 10:59 AM PT
- Claude Code docs: settings · code.claude.com
- Claude Code docs: hooks · code.claude.com