FoundryVTT/QUICKSTART.md

# Claude Code Quickstart Guide

> **Get started with Claude Code Setup in 5 minutes**
> **Version**: 3.0.0 | **Last Updated**: 2025-10-20

---

## What's Configured?

This project has **Claude Code fully configured** with:

✅ **8 MCP Servers** - Code navigation, memory, docs, automation
✅ **8 Specialized Agents** - Architecture, review, debug, security, testing
✅ **9 Slash Commands** - Analyze, review, implement, test, optimize, adr
✅ **6 Output Styles** - Concise, professional, verbose, learning, explanatory, security
✅ **6 Event Hooks** - Session lifecycle, bash, file operations, stop tracking
✅ **Complete Templates** - Extend all features easily
✅ **Automatic Status Summaries** - Every response includes tool usage details

---

## Quick Commands

### Essential Commands

```bash
/help               # Get help
/setup-info         # See full configuration
/cost               # View token usage
/rewind             # Undo changes (ESC ESC also works)
```

### Development Commands

```bash
/adr [list|view|create|update] # Manage Architectural Decision Records
/analyze [path]           # Comprehensive code analysis
/review [file-or-path]    # Code review with best practices
/implement [feature]      # Implement new features
/test [file-path]         # Run and analyze tests
/optimize [file]          # Performance optimization
/explain [file]           # Detailed code explanation
/scaffold [type] [name]   # Generate boilerplate
```

### Workflow Examples

```bash
# Quick code review
> /review src/components/

# Implement feature
> /implement user authentication with JWT

# Run tests
> /test

# Get analysis
> /analyze src/services/payment.ts
```

---

## MCP Servers (8 Available)

### 🎯 Most Useful

**Serena** - Code navigation + persistent memory
```bash
# Find code
find_symbol("UserService")
find_referencing_symbols("authenticate", "src/auth/")

# Store knowledge (survives sessions)
write_memory("adr-001-architecture", "Decision: Use microservices...")
read_memory("adr-001-architecture")
```

**Context7** - Real-time library docs
```bash
# Get current framework documentation
resolve-library-id("react")
get-library-docs("/facebook/react")
```

**Memory Graph** - Temporary session context
```bash
# Build context for current task (cleared after session)
create_entities([{name: "UserService", type: "Class"}])
create_relations([{from: "UserService", to: "AuthMiddleware"}])
```

### 🔧 Automation

**Playwright** - Browser automation
**Windows MCP** - Desktop automation
**Fetch** - Web scraping

### 💾 Databases

**Database Server** - General database queries

### 🧠 Reasoning

**Sequential Thinking** - Complex problem solving with extended thinking

---

## Agents (8 Specialized)

### How to Use

**Automatic**: Just mention the domain
```bash
> "I need to design a microservices architecture"
# → Architect agent automatically invoked
```

**Manual**: Explicitly request
```bash
> "Use the security-analyst agent to review this code"
# → Security analyst explicitly invoked
```

### Available Agents

| Agent | Use For | Keywords |
|-------|---------|----------|
| **architect** | System design, technical planning | architecture, design, scalability |
| **code-reviewer** | Code quality, best practices | review, quality, standards |
| **debugger** | Bug diagnosis, troubleshooting | debug, error, bug, issue |
| **documentation-writer** | Technical docs, README | documentation, docs, readme |
| **project-manager** | Task breakdown, coordination | project, manage, coordinate |
| **refactoring-specialist** | Code improvement, cleanup | refactor, improve, cleanup |
| **security-analyst** | Security analysis, vulnerabilities | security, vulnerability, audit |
| **test-engineer** | Testing strategy, test generation | test, testing, coverage |

---

## Output Styles (6 Available)

Change how Claude responds:

```bash
/output-style concise           # Brief, minimal explanation
/output-style professional      # Formal, business-appropriate
/output-style verbose           # Detailed, comprehensive
/output-style explanatory       # Educational insights
/output-style learning          # Interactive - Claude teaches YOU
/output-style security-reviewer # Security-focused analysis
/output-style default           # Return to standard
```

### Quick Guide

- **Quick fixes**: Use `concise`
- **Learning**: Use `learning` or `explanatory`
- **Reports**: Use `professional`
- **Deep understanding**: Use `verbose`
- **Security work**: Use `security-reviewer`

---

## Advanced Features

### Extended Thinking

For complex problems, use thinking keywords:
```bash
> "Think hard about the best database architecture"
> "Ultrathink: How should I optimize this algorithm?"
```

Levels: `think` → `think hard` → `think harder` → `ultrathink`

### Plan Mode

**Toggle**: Press `Tab` key

**Use**: Explore code safely before making changes
1. Enter plan mode (Tab)
2. Explore and understand
3. Exit plan mode (Tab)
4. Execute changes

### Checkpointing

**Access**: Press `ESC ESC` or `/rewind`

**Options**:
- Code only (keep conversation)
- Conversation only (keep files)
- Both (complete rollback)

**Retention**: 30 days

### Parallel Execution

Claude can run multiple operations simultaneously:
```bash
# Multiple file reads
> "Read src/auth/service.ts, src/auth/middleware.ts, and src/auth/utils.ts"

# Multiple agents
> "I need code review and security analysis"
```

---

## Memory System

### Three Memory Types

**1. Project Instructions (CLAUDE.md)**
- Team-shared project conventions
- Auto-loaded every session
- Location: [CLAUDE.md](CLAUDE.md)

**2. Persistent Memory (Serena)**
- Survives across sessions
- Store ADRs, lessons, patterns
```bash
write_memory("name", "content")
read_memory("name")
list_memories()
```

**3. Temporary Memory (Knowledge Graph)**
- Current session only
- Entity relationships
```bash
create_entities([...])
create_relations([...])
read_graph()
```

### When to Use What?

**Should it exist next week?**
- YES → Serena persistent memory
- NO → Knowledge graph

---

## Hooks (Automated Actions)

**5 hooks configured** - execute automatically:

| Hook | Trigger | Current Action |
|------|---------|----------------|
| session-start | Session begins | Create logs, log start |
| session-end | Session ends | Final logging |
| pre-bash | Before bash commands | Command logging |
| post-write | After file writes | Write logging, (auto-format optional) |
| user-prompt-submit | After prompt | Prompt tracking |

**Logs location**: `.claude/logs/`

---

## Creating Custom Features

### Custom Command

```bash
# 1. Copy template
cp .claude/commands/.COMMANDS_TEMPLATE.md .claude/commands/deploy.md

# 2. Edit file (add frontmatter and instructions)
---
description: Deploy application to production
argument-hint: [environment]
allowed-tools: Bash(git *:*), Bash(npm *:*), Read(*)
---

# 3. Use it
> /deploy production
```

### Custom Agent

```bash
# 1. Copy template
cp .claude/agents/.AGENT_TEMPLATE.md .claude/agents/api-tester.md

# 2. Configure frontmatter and instructions
---
name: api-tester
description: API testing and validation specialist
allowed-tools: Read(*), Bash(curl:*), Bash(npm test:*)
---

# 3. Use it
> "Use the api-tester agent to test our REST API"
```

### Custom Output Style

```bash
# 1. Copy template
cp .claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md .claude/output-styles/debugging-mode.md

# 2. Define behavior
---
name: debugging-mode
description: Systematic debugging with detailed analysis
---

# 3. Activate
> /output-style debugging-mode
```

---

## Common Workflows

### Feature Development

```bash
# 1. Architecture
> "Use architect agent to design payment integration"

# 2. Implement
> /implement Stripe payment integration

# 3. Test
> /test src/payments/

# 4. Review
> /review src/payments/

# 5. Document
> "Use documentation-writer agent to document payment flow"

# 6. Commit
> "Create git commit"

# After each step, you'll see a status summary showing:
# - What was done
# - Which agents/commands/MCP servers were used
# - Files modified
```

### Bug Fixing

```bash
# 1. Debug
> "Use debugger agent: [paste error]"

# 2. Extended thinking (for complex bugs)
> "Think hard about this race condition"

# 3. Review fix
> /review [fixed file]

# 4. Test
> /test
```

### Code Review

```bash
# 1. Standard review
> /review src/

# 2. Security check
> "Use security-analyst agent to check vulnerabilities"

# 3. Refactoring suggestions
> "Use refactoring-specialist agent for improvements"
```

### Learning Codebase

```bash
# 1. Use explanatory style
> /output-style explanatory

# 2. High-level questions
> "Explain the architecture of this project"
> "How does authentication work?"

# 3. Deep dive with Serena
> get_symbols_overview("src/core/engine.ts")
> find_symbol("Engine/initialize")

# 4. Store learnings
> write_memory("architecture-overview", "The system uses...")
```

---

## File Shortcuts

### Reference Files

Use `@` to include files in prompts:
```bash
> "Review @src/auth/service.ts"
> "Explain @src/utils/*.ts"
```

### Import in CLAUDE.md

Import additional context:
```markdown
@docs/architecture.md
@docs/coding-standards.md
```

---

## Configuration Quick Reference

### Key Files

| File | Purpose |
|------|---------|
| `.claude/settings.json` | Main configuration (shared) |
| `.claude/settings.local.json` | Personal config (not in git) |
| `.mcp.json` | MCP servers |
| `CLAUDE.md` | Project instructions |
| `.claude/agents/*.md` | Specialized agents |
| `.claude/commands/*.md` | Slash commands |
| `.claude/output-styles/*.md` | Response styles |
| `.claude/hooks/*.sh` | Automation scripts |

### Permissions

**Location**: `.claude/settings.json` → `permissions`

```json
{
  "allowed": ["Read(*)", "Write(*)", "Bash(git *:*)"],
  "ask": ["Bash(npm install:*)"],
  "denied": ["Bash(rm -rf /:*)"]
}
```

---

## Keyboard Shortcuts

- `Tab` - Toggle plan mode
- `ESC ESC` - Access checkpoints
- `Ctrl+C` - Interrupt Claude

---

## Troubleshooting

### Agent Not Working

```bash
# Check it exists
ls .claude/agents/

# Check description has keywords
cat .claude/agents/[name].md

# Try manual invocation
> "Use the [agent-name] agent to..."

# Restart Claude
```

### Command Not Found

```bash
# Check it exists
ls .claude/commands/

# List available
> /help

# Restart Claude
```

### MCP Server Failed

```bash
# Check configuration
cat .mcp.json | jq '.mcpServers'

# Test command manually
npx -y @modelcontextprotocol/server-sequential-thinking

# Check logs
cat .claude/logs/session.log
```

### Permission Denied

```bash
# Check permissions
cat .claude/settings.json | jq '.permissions'

# Add to allowed
# Edit settings.json → permissions → allowed array

# Restart Claude
```

---

## Tips & Tricks

### 🚀 Performance

1. **Use concise style** for quick tasks
2. **Parallel operations** when possible
3. **Serena symbol tools** instead of full file reads
4. **Extended thinking** only for complex problems

### 🎯 Effectiveness

1. **Start broad, then narrow** - high-level first, details later
2. **Use appropriate tools** - agents for domains, commands for workflows
3. **Leverage memory** - store ADRs, lessons, patterns
4. **Reference files** with `@` syntax

### 🔐 Security

1. **Review hooks** before using
2. **Restrict sensitive tools** in permissions
3. **Use security-analyst** for audits
4. **Never commit secrets** to CLAUDE.md

### 📈 Learning

1. **Use explanatory style** for understanding
2. **Extended thinking** for complex topics
3. **Store learnings** in Serena memory
4. **Learning style** for hands-on practice

---

## Next Steps

### New Users

1. Try basic commands: `/help`, `/setup-info`
2. Experiment with agents: "Use the [agent] agent to..."
3. Try output styles: `/output-style learning`
4. Create your first custom command

### Experienced Users

1. Set up personal `.claude/settings.local.json`
2. Create project-specific agents
3. Configure hooks for your workflow
4. Leverage MCP servers fully

### Team Setup

1. Review and customize `CLAUDE.md`
2. Add team-specific commands
3. Configure permissions
4. Share setup via git

---

## Resources

### Documentation

- **Complete Setup**: [CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md) - Full documentation
- **Templates Guide**: [.claude/TEMPLATES_README.md](.claude/TEMPLATES_README.md) - Template details
- **MCP Servers**: [MCP_SERVERS_GUIDE.md](MCP_SERVERS_GUIDE.md) - Complete MCP documentation
- **MCP Templates**: [.claude/agents/MCP_USAGE_TEMPLATES.md](.claude/agents/MCP_USAGE_TEMPLATES.md) - Copy-paste templates for agents
- **Official Docs**: https://docs.claude.com/en/docs/claude-code/

### Templates

- **Agent**: [.claude/agents/.AGENT_TEMPLATE.md](.claude/agents/.AGENT_TEMPLATE.md)
- **Command**: [.claude/commands/.COMMANDS_TEMPLATE.md](.claude/commands/.COMMANDS_TEMPLATE.md)
- **Skill**: [.claude/skills/.SKILL_TEMPLATE.md](.claude/skills/.SKILL_TEMPLATE.md)
- **Output Style**: [.claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md](.claude/output-styles/.OUTPUT_STYLES_TEMPLATE.md)
- **Project**: [CLAUDE_TEMPLATE.md](CLAUDE_TEMPLATE.md)

### Get Help

1. `/help` - Built-in help
2. `/setup-info` - Configuration details
3. GitHub Issues: https://github.com/anthropics/claude-code/issues
4. Official Docs: https://docs.claude.com/en/docs/claude-code/

---

## Cheat Sheet

```bash
# Development
/adr [action] [id]           # Manage ADRs
/analyze [path]              # Code analysis
/review [path]               # Code review
/implement [feature]         # Feature implementation
/test [file]                 # Run tests
/optimize [file]             # Optimize performance
/explain [file]              # Explain code

# Agents (automatic or manual)
architect                    # System design
code-reviewer                # Code review
debugger                     # Bug fixing
documentation-writer         # Docs
security-analyst             # Security
test-engineer                # Testing

# Output Styles
/output-style concise        # Brief
/output-style learning       # Interactive
/output-style explanatory    # Educational
/output-style security-reviewer  # Security-focused

# Memory
write_memory(name, content)  # Save (persistent)
read_memory(name)            # Load (persistent)
create_entities([...])       # Build context (temporary)

# Extended Thinking
think / think hard / ultrathink

# Shortcuts
Tab                          # Plan mode toggle
ESC ESC                      # Checkpoints
@file                        # Reference file
```

---

**Version**: 3.0.0 | **Last Updated**: 2025-10-20

**Ready to start?** Run `claude` and try:
```bash
> /setup-info
> "Use the architect agent to explain the project structure"
> /output-style learning
```

For complete documentation, see [CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)