Claude Code Setup Guides

Modular, focused guides for setting up Claude Code projects from scratch. Each guide is optimized for use in plan mode and during project initialization.

---

Quick Start

New to Claude Code? Follow this path:

1. setup/01-prerequisites.md (5 min)

   • Verify installation and system requirements
   • Understand configuration structure

2. setup/02-global-configuration.md (10 min)

   • Configure user-level settings
   • Enable essential plugins

3. setup/03-project-structure.md (15 min)

   • Set up project directories
   • Create CLAUDE.md and permissions

4. setup/04-hooks-and-safety.md (10 min)

   • Add safety hooks
   • Protect against destructive operations

5. setup/05-mcp-servers.md (10 min, optional)

   • Connect external tools
   • Enable documentation lookup

6. setup/06-plugins-and-skills.md (15 min, optional)

   • Enable advanced features
   • Create custom skills

Total time: 30-60 minutes depending on tier chosen

---

Guide Organization

📁 setup/

Step-by-step setup guides (follow in order):

Guide	Purpose	Time
01-prerequisites.md	System requirements & structure	5 min
02-global-configuration.md	User-level settings	10 min
03-project-structure.md	Project initialization	15 min
04-hooks-and-safety.md	Safety configuration	10 min
05-mcp-servers.md	External integrations	10 min
06-plugins-and-skills.md	Advanced features	15 min
07-agents-and-validators.md	Specialized agents & validation	30-45 min

New: 07-agents-and-validators.md - Create focused, self-validating agents with automated quality checks. Learn the three-layer architecture: Orchestrator → Specialized Agents → Validators. Build trusted automation for data processing, code generation, and complex workflows.

---

📁 reference/

Quick reference guides (use as needed):

Guide	Purpose
verification-checklist.md	Verify setup at each stage
troubleshooting.md	Common issues and solutions

---

📁 templates/

Ready-to-use templates:

Template	Purpose
setup-tiers.md	Complete setup tiers (Minimal/Standard/Enterprise)
agent-template.md	Specialized agent templates
validator-template.py	Validator script template
hooks/validators/	Ready-to-use validators (CSV, JSON, code quality)

---

Setup Tiers

Choose based on your project needs:

🟢 Minimal (5 min)

For: Personal projects, prototyping

• Basic structure + CLAUDE.md
• Permissive permissions
• No hooks or MCP

Quick setup:

mkdir -p .claude
# Create minimal settings
# Create basic CLAUDE.md

Full template →

---

🟡 Standard (30 min)

For: Professional development, teams

• Complete structure
• Safety hooks (3)
• MCP documentation
• Granular permissions

Quick setup:

# Use setup script from template
bash setup-standard.sh

Full template →

---

🔴 Enterprise (60 min)

For: Production, regulated industries

• Full security suite
• Advanced hooks (6+)
• Compliance-ready
• Restrictive permissions
• SECURITY.md

Quick setup:

# Use setup script from template
bash setup-enterprise.sh

Full template →

---

🤖 Specialized Agents & Validators (New!)

Build trusted automation with self-validating agents.

The agents & validators pattern enables you to create complex, reliable workflows by combining:

• Specialized Agents - Each does ONE thing perfectly (normalize CSVs, categorize transactions, generate charts)
• Automated Validators - Verify output quality automatically (format checks, balance calculations, schema validation)
• Orchestrators - Chain agents into multi-stage pipelines

Hook Types:

• PreToolUse - Block dangerous operations before they run (prevent rm -rf, invalid paths)
• PostToolUse - Validate output after tool completes (CSV format, JSON schema, image size)
• Stop - Final comprehensive check when agent finishes (type checking, linting, integration tests)

Real-World Example: Process monthly bank statements through a 5-agent pipeline:

Raw CSVs → Normalize → Categorize → Merge → Visualize → Dashboard
           [validator] [validator] [validator] [validator] [validator]

Each agent self-corrects if validation fails. Fully automated, fully tested.

Get Started: setup/07-agents-and-validators.md (30-45 min)

---

Common Use Cases

"I'm starting a new React project"

1. 03-project-structure.md - Basic setup
2. 04-hooks-and-safety.md - Add safety
3. 05-mcp-servers.md - Add context7 + playwright
4. 06-plugins-and-skills.md - Enable frontend-design

---

"I need enterprise security"

1. Follow full setup path (01-06)
2. Use templates/setup-tiers.md
3. Create SECURITY.md
4. Enable all security hooks

---

"Something's not working"

1. reference/verification-checklist.md - Diagnose issues
2. reference/troubleshooting.md - Find solutions

---

"I want to customize hooks"

1. setup/04-hooks-and-safety.md - Learn syntax
2. templates/hooks/ - Copy examples
3. Modify patterns for your needs

---

"I need specialized, self-validating agents"

Use Cases:

• Data processing pipelines (CSV normalization, categorization, merging)
• Code generation with quality checks (type checking, linting, testing)
• Multi-stage workflows (normalize → categorize → merge → visualize → dashboard)
• File format validation (CSV, JSON, XML schema enforcement)

Three-Layer Architecture:

1. Orchestrator Command - Coordinates workflow, chains agents sequentially
2. Specialized Agents - ONE purpose each, isolated contexts, embedded validators
3. Validators - Deterministic checks, clear errors, auto-correction

Setup Steps:

1. setup/07-agents-and-validators.md - Complete guide (30-45 min)
2. templates/agent-template.md - Copy agent template
3. templates/validator-template.py - Copy validator template
4. templates/hooks/validators/ - Use ready-made validators

Philosophy: Focused Agent + Specialized Validation = Trusted Automation

Real Example: Financial data pipeline with 5 specialized agents (normalize, categorize, merge, visualize, dashboard) - each with its own validator, fully automated and self-correcting.

---

Quick Commands

# Validate configurations
cat ~/.claude/settings.json | jq .
cat .claude/settings.local.json | jq .
cat .mcp.json | jq .

# Test setup
claude "What is this project about?"          # Test CLAUDE.md
claude "Run npm install"                      # Test permissions
claude "Run rm -rf test"                      # Test hooks

# Check status
ls -la .claude/                               # Project structure
ls -la .claude/hookify.*.local.md            # Hooks
git status --ignored | grep ".claude"         # Git ignore

# Test agents and validators
echo '{"tool_input": {"file_path": "test.csv"}}' | \
  python3 .claude/hooks/validators/csv-validator.py  # Test validator
cat .claude/hooks/validators/validator.log    # Check logs
claude "Use csv-normalize-agent to process data.csv"  # Test agent

# Run diagnostic
bash templates/diagnostic.sh                  # Full diagnostic

---

File Structure Overview

Global (~/.claude/)

~/.claude/
├── settings.json              # Plugin settings
├── agents/                    # Agent definitions
├── plugins/                   # Plugin cache
└── projects/                  # Project metadata

Project (/.claude/)

project/
├── .claude/
│   ├── settings.local.json    # Project permissions
│   ├── hookify.*.local.md     # Safety hooks
│   ├── agents/                # Specialized agent definitions
│   ├── hooks/
│   │   └── validators/        # Validation scripts (Python)
│   ├── commands/              # Orchestrator commands
│   └── skills/                # Custom skills
├── CLAUDE.md                  # Project context
└── .mcp.json                  # MCP servers

---

Key Concepts

Concept	Description	File
Global	Applies to all projects	~/.claude/settings.json
Project	Applies to one project	.claude/settings.local.json
Hooks	Safety rules (warn/block)	.claude/hookify.*.local.md
MCP	External tool integration	.mcp.json
Skills	Reusable prompt templates	.claude/skills/*/SKILL.md
Agents	Specialized single-purpose workers	.claude/agents/*.md
Validators	Automated output verification	.claude/hooks/validators/*.py

---

Best Practices

✅ Do:

• Start with Standard tier
• Use hooks for safety
• Keep CLAUDE.md updated
• Version control CLAUDE.md
• Gitignore .local.* files
• Create single-purpose agents
• Add validators to all agents
• Log validator operations

❌ Don't:

• Commit .local.* files
• Use permissive wildcards in production
• Skip verification checklist
• Hardcode secrets in CLAUDE.md
• Disable all hooks
• Create multi-purpose agents
• Skip validation in pipelines

---

Getting Help

Can't find what you need?

1. Check reference/troubleshooting.md
2. Run diagnostic: bash templates/diagnostic.sh
3. Enable debug logging
4. Check logs: tail -f ~/.claude/debug/*.log
5. Report issue: https://github.com/anthropics/claude-code/issues

Resources:

• Documentation: https://docs.claude.ai/claude-code
• GitHub: https://github.com/anthropics/claude-code
• Discord: https://discord.gg/claude-code

---

Contributing

Found an issue or want to improve a guide?

1. Report in issues
2. Submit a pull request
3. Share your custom templates

---

License

These guides are provided as-is for Claude Code users.

---

Ready to start? → setup/01-prerequisites.md