The .claude directory is where all the project's customization lives, and the easiest way to make sense of it is to split its contents by role. Some files are instruction that affects the model (CLAUDE.md, rules). Others are policy that sets rules and permissions (settings, permissions). Others are extension that adds executable components (commands, agents, skills, hooks, MCP). Mixing these roles is a frequent source of confusion: instruction is edited expecting a policy effect, and an executable component is taken for a harmless note.

A typical team repository lays these roles out in a familiar structure. At the root are CLAUDE.md and an uncommitted CLAUDE.local.md, .mcp.json with MCP definitions, .worktreeinclude. Inside .claude are settings.json and an uncommitted settings.local.json, and alongside them the directories rules, skills, agents, hooks, output-styles, commands and, if configured, agent-memory. It helps to see this map in full once, to understand where to put a new entity.

Not every project needs all the directories, and this is an important principle. The minimum is a short CLAUDE.md and .claude/settings.json; the rest is added when a repeatable task or a measurable control appears, not in advance. The rule of choice is simple: facts and rules needed almost always - in CLAUDE.md and rules; a procedure on demand - in a skill; a separate role with its own context - in a subagent; an event check - in a hook; an external source - in MCP; a portable set - in a plugin; enforced policy - in managed.

It helps to gather the need and the mechanism into a table once, so as not to invent a new entity for every task. Below is such a map - from project facts to enforced policy. You return to it when your hand reaches to put a procedure in CLAUDE.md or a rule in a skill: each mechanism has its own role and its own loading semantics, and choosing the right mechanism matters more than cramming one place with everything.