Claude Project Structure Guide

your-project/ — full structure

your-project/ ├── CLAUDE.mdcommitted ├── CLAUDE.local.mdgitignored ├── .claude/ │ ├── settings.jsoncommitted │ ├── settings.local.jsongitignored │ ├── agents/ │ │ ├── code-reviewer.md │ │ └── security-auditor.md │ ├── commands/ │ │ ├── deploy.md │ │ ├── fix-issue.md │ │ └── review.md │ ├── skills/ │ │ └── pdf-parser/ │ │ └── SKILL.md │ └── rules/ │ ├── api-conventions.md │ ├── code-style.md │ └── testing.md ├── src/ ├── package.json └── ...

The Structure

your-project/ ├── CLAUDE.md → Team instructions — commit to git ├── CLAUDE.local.md → Personal overrides — gitignored └── .claude/ → Claude Code config folder ├── settings.json → Permissions & MCP config — commit to git ├── settings.local.json → Personal permissions — gitignored ├── agents/ → Subagent personas — isolated context ├── commands/ → Custom slash commands ├── skills/ → Auto-invoked workflow packages └── rules/ → Modular instruction files

Agents

Each agent is a markdown file. Define a sub-agent persona with its own system prompt, model preference, and tool restrictions.

Location: .claude/agents/code-reviewer.md

code-reviewer.md
---
name: code-reviewer
description: Specialized code reviewer for bugs and security issues before merging.
tools: Read, Glob, Grep, Bash
model: sonnet
---

You are a senior code reviewer.

Focus on:
- Correctness and edge cases
- Security vulnerabilities (XSS, injection, auth bypass)
- Performance bottlenecks
- Code readability and maintainability

Rules:
- Be CONCISE. No fluff.
- Flag CRITICAL, WARNING, or SUGGESTION. Only CRITICAL blocks merge.

The agent frontmatter supports these fields:

name	display name
tools	which tools the agent can access
model	sonnet, opus, or haiku
description	tells Claude when to auto-invoke this agent
maxTurns	max steps before stopping

Commands

Put a file in .claude/commands/ and it becomes a slash command. No config, no wiring.

Location: .claude/commands/deploy.md

deploy.md
# Deploy to Production

To Deploy, execute EXACTLY these steps:

1. Run the full test suite
   npm run test
2. Build the project
   npm run build
3. Deploy via CLI
   npx vercel --prod
4. Verify the deployment at $DEPLOY_URL

Usage: type /deploy in the CLI and Claude handles the rest.

Use $ARGUMENTS to pass in flags from the CLI prompt.

Hooks

Hooks let Claude automatically run scripts before or after every action.

Location: .claude/settings.json (hooks section)

settings.json (hooks)
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run test -- --changed"
          }
        ]
      }
    ]
  }
}

Claude Code hook events: PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact. Use matcher to target specific tools (e.g. Bash, Write, Edit).

Rules

Instead of one giant CLAUDE.md, break standards into modular files in the rules/ directory. Each markdown file auto-loads alongside your CLAUDE.md.

.claude/rules/
# rules/api-conventions.md

→ Always use camelCase for variables, PascalCase for components
→ Every API endpoint must validate inputs
→ Return { data, error, status } from all endpoints
→ Always throw custom AppError, never raw Error

# rules/testing.md

→ Write tests before implementation (TDD)
→ Minimum 80% code coverage for new code
→ Use describe/it blocks, no test() syntax
→ Mock external services, never call real APIs in tests

Each file inside .claude/rules/ stays focused on one concern. The team member who owns API conventions edits their file; the person who owns testing standards edits theirs.

Skills

A skill is like a command, but Claude auto-detects when it's relevant and loads it automatically. You can also invoke them manually.

Location: .claude/skills/[name]/SKILL.md

skills/pdf-parser/SKILL.md
---
name: pdf-parser
description: Parse PDF files and extract text. Used when PDF processing is needed.
disable-model-invocation: false
---

Steps:
1. Load the PDF using pdf-parse library
2. Extract all text content page by page
3. Return structured data with page numbers
4. Handle errors for corrupted or encrypted files

Key difference from commands: skills can bundle supporting files alongside the SKILL.md file. Commands are single files. Skills are packages.

Personal skills go in ~/.claude/skills/ and are available across all your projects.

CLAUDE.md

The most important file. Loaded every single session. Put your team's rules, conventions, and architecture here. Commit it to git so the whole team gets the same instructions.

Need personal overrides that shouldn't affect the team? Create CLAUDE.local.md at the project root — it's gitignored and loaded alongside CLAUDE.md for your machine only.

Keep it under 200 lines. Anything longer eats context and adherence drops.

CLAUDE.md
# Project Config

- Stack: Next.js 14 + TypeScript + Tailwind
- Build: npm run build
- Test: npm run test
- Lint: npm run lint

# Conventions

- Use function components only
- Explicitly type all props with TypeScript interfaces
- Use CSS Modules (not inline styles)

# Architecture

- /app → App Router pages
- /components → Reusable UI components
- /lib → Utilities and helpers

# Don'ts

- Don't use console.log — use custom logger
- Don't modify auth code without review
- Never delete existing tests
- Never add a dependency without checking bundle size

settings.json

Controls permissions, MCP servers, and hook configs. This is how you lock things down. Commit settings.json to git for shared team config.

For personal overrides — like allowing extra tools only on your machine — use .claude/settings.local.json. It has the same structure and is gitignored automatically.

Location: .claude/settings.json

settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  },
  "mcpServers": {
    "github": {
      "type": "url",
      "url": "https://mcp.github.com/sse"
    },
    "linear": {
      "type": "url",
      "command": "npx @anthropic/linear-mcp-server"
    }
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "npm run lint && npm run test" }]
      }
    ]
  }
}

Quick Setup

Copy-paste these commands to scaffold the entire folder structure in seconds:

terminal
# Create the .claude folder structure
mkdir -p .claude/agents .claude/commands .claude/skills .claude/rules

# Shared files — commit these to git
touch CLAUDE.md
touch .claude/settings.json
touch .claude/agents/code-reviewer.md
touch .claude/agents/security-auditor.md
touch .claude/commands/deploy.md
touch .claude/commands/fix-issue.md
touch .claude/commands/review.md
touch .claude/rules/api-conventions.md
touch .claude/rules/code-style.md
touch .claude/rules/testing.md
mkdir -p .claude/skills/pdf-parser
touch .claude/skills/pdf-parser/SKILL.md

# Personal overrides — already gitignored by Claude Code
touch CLAUDE.local.md
touch .claude/settings.local.json

# Initialize Claude Code in the project
claude /init

Pro tip: commit this to your repo so your whole team gets the same setup from day one.