Anatomy of Claude Code Project Structure

The complete .claude project anatomy and recommended layout.

Claude Code Project Structure

A production-ready layout, conventions, and best practices for building software with Claude Code — explained in plain English, with copy-paste-ready snippets.

TL;DR

Claude Code is Anthropic's terminal-based AI coding agent; a good project structure makes it 10× more reliable.
The heart of the setup is a CLAUDE.md file (project memory) + a .claude/ folder (config, commands, skills, agents).
Use MCP servers (.mcp.json) to plug Claude into GitHub, JIRA, Slack, your DB, etc.
Use Hooks to enforce safety (lint, secret-scan, tests) automatically.
Tailor the layout to your team size: solo, small team, enterprise, or open-source.

Why this matters

Think of Claude Code like a brilliant new hire. Without an onboarding doc, a desk layout, and access permissions, they wander. CLAUDE.md is the onboarding doc, .claude/ is the desk, MCP servers are the building access badges, and hooks are the safety policies. Get this right once, and every future task goes faster.

Bottom line: Structure isn't bureaucracy — it's how you make an AI agent trustworthy.

The Big Picture

Bottom line: Six moving parts, one source of truth (CLAUDE.md).

Core Components

Name	Purpose	When to use
`CLAUDE.md`	Project memory: conventions, stack, rules	Always. Day 1 file.
`.claude/settings.json`	Shared team config (permissions, hooks, env)	When ≥ 2 people share the repo
`.claude/settings.local.json`	Personal overrides (gitignored)	Per-developer tweaks
`.claude/commands/`	Custom slash commands (`/review`, `/deploy`)	Repeated multi-step workflows
`skills/`	Auto-activated reusable capability packs	When a workflow has docs + scripts + assets
`agents/`	Specialized subagents (code-reviewer, test-writer)	Parallel or domain-specific work
`.mcp.json`	External tool connections (GitHub, DB, Slack)	When Claude needs to do things outside your repo
`plugins/`	Bundled, distributable extension packs	When sharing setups across many repos

Bottom line: Start with CLAUDE.md + .claude/settings.json. Add the rest only when you feel the pain.

Step-by-Step Setup

1. Install Claude Code

npm i -g @anthropic-ai/claude-code

2. Initialize in your project

cd your-project
claude        # first launch creates baseline scaffolding
/init         # built-in slash command bootstraps CLAUDE.md

3. Create your `CLAUDE.md` (project memory)

# Project: My App

## Tech Stack
- Next.js 14, TypeScript, Tailwind
- Supabase for auth & database
- Prisma ORM, tRPC API layer

## Conventions
- Always write tests before code (TDD).
- Use conventional commits (feat:, fix:, chore:).
- Never commit directly to `main`.
- Run lint + typecheck before opening a PR.

## Architecture
- `src/components/` → React components
- `src/services/`   → Business logic
- `src/utils/`      → Shared helpers

## Security
- No secrets in code or logs.
- Validate all user inputs.
- Use parameterized queries only.

4. Add shared settings — `.claude/settings.json`

{
  "permissions": {
    "allow": ["Read", "Bash(npm run *)", "WebSearch"],
    "deny": ["WriteOutsideWorkspace", "Bash(rm -rf *)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "*",
        "hooks": [
          { "type": "command", "command": "./scripts/pre-tool.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "npm run lint" }
        ]
      }
    ]
  },
  "env": {
    "MAX_THINKING_TOKENS": "100000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

5. Wire up external tools — `.mcp.json`

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

6. Add a custom slash command — `.claude/commands/review.md`

---
description: Run a full code review on the current branch
---
You are a senior code reviewer. Diff against `main`, then:
1. List risky changes.
2. Flag missing tests.
3. Suggest concrete fixes with file:line refs.

💡 Tip: Anything in .claude/commands/*.md becomes /filename inside Claude.

Variants for Different Team Settings

👤 Solo developer (the minimalist)

Keep it tiny — you are the convention.

my-project/
├── CLAUDE.md            # your personal style guide
├── .claude/
│   └── settings.json    # 1–2 hooks, generous permissions
└── .mcp.json            # GitHub only

Decision: Skip skills/, agents/, plugins/ until you repeat a workflow 3+ times.

👥 Small team (2–10)

Add shared commands and a code-review subagent.

.claude/
├── settings.json            # committed, shared rules
├── settings.local.json      # gitignored, personal
└── commands/
    ├── review.md
    └── deploy.md
agents/
└── code-reviewer.yml

Decision: Adopt conventional commits + PR template so Claude has predictable patterns to follow.

🏢 Enterprise / regulated

Lock down permissions, add audit hooks, isolate environments.

// .claude/settings.json
{
  "permissions": {
    "allow": ["Read", "Bash(npm test)"],
    "deny": ["WebSearch", "Bash(curl *)", "WriteOutsideWorkspace"]
  },
  "hooks": {
    "PreCommit": [
      { "matcher": "*",
        "hooks": [
          { "type": "command", "command": "./scripts/secret-scan.sh" },
          { "type": "command", "command": "./scripts/audit-log.sh" }
        ]
      }
    ]
  }
}

Decisions: Centralize MCP tokens in a vault, require human approval for Write, ship a corporate plugins/ pack.

🌍 Open-source / community

Optimize for contributors who don't know your stack.

Ship a CLAUDE.md with onboarding script.
Add docs/onboarding.md linked from the README.
Provide a bootstrap.md command that runs npm i && npm test.
Mark settings.local.json in .gitignore so forks stay clean.

Bottom line: Same skeleton, different dials. Tighten permissions as team size and risk grow.

Anatomy of a Single Unit — A Skill

A "skill" is a self-contained capability folder.

skills/code-review/
├── SKILL.md         # what it does + when it activates
├── scripts/
│   └── analyze.sh   # executable automation
├── references/
│   └── style.md     # loaded on demand
└── assets/
    └── template.md  # static files

<!-- skills/code-review/SKILL.md -->
---
name: code-review
description: Activates when user asks to review code, audit a PR, or check quality.
triggers: ["review", "audit", "lint", "quality"]
---
Use scripts/analyze.sh to diff and lint. Reference references/style.md for conventions.

🧪 Try this: Ask Claude "review my last commit" — the skill auto-activates.

Lifecycle / Hook Events

Event	Fires when	Common use
`PreToolUse`	Before any tool call	Block dangerous commands, secret scan
`PostToolUse`	After every tool call	Auto-lint, run tests
`SessionStart`	Claude session opens	Load project context, env summary
`SessionEnd`	Session closes	Save summary to `docs/sessions/`
`PreCommit`	Before a git commit	Secret detection, policy checks
`Notification`	Special events	Slack / webhook alerts

Common Patterns & Recipes

Pattern 1 — Auto-lint after every write

"PostToolUse": [
  { "matcher": "Write|Edit",
    "hooks": [{ "type": "command", "command": "npm run lint -- --fix" }] }
]

Pattern 2 — Block secrets before commit

#!/usr/bin/env bash
# scripts/secret-scan.sh
if git diff --cached | grep -E "(api[_-]?key|secret|password)\s*=" ; then
  echo "❌ Possible secret detected. Commit blocked."
  exit 1
fi

Pattern 3 — Specialized subagent (`agents/code-reviewer.yml`)

name: code-reviewer
description: Reviews PRs against project conventions.
model: claude-opus-4
tools: [Read, Bash, WebSearch]
system_prompt: |
  You are a strict senior reviewer. Follow CLAUDE.md conventions.
  Output: 1) Risks  2) Missing tests  3) Concrete fixes (file:line).

Pattern 4 — Context budget guardrail

"env": {
  "MAX_THINKING_TOKENS": "100000",
  "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
}

Pattern 5 — MCP server with scoped filesystem

"filesystem": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@anthropic/mcp-filesystem", "./src", "./tests"]
}

Best Practices ✅

Iterate — start tiny, evolve as pain shows up.
Document skills — future-you will forget what they do.
Modular skills — one job per skill.
Secrets in env vars, never in settings.json.
Test hooks locally before committing.
Compact context at 70–80 % to keep responses sharp.

Anti-Patterns ❌

One mega-skill that does everything.
Hard-coded API tokens in .mcp.json.
Permissive allow: ["*"] in production repos.
Editing settings.json without telling the team.
Skipping CLAUDE.md ("Claude will figure it out") — it won't.

Troubleshooting

Symptom	Likely cause	Fix
Claude ignores conventions	`CLAUDE.md` too long or vague	Trim to ≤ 200 lines, use bullets
Hooks not firing	Wrong `matcher` regex	Test with `matcher: "*"` first
MCP server fails to start	Missing env var	`echo $GITHUB_TOKEN` to verify
Context fills too fast	No autocompact	Set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`
Skill never activates	Trigger words mismatch	Add synonyms to `triggers:` list
Permission denied on write	Sandbox blocked path	Add path to `allow` or move into workspace

Starter Template (full, copy-paste)

my-project/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json     # gitignored
│   └── commands/
│       ├── review.md
│       ├── deploy.md
│       ├── test-all.md
│       └── bootstrap.md
├── skills/
│   ├── code-review/
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   ├── references/
│   │   └── assets/
│   ├── text-writer/
│   │   └── SKILL.md
│   ├── security-audit/
│   │   └── SKILL.md
│   └── refactor/
│       └── SKILL.md
├── agents/
│   ├── code-reviewer.yml
│   ├── test-writer.yml
│   ├── security-auditor.yml
│   └── devops-sre.yml
├── plugins/
│   ├── manifest.json
│   └── my-plugin/
├── .mcp.json
├── .env.example
├── .gitignore
└── README.md

.gitignore essentials:

.claude/settings.local.json
.env
.env.local
node_modules/

Glossary

Agent / Subagent — A specialized Claude persona with its own prompt and tools.
CLAUDE.md — A markdown file Claude reads first; the project's "memory".
Hook — A shell command Claude runs automatically on lifecycle events.
MCP (Model Context Protocol) — Anthropic's open protocol that lets Claude talk to external tools.
Plugin — A bundled, shareable pack of skills/commands/hooks.
Skill — A reusable workflow folder Claude auto-activates by trigger words.
Slash command — A user-defined shortcut like /review defined in .claude/commands/.
PreToolUse / PostToolUse — Hook events firing before/after a tool call.

TL;DR​

Why this matters​

The Big Picture​

Core Components​

Step-by-Step Setup​

1. Install Claude Code​

2. Initialize in your project​

3. Create your CLAUDE.md (project memory)​

4. Add shared settings — .claude/settings.json​

5. Wire up external tools — .mcp.json​

6. Add a custom slash command — .claude/commands/review.md​

Variants for Different Team Settings​

👤 Solo developer (the minimalist)​

👥 Small team (2–10)​

🏢 Enterprise / regulated​

🌍 Open-source / community​

Anatomy of a Single Unit — A Skill​

Lifecycle / Hook Events​

Common Patterns & Recipes​

Pattern 1 — Auto-lint after every write​

Pattern 2 — Block secrets before commit​

Pattern 3 — Specialized subagent (agents/code-reviewer.yml)​

Pattern 4 — Context budget guardrail​

Pattern 5 — MCP server with scoped filesystem​

Best Practices ✅​

Anti-Patterns ❌​

Troubleshooting​

Starter Template (full, copy-paste)​

Glossary​

Further Reading​