Claude Code Project Structure Coumets Dev

Claude Code reads its instructions and configuration from a small set of well-known files in your repository. Knowing what each one is for keeps CLAUDE.md short, shares the right things with your team, and keeps context lean.

Layout

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── code-style.md
    │   ├── api-conventions.md
    │   └── pr.md
    ├── commands/
    │   ├── review.md
    │   └── deploy.md
    ├── skills/
    │   └── testing-patterns/
    │       └── SKILL.md
    ├── agents/
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/
        └── validate-code.sh

What each file does

Path	Purpose	Shared via git
`CLAUDE.md`	Project overview, tech stack, code conventions and architecture notes. Loaded at the start of every session.	Yes
`CLAUDE.local.md`	Your personal, project-specific preferences (sandbox URLs, test data). Loaded alongside `CLAUDE.md`.	No, add it to `.gitignore`
`.mcp.json`	MCP server integrations such as GitHub, JIRA, Slack or databases. Lives at the project root.	Yes
`.claude/settings.json`	Permissions, tool access, environment variables and hook configuration.	Yes
`.claude/settings.local.json`	Personal overrides of the project settings.	No
`.claude/rules/*.md`	Modular instructions, one topic per file, for things you do not want in `CLAUDE.md`. Rules can be scoped to file paths so they load only when relevant.	Yes
`.claude/commands/*.md`	Custom commands. Each file becomes a command and can use `$ARGUMENTS` for user input. Good for PR reviews, deployments and scaffolding.	Yes
`.claude/skills/<name>/SKILL.md`	Skills loaded automatically when the task matches, or invoked with `/<name>`. They can bundle supporting files.	Yes
`.claude/agents/*.md`	Subagents with their own system prompt, tools and permissions, running in an isolated context.	Yes
`.claude/hooks/*.sh`	Scripts run on events (for example before or after a tool call), so a behaviour happens deterministically instead of depending on the model. Wired up in `settings.json`.	Yes

Always loaded or on demand

flowchart LR
  Start[Session starts] --> Always[Loaded at launch]
  Always --> ClaudeMd[CLAUDE.md and CLAUDE.local.md]
  Always --> Rules[Rules without path scope]
  Always --> Settings[settings.json and .mcp.json]
  Task[Task or prompt] --> OnDemand[Loaded on demand]
  OnDemand --> Skills[Matching skills]
  OnDemand --> ScopedRules[Path-scoped rules]
  OnDemand --> Agents[Subagents when delegated]
  Events[Tool events] --> Hooks[Hook scripts run]

Keep the always-loaded layer small. Move rarely needed knowledge into skills and path-scoped rules so it only costs context when the task needs it.

Commands and skills

Custom commands have been merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Existing command files keep working, but prefer a skill for new work because skills support supporting files and let Claude load them automatically when relevant.

Practical tips

Run /init to generate a first CLAUDE.md, then trim it to what Claude cannot infer from the code.
Put team conventions in .claude/rules/ and personal notes in CLAUDE.local.md.
Use hooks for anything that must always happen, such as formatting, linting or blocking dangerous commands.
Use /memory to edit CLAUDE.md files and /permissions to review tool rules.

See Essential Claude Code Commands for the commands mentioned here, and Setting Up a New Project with Claude Code for a first-time walkthrough.