Initial commit: Fresh start with current state
This commit is contained in:
Claude Code
641
QUICKSTART.md
Normal file
641
QUICKSTART.md
Normal file
@@ -0,0 +1,641 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user