Mastering Claude Code Setup

A comprehensive guide to setting up Claude Code for maximum effectiveness on any project. Covers CLAUDE.md, skills, hooks, auto memory, settings, agent teams, and workflow patterns.

Table of Contents

1. Project Rules (CLAUDE.md)
2. Skills
3. Agent Teams
4. Hooks
5. Auto Memory
6. Settings
7. Workflow Patterns
8. Setup Checklist

---

1. Project Rules (CLAUDE.md)

CLAUDE.md is the single most important file for Claude Code. It's loaded into every conversation and tells Claude how to work with your project.

Where to Put It

project-root/
├── CLAUDE.md          ← Project-wide rules (checked into git)
└── .claude/
    └── CLAUDE.md      ← Personal rules (not in git)

• CLAUDE.md in root: Shared with the team via git
• .claude/CLAUDE.md: Your personal preferences (gitignored)

What to Include

Quick Context (most important)

## Quick Context
- **Stack**: Python 3.12 + FastAPI + PostgreSQL 16
- **Run**: `uvicorn app.main:app --reload`
- **Test**: `pytest tests/ -x`
- **Build**: `docker compose build`
- **Lint**: `ruff check . && mypy .`

This alone saves Claude from guessing your stack and commands.

Coding Standards

## Coding Standards

### Import Order
1. Standard library
2. Third-party
3. Framework
4. Relative

### Error Handling
- Use domain-specific exceptions, not generic Exception
- Always handle external I/O with try/except
- Log errors with context

Module Boundaries (for teams)

## Module Boundaries

| Domain | Directories | Notes |
|--------|------------|-------|
| API | src/api/ | Route handlers |
| Models | src/models/ | SQLAlchemy models |
| Services | src/services/ | Business logic |

**Shared files:** src/config.py, docker-compose.yaml

Verification Commands

## Verification
- **Tests**: `pytest tests/ -x`
- **Lint**: `ruff check src/`
- **Type check**: `mypy src/`
- **Build**: `docker compose build`

Anti-Patterns

• Too long: CLAUDE.md over 500 lines loses effectiveness (use skills for detailed rules)
• Too vague: "Write good code" is useless — be specific
• Duplicate info: Don't repeat what's already in your README or docs
• Outdated commands: Keep verification commands current

---

2. Skills

Skills are reusable prompts that Claude loads on demand. They live in .claude/skills/<name>/SKILL.md.

Structure

.claude/skills/
├── code-review/
│   ├── SKILL.md              # Skill definition
│   └── references/           # Detailed checklists (loaded on demand)
│       ├── security.md
│       └── quality.md
├── handover/
│   └── SKILL.md
└── skill-creator/
    └── SKILL.md

Creating a Skill

Every skill needs a SKILL.md with YAML frontmatter:

---
name: code-review
description: Multi-pass code review with P0-P3 severity. Use when user says "code review", "review my code", or "pre-commit check".
---

# Code Review

[Skill instructions here...]

Rules: - Directory: kebab-case (code-review, not codeReview) - File: exactly SKILL.md (case-sensitive) - Name must match directory name - Description must include trigger phrases

Progressive Disclosure (3 Levels)

Level	Where	Size	When Loaded
1	YAML frontmatter	~100 tokens	Every conversation
2	SKILL.md body	<5,000 tokens	When skill invoked
3	references/ files	Unlimited	On demand during execution

Keep Level 1 minimal — it's always in context. Put detailed checklists in references/.

Invoking Skills

/code-review                 # Invoke by name
/code-review src/services/   # With arguments

Keeping Docs in Sync

When creating or deleting a skill, update reference docs too:

1. Create/edit .claude/skills/<name>/SKILL.md
2. Update SKILLS_QUICK_REFERENCE.md (if project has one)
3. Update CLAUDE.md workflow section (if skill changes workflows)

Add this rule to your CLAUDE.md to enforce it:

### Adding/Modifying Skills
When creating, renaming, or deleting a skill:
1. Create/edit the SKILL.md with YAML frontmatter
2. Update SKILLS_QUICK_REFERENCE.md
3. Keep both docs in sync

Advanced: Skills That Spawn Agent Teams

A skill can instruct Claude to create an agent team for parallel execution:

---
name: agent-team-review
description: Parallel code review with agent teammates.
---

The skill body defines roles (security reviewer, quality reviewer, etc.) and Claude spawns a team. Use for tasks that are naturally parallel and well-scoped.

---

3. Agent Teams

Agent Teams let multiple Claude agents work in parallel on different parts of your project.

Enable

In ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

When to Use

• Large features touching 3+ independent modules
• Parallel work (frontend + backend, code + tests)
• Bulk operations across many files

Key Patterns

1. Define module boundaries in CLAUDE.md so agents know their scope
2. List shared files that need coordination
3. Include verification commands so agents can self-check
4. Keep teams small (2-4 agents)

Custom Agents (YAML Frontmatter)

Define specialized agents in .claude/agents/<name>.md with YAML frontmatter:

---
name: builder
description: Implementation agent for writing code
tools: Read, Write, Edit, Bash, Glob, Grep
model: sonnet
---

Key fields: name, description, tools (restricts capabilities), model (opus/sonnet/haiku), hooks (agent-specific hook overrides).

See Agents for detailed patterns and agent-specific hooks.

---

4. Hooks

Hooks are shell commands that run before or after Claude uses a tool.

Events (13 total)

Claude Code supports 13 hook events across the full lifecycle:

Category	Events	Common Use
Lifecycle	Setup, SessionStart, SessionEnd	Environment setup, context loading, cleanup
Conversation	UserPromptSubmit	Input validation, prompt logging
Tool Execution	PreToolUse, PostToolUse, PostToolUseFailure	Security, formatting, lint validation, error logging
Permission	PermissionRequest	Auto-allow safe operations
Notification	Notification	Alerts, announcements
Completion	Stop, SubagentStart, SubagentStop	Summaries, sub-agent tracking
Maintenance	PreCompact	Transcript backup before compaction

The most commonly used are PreToolUse, PostToolUse, and Stop.

Configuration

In .claude/settings.local.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/security-check.py"
          }
        ]
      }
    ]
  }
}

How They Work

• Hooks receive JSON on stdin (tool name, inputs)
• Exit 0 = allow, Exit 2 = block (with message)
• Any other exit = allow (fail-open)
• Keep hooks fast (<1 second)

Useful Hooks

Hook	Event	Purpose
security-check.py	PreToolUse	Block secrets/API keys in code
protect-files.py	PreToolUse	Block edits to lock files, .env
permission-auto-allow.py	PermissionRequest	Auto-allow safe read-only commands
format-on-edit.py	PostToolUse	Auto-format after edits
lint-on-edit.py	PostToolUse	Lint validation gate (blocks on errors)
stop-summary.py	Stop	Log task completion summary
log-commands.sh	PreToolUse	Audit trail for bash commands

Validation Gate Pattern

Use PostToolUse hooks as quality gates — if lint or type check fails, the hook blocks with exit 2 and Claude must fix the issue before continuing:

Claude writes file → [PostToolUse: lint-on-edit.py] → Lint fails → Exit 2 (block)
                                                     → Lint passes → Exit 0 (allow)

This creates a tight feedback loop where code quality is enforced automatically.

See Hooks for all 13 events and scripts.

---

5. Auto Memory

Auto Memory lets Claude remember insights across sessions. It's stored per-project and loaded automatically.

How It Works

• Location: ~/.claude/projects/<path>/memory/MEMORY.md
• Loaded into system prompt every conversation
• Max ~200 lines — keep it concise
• Claude reads and updates it as it learns

What to Store

Good for memory: - Project setup commands and gotchas - Patterns that worked or failed - Configuration quirks - Common errors and their fixes

Not for memory (put in CLAUDE.md instead): - Coding standards - Module boundaries - Verification commands - Architectural rules

Structure

# Project Memory

## Setup
- Docker on port 8070, database on 5433
- Module update: `docker exec app odoo -d db -u module --stop-after-init`

## Patterns Learned
- Translation context: use `model_terms:` for view strings
- Wizard files go in models/ folder, not wizard/
- Reports: hardcode strings in output, don't use _()

## Configuration
- Settings: env vars go under "env" key, not top-level

Topic Files

For detailed notes, create separate files and link from MEMORY.md:

memory/
├── MEMORY.md           ← Always loaded (~200 lines max)
├── debugging.md        ← Linked from MEMORY.md
└── patterns.md         ← Linked from MEMORY.md

---

6. Settings

Pre-Approved Commands

Skip permission prompts for safe commands in .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(npm test*)",
      "Bash(pytest *)",
      "Bash(ls *)",
      "Bash(mkdir *)"
    ],
    "deny": []
  }
}

Settings Files

File	Scope	Git
~/.claude/settings.json	Global (all projects)	N/A
.claude/settings.json	Project (shared)	Yes
.claude/settings.local.json	Project (personal)	No

Priority: local > project > global

Recommended Starting Commands

See Templates for a complete starter.

---

7. Workflow Patterns

Pattern 1: CLAUDE.md + Skills

CLAUDE.md           → Always-on rules (coding standards, quick context)
Skills              → On-demand workflows (code review, report generation)

Rule of thumb: If it applies to every conversation, put it in CLAUDE.md. If it's a specific workflow, make it a skill.

Pattern 2: Progressive Disclosure

YAML frontmatter    → Tiny (always loaded, ~100 tokens)
SKILL.md body       → Medium (loaded when invoked, <5K tokens)
references/         → Large (loaded on demand, unlimited)

Pattern 3: Hooks + Pre-Approved Commands

Hooks               → Automated guardrails (block secrets, protect files)
Pre-approved        → Reduce friction (skip prompts for safe commands)

Together they create a "safe by default, fast by permission" workflow.

Pattern 4: Session Handover

End of session      → /handover (generates HANDOVER.md)
Start of session    → "Read .claude/handover/HANDOVER.md and resume"

Preserves context across sessions without repeating yourself.

Pattern 5: Memory + CLAUDE.md

CLAUDE.md           → Prescriptive rules ("always do X")
Auto Memory         → Descriptive learnings ("we discovered Y")

CLAUDE.md is authored by you. Memory is authored by Claude from experience.

Pattern 6: Skills + Agent Teams

1. Create a skill that defines parallel review/audit roles
2. Skill instructs Claude to spawn an agent team
3. Each teammate handles one dimension independently
4. Lead merges results into unified output

Example: /agent-team-review spawns 3-4 specialized reviewers (security, quality, translations) that work in parallel and produce a merged report.

Pattern 7: Skill Lifecycle

1. Notice you're explaining the same thing 3+ times
2. Create a skill for that workflow
3. Update SKILLS_QUICK_REFERENCE.md (keep docs in sync!)
4. Iterate based on usage

Pattern 8: Post-Task Review + Commit Prompt

1. Claude finishes a task that modified files
2. Runs git status + git diff --stat automatically
3. Presents summary of all changes
4. Asks: "Want me to commit and push?"
5. If yes: creates commit with proper message, pushes
6. If no: leaves changes unstaged

Add this to your CLAUDE.md to enforce it:

### After Completing a Task
After finishing any task that modifies files, ALWAYS:
1. Run `git status` and `git diff --stat` to show what changed
2. Present a brief summary of all changes
3. Ask the user: "Want me to commit and push these changes?"

Git safety rules:
- NEVER `git push --force` without explicit user permission
- NEVER commit or push without asking the user first
- NEVER run destructive git commands (`reset --hard`, `clean -f`) without permission
- Always show what will be committed before committing

---

8. Status Lines

Status lines customize what Claude Code displays in its header bar. Configure in ~/.claude/settings.json:

{
  "statusLine": "echo 'branch:$(git branch --show-current) | model:$CLAUDE_MODEL'"
}

Common status line data: - Git branch and status - Current model name - Working directory - Custom project metadata

Status lines run a shell command and display the output. Keep them fast (<500ms).

---

9. Output Styles

Output styles control how Claude formats responses. Place style files in .claude/output-styles/:

.claude/output-styles/
├── concise.md          # Minimal output for experienced devs
├── table-based.md      # Everything in markdown tables
└── bullet-points.md    # Nested bullet lists

Invoke with the --output-style flag or configure in settings. Useful for teams that prefer consistent formatting across sessions.

---

10. Setup Checklist

Essential (do first)

• Create CLAUDE.md with Quick Context section
• Add verification commands (test, lint, build)
• Add coding standards relevant to your stack
• Set up .claude/settings.local.json with pre-approved commands

Recommended (high value)

• Create /code-review skill
• Create /handover skill
• Add security-check.py hook
• Seed Auto Memory with project setup notes

Optional (nice to have)

• Enable Agent Teams (for large multi-module projects)
• Define custom agents with YAML frontmatter
• Add protect-files.py hook
• Add format-on-edit.py hook
• Add lint-on-edit.py hook (validation gate)
• Configure a status line
• Create project-specific skills

Quick Reference

Feature	Location	Loaded
CLAUDE.md	./CLAUDE.md	Every conversation
Skills	.claude/skills/<name>/SKILL.md	On invocation
Custom Agents	.claude/agents/<name>.md	When agent spawned
Hooks	.claude/hooks/*.py	On matching event
Memory	~/.claude/projects/.../memory/MEMORY.md	Every conversation
Settings	.claude/settings.local.json	Every conversation
Status Line	~/.claude/settings.json → statusLine	Always visible
Output Styles	.claude/output-styles/*.md	On selection

---

Sources

• Claude Code Documentation
• Anthropic Skills Repository
• Real-world project setups and learnings