Project Structure

Recommended Layout

your-project/
├── .claude/
│   ├── settings.json             # shared team settings (commit this)
│   ├── settings.local.json       # personal overrides (gitignore this)
│   ├── CLAUDE.md                 # project instructions (commit this)
│   ├── CLAUDE.local.md           # personal instructions (gitignore this)
│   ├── rules/                    # path-scoped instruction files
│   │   ├── api.md                # rules for src/api/**
│   │   ├── testing.md            # rules for **/*.test.ts
│   │   └── frontend/
│   │       └── components.md     # rules for src/components/**
│   ├── skills/                   # custom slash commands
│   │   ├── deploy/
│   │   │   ├── SKILL.md
│   │   │   └── deploy.sh
│   │   └── new-feature/
│   │       └── SKILL.md
│   ├── agents/                   # custom subagents
│   │   ├── code-reviewer.md
│   │   └── frontend-specialist.md
│   └── commands/                 # legacy (prefer skills/ instead)
│       └── format.md
├── .mcp.json                     # MCP server config (commit this)
├── CLAUDE.md                     # alternative location (commit this)
├── CLAUDE.local.md               # alternative personal location (gitignore)
├── src/
├── tests/
├── package.json
├── README.md
└── .gitignore

User Config Directory

~/.claude/
├── settings.json                 # applies to all projects
├── CLAUDE.md                     # personal instructions for all projects
├── rules/                        # user-level path-scoped rules
├── skills/                       # reusable skills across projects
├── agents/                       # reusable subagents across projects
├── keybindings.json              # custom keyboard shortcuts
├── statusline.py                 # custom status line script
└── projects/                     # session history (auto-managed)
    └── <project-hash>/
        ├── sessions.jsonl        # conversation transcripts
        └── memory/               # auto memory files
            ├── MEMORY.md         # memory index
            └── *.md              # individual memory files

.gitignore Entries

# Claude Code — never commit these
.claude/settings.local.json
CLAUDE.local.md
.claude.local.json
.claude/projects/

Rules File Format

.claude/rules/api.md:

---
paths:
  - "src/api/**/*.ts"
  - "src/routes/**"
---

# API Rules

- Validate all input with Zod schemas
- Use the standard error shape: `{ error: string, code: string }`
- All handlers must be async
- Return 400 for validation errors, 500 for unexpected errors
- Add OpenAPI JSDoc to every route handler

.claude/rules/testing.md:

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---

# Testing Rules

- Use Vitest (not Jest)
- Prefer `it.each` for data-driven tests
- Mock only external services — never mock internal modules
- Each test file should be self-contained

Two CLAUDE.md Location Options

Both are valid and loaded. Use whichever fits your team’s convention:

Option A: ./CLAUDE.md           (project root)
Option B: ./.claude/CLAUDE.md   (inside .claude/)

If both exist, both are loaded. Avoid duplication.

Minimal Starter Setup

# 1. Initialize CLAUDE.md
claude -p "/init"

# 2. Create settings
mkdir -p .claude
cat > .claude/settings.json << 'EOF'
{
  "permissions": {
    "allow": ["Bash(npm *)", "Bash(git *)"]
  }
}
EOF

# 3. Gitignore personal files
echo '.claude/settings.local.json' >> .gitignore
echo 'CLAUDE.local.md' >> .gitignore

🧠 Quick Recall

• Trick: “.claude/ is the project’s brain: settings, skills, agents, hooks.”

👨‍🏫 Teach It

• Show: tour a mature repo’s .claude/ directory tree.
• They’ll trip on: settings.local.json is gitignored — personal, not shared.

---

Learning path: ⬅ 18-memory-real-examples.md · Index · ➡ 20-skills.md