# Feature Specification Template (Write BEFORE opening Claude Code)

## Feature: User Authentication System
**Goal**: Implement JWT-based authentication with refresh tokens

**Context**:
- Framework: FastAPI (Python 3.11)
- Database: PostgreSQL 14
- Current auth: None (greenfield)
- Dependencies: python-jose, passlib, bcrypt

**Requirements**:
1. User registration endpoint
2. Login with email/password
3. JWT access tokens (15min expiry)
4. Refresh token rotation
5. Password hashing with bcrypt
6. Token blacklist for logout

**Database Schema**:
```sql
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE refresh_tokens (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    token_hash VARCHAR(255) NOT NULL,
    expires_at TIMESTAMP NOT NULL,
    revoked BOOLEAN DEFAULT FALSE
);

<task>
  <objective>Implement product search functionality with full-text search</objective>

  <requirements>
    <requirement priority="high">Search by product name and description</requirement>
    <requirement priority="high">Filter by price range</requirement>
    <requirement priority="medium">Filter by category</requirement>
    <requirement priority="low">Autocomplete suggestions</requirement>
  </requirements>

  <constraints>
    <constraint>Must use PostgreSQL full-text search (no Elasticsearch)</constraint>
    <constraint>Query performance must be under 100ms for 10k products</constraint>
    <constraint>Pagination required (50 items per page)</constraint>
  </constraints>

  <acceptance_criteria>
    <criterion>Search returns relevant results ranked by relevance</criterion>
    <criterion>Price filter accepts min/max parameters</criterion>
    <criterion>API endpoint follows existing naming conventions</criterion>
    <criterion>Comprehensive test coverage (>90%)</criterion>
  </acceptance_criteria>

  <implementation_notes>
    <note>Use Django's SearchVector and SearchQuery</note>
    <note>Add GIN index on search_vector column</note>
    <note>Implement debounce on autocomplete (300ms)</note>
  </implementation_notes>
</task>

# Single-purpose agent examples

# Frontend Agent (React/TypeScript)
claude-code-frontend/
├── .claud.md
│   Rules:
│   - Only modify files in src/components/ and src/pages/
│   - Use TypeScript strict mode
│   - Follow React hooks best practices
│   - All components must have PropTypes or TypeScript interfaces
│   - Use CSS modules for styling

# Backend Agent (Python/FastAPI)
claude-code-backend/
├── CLAUDE.md
│   Rules:
│   - Only modify files in api/ directory
│   - All endpoints must have Pydantic models
│   - Include OpenAPI documentation
│   - Async/await for all I/O operations
│   - Comprehensive error handling with custom exceptions

# Database Agent (PostgreSQL migrations)
claude-code-database/
├── CLAUDE.md
│   Rules:
│   - Only create migration files
│   - Never modify existing migrations
│   - Include both up and down migrations
│   - Add indexes for foreign keys
│   - Document migration purpose in comments

# Infrastructure Agent (Terraform/Kubernetes)
claude-code-infrastructure/
├── CLAUDE.md
│   Rules:
│   - Only modify infrastructure/ directory
│   - Terraform: use variables, no hardcoded values
│   - Kubernetes: include resource limits
│   - Tag all cloud resources with environment/project
│   - Include cost estimation comments

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "args": ["/path/to/project"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

# Monitor token usage and reset at 50% capacity

Current Conversation: 45,000 / 100,000 tokens (45%)
Action: Continue current session

Current Conversation: 52,000 / 100,000 tokens (52%)
Action: Start fresh session with context handoff

# Context handoff template
"""
Previous session summary:

Completed:
- Implemented user authentication endpoints
- Added JWT token generation
- Created user registration flow

In Progress:
- Email verification system (70% complete)
  - Email service configured
  - Verification token generation working
  - Need to complete: email template, verification endpoint

Current State:
- All tests passing
- Database migrations applied
- API documented in OpenAPI spec

Next Steps:
1. Complete email verification endpoint
2. Add rate limiting to auth endpoints
3. Implement password reset flow
"""

# .claude-commands.json
{
  "commands": {
    "/review": {
      "description": "Comprehensive code review",
      "prompt": "Review all modified files for:\n1. Security vulnerabilities\n2. Performance issues\n3. Code style violations\n4. Missing tests\n5. Documentation gaps\n\nProvide specific line numbers and suggested fixes."
    },
    "/test": {
      "description": "Generate comprehensive tests",
      "prompt": "Generate pytest tests for the current module:\n1. Happy path tests\n2. Edge cases\n3. Error conditions\n4. Integration tests\n5. Aim for >90% coverage"
    },
    "/optimize": {
      "description": "Performance optimization analysis",
      "prompt": "Analyze code for performance optimizations:\n1. Database query efficiency\n2. Caching opportunities\n3. Async/await usage\n4. Memory allocation patterns\n5. Algorithm complexity"
    },
    "/secure": {
      "description": "Security audit",
      "prompt": "Perform security audit:\n1. SQL injection vulnerabilities\n2. XSS attack vectors\n3. CSRF protection\n4. Authentication/authorization issues\n5. Secrets management\n6. Input validation"
    },
    "/document": {
      "description": "Generate documentation",
      "prompt": "Generate comprehensive documentation:\n1. Docstrings for all functions/classes\n2. README with usage examples\n3. API endpoint documentation\n4. Architecture decision records\n5. Deployment instructions"
    }
  }
}

# .claude/hooks/pre-commit
#!/bin/bash
# Run before each commit

echo "Running pre-commit hooks..."

# 1. Format code
black .
isort .

# 2. Lint
pylint api/
mypy api/ --strict

# 3. Security scan
bandit -r api/

# 4. Run tests
pytest tests/ --cov=api --cov-report=term-missing

# 5. Check for secrets
detect-secrets scan --baseline .secrets.baseline

if [ $? -ne 0 ]; then
    echo "Pre-commit checks failed!"
    exit 1
fi

echo "All checks passed!"

# .claude/hooks/post-feature
#!/bin/bash
# Run after completing a feature

echo "Running post-feature validation..."

# 1. Update PROJECT_CONTEXT.md
echo "## Feature: $1" >> PROJECT_CONTEXT.md
echo "Completed: $(date)" >> PROJECT_CONTEXT.md
echo "" >> PROJECT_CONTEXT.md

# 2. Generate changelog entry
git log --oneline -1 >> CHANGELOG.md

# 3. Run full test suite
pytest tests/ --verbose

# 4. Update API documentation
python manage.py spectacular --file schema.yml

# 5. Check for breaking changes
python scripts/check_breaking_changes.py

echo "Post-feature validation complete!"

# ❌ Bad: Multiple features in one chat
"Add user authentication, implement product search, and fix the checkout bug"

# ✅ Good: One feature per chat
Session 1: "Implement JWT-based user authentication"
Session 2: "Add full-text product search with PostgreSQL"
Session 3: "Debug and fix checkout cart calculation error"

After every feature completion, always ask:

"Review your work and list what might be broken. Consider:

1. **Edge Cases**: What inputs haven't been tested?
2. **Error Handling**: What can throw exceptions?
3. **Race Conditions**: Any async/concurrent issues?
4. **Database Integrity**: Foreign key constraints, indexes?
5. **Security**: Authentication, authorization, input validation?
6. **Performance**: N+1 queries, inefficient algorithms?
7. **Breaking Changes**: API compatibility, migration path?
8. **Dependencies**: Version conflicts, missing packages?
9. **Configuration**: Environment-specific settings?
10. **Documentation**: Is everything documented?"

Then fix issues BEFORE moving to next feature.

# Screenshots provide 10x more context than text

# Text description (inefficient):
"The product list page shows products in a grid layout with 4 columns.
Each product card has an image, title, price, and add-to-cart button.
The cards have a subtle shadow and rounded corners. The grid is responsive
and collapses to 2 columns on tablets and 1 column on mobile."

# Better: Drag screenshot directly into terminal
# [screenshot-product-list.png]

# Then simply prompt:
"Implement this exact layout using React and Tailwind CSS"

# Keep running tests until they actually pass

Iteration 1:
> Run tests
FAILED: test_user_registration - AssertionError: 400 != 201

> Fix validation error
> Run tests
FAILED: test_user_registration - KeyError: 'email'

> Fix missing field
> Run tests
FAILED: test_user_registration - IntegrityError: duplicate key

> Add unique constraint check
> Run tests
PASSED: test_user_registration ✓

# "Should work" means it doesn't work
# Loop until green

# CLAUDE.md (Keep under 100 lines)

## Tech Stack
- Backend: FastAPI (Python 3.11)
- Database: PostgreSQL 15
- Frontend: React 18 + TypeScript
- Deployment: Docker + Kubernetes

## Code Standards
- Type hints for all Python functions
- Async/await for I/O operations
- Pydantic models for all API contracts
- Jest + React Testing Library for frontend tests
- 90%+ test coverage required

## Never Do
- Modify database migrations
- Commit secrets or API keys
- Use `any` type in TypeScript
- Bypass authentication checks
- Use `SELECT *` in queries

## Always Do
- Add docstrings to public functions
- Include error handling
- Log important operations
- Update PROJECT_CONTEXT.md after changes
- Run tests before committing

## Security
- Validate all user inputs
- Use parameterized queries (no string interpolation)
- Implement rate limiting on public endpoints
- Hash passwords with bcrypt (cost factor 12)
- Use HTTPS in production

# Write tests BEFORE implementation

# 1. Define test cases
@pytest.mark.asyncio
async def test_user_registration_success():
    """Test successful user registration"""
    user_data = {
        "email": "test@example.com",
        "password": "SecurePass123!",
        "name": "Test User"
    }

    response = await client.post("/auth/register", json=user_data)

    assert response.status_code == 201
    assert "id" in response.json()
    assert response.json()["email"] == user_data["email"]
    assert "password" not in response.json()  # Never return password

@pytest.mark.asyncio
async def test_user_registration_duplicate_email():
    """Test registration with duplicate email fails"""
    # Setup: Create existing user
    await create_user(email="existing@example.com")

    # Attempt to register with same email
    response = await client.post("/auth/register", json={
        "email": "existing@example.com",
        "password": "SecurePass123!"
    })

    assert response.status_code == 400
    assert "already exists" in response.json()["detail"].lower()

# 2. Then prompt Claude Code:
"""
Implement the user registration endpoint to make these tests pass.

Requirements from tests:
- POST /auth/register endpoint
- Accept email, password, name
- Return 201 with user object (no password)
- Prevent duplicate email registration
- Use async/await
"""

# 3. TDD with AI prevents debugging nightmares

# PROJECT_CONTEXT.md

## Project Overview
E-commerce platform API for selling digital and physical products.

## Current Architecture

# Frontend Agent
Agent: claude-frontend
Context: React components, TypeScript, CSS
Rules:
- Use functional components with hooks
- TypeScript strict mode
- CSS modules for styling
- PropTypes or interfaces required
- Accessibility (a11y) compliance

# Backend Agent
Agent: claude-backend
Context: FastAPI, database models, business logic
Rules:
- Async/await for I/O
- Pydantic validation
- Comprehensive error handling
- OpenAPI documentation
- Database transactions for multi-step operations

# Database Agent
Agent: claude-database
Context: PostgreSQL schemas, migrations, queries
Rules:
- Alembic migrations only
- Never modify existing migrations
- Include up and down migrations
- Add indexes for performance
- Foreign key constraints required

After making changes, always ask:

"Explain what you changed and why. Include:

1. **Files Modified**: List with line numbers
2. **Changes Made**: What specifically changed
3. **Reasoning**: Why this approach was chosen
4. **Tradeoffs**: Alternative approaches considered
5. **Side Effects**: What else might be affected
6. **Testing**: How to verify changes work
7. **Rollback**: How to undo if needed"

Example response:
"""
Changes Made:

1. api/auth/views.py (lines 45-67)
   - Added rate limiting decorator to login endpoint
   - Limit: 5 attempts per 15 minutes per IP
   - Uses Redis for distributed rate limit tracking

2. requirements.txt
   - Added slowapi==0.1.9 for rate limiting

Reasoning:
- Prevent brute force attacks on login endpoint
- Distributed rate limiting works across multiple API instances
- Redis provides fast lookup and automatic expiration

Tradeoffs Considered:
- In-memory rate limiting: Doesn't work with multiple instances
- Database rate limiting: Too slow for high-traffic endpoints
- Chose Redis: Fast, distributed, automatic cleanup

Side Effects:
- Requires Redis connection (already used for caching)
- Failed login attempts now return 429 after limit exceeded
- May need to whitelist internal IPs for monitoring tools

Testing:
```bash
# Test rate limiting
for i in {1..6}; do
  curl -X POST http://localhost:8000/auth/login \
    -H "Content-Type: application/json" \
    -d '{"email":"test@example.com","password":"wrong"}'
done
# 6th request should return 429 Too Many Requests

# Git commit after EVERY working feature

# ✅ Good: Granular commits
git add api/auth/
git commit -m "feat: Add user registration endpoint

- Implement POST /auth/register
- Add email/password validation
- Hash passwords with bcrypt
- Return JWT token on success
- Add comprehensive tests (95% coverage)

Tests: pytest tests/test_auth.py::test_registration -v
Closes: #123"

git add api/auth/login.py
git commit -m "feat: Add user login endpoint

- Implement POST /auth/login
- Validate credentials
- Generate JWT access + refresh tokens
- Add rate limiting (5 req/15min)
- Add integration tests

Tests: pytest tests/test_auth.py::test_login -v
Relates: #124"

# ❌ Bad: Mega commits
git add .
git commit -m "Add authentication system"
# (100 files changed, 5000 insertions, 2000 deletions)

# Generate debug plan before attempting fixes

Prompt:
"Create a debugging plan for this issue: Users report checkout failing
when cart has more than 5 items.

Include:
1. **Hypothesis**: Likely root causes
2. **Reproduction**: Steps to reproduce locally
3. **Investigation**: What to check and in what order
4. **Logging**: What debug output to add
5. **Testing**: How to verify fix works
6. **Prevention**: How to prevent recurrence"

Expected output:
"""
Debug Plan: Checkout Failure >5 Items

Hypothesis:
1. Database query limit/pagination issue
2. Session/cookie size limit exceeded
3. Cart calculation overflow or timeout
4. Validation rule incorrectly applied

Reproduction Steps:
```python
# Create test case
def test_checkout_large_cart():
    cart = create_cart_with_items(count=10)
    response = client.post("/checkout", json=cart.dict())
    assert response.status_code == 200

# Add to checkout view
logger.info(f"Processing checkout: {cart.item_count} items")
logger.debug(f"Cart data: {cart.dict()}")
logger.debug(f"Session size: {len(json.dumps(session.dict()))} bytes")

# Good
try:
    process_payment()
except PaymentError as e:
    log.error(f"Payment failed: {e}")
    notify_admin(e)
except NetworkError as e:
    log.warning(f"Temporary network issue: {e}")
    queue_for_retry(payment)

# Give tasks one at a time, review each before proceeding

# ❌ Bad: Chain of tasks
"Implement user authentication, add product search, fix the checkout bug,
and optimize database queries"

# ✅ Good: Sequential with review
Task 1: "Implement user registration endpoint"
> Review output, verify tests pass
> Commit changes

Task 2: "Implement user login endpoint"
> Review output, verify tests pass
> Commit changes

Task 3: "Add JWT token refresh endpoint"
> Review output, verify tests pass
> Commit changes

# You orchestrate, AI executes
# Review EVERYTHING before trusting

# Use Playwright MCP with Sonnet for comprehensive UI testing

npx playwright test --headed

# Playwright can:
# 1. Visually inspect the interface
# 2. Test interactions (clicks, forms, navigation)
# 3. Read browser console for JavaScript errors
# 4. Capture screenshots of failures
# 5. Generate test code from recordings

# Example test generation:
npx playwright codegen http://localhost:3000

# Better than screenshots alone:
# - Tests document expected behavior
# - Automated regression testing
# - Cross-browser compatibility checks

# For multi-hour tasks, maintain context without wiping conversation

Approach 1: Internal To-Do List
"Create an internal to-do list for this feature, then tackle one item at
a time. After completing each item, update the list and wait for my approval
before proceeding."

Example:
"""
Feature: Inventory Management System

To-Do List:
- [✓] Create database schema for inventory
- [✓] Implement stock tracking
- [⧗] Add low stock alerts (in progress)
  - [✓] Create alert model
  - [✓] Add background job for checking
  - [ ] Implement email notifications
  - [ ] Add webhook notifications
- [ ] Implement automated reordering
- [ ] Create admin UI for inventory management
- [ ] Add inventory audit logging

Current: Working on email notifications for low stock alerts
Next: Webhook notifications
"""

Approach 2: Checkpoint Saves
# Save conversation state at logical breakpoints
# Return to saved checkpoint instead of starting fresh

# Use cheaper models for non-critical sub-tasks

Main Agent (Sonnet 4):
- Feature implementation
- Code generation
- Architecture decisions
- Complex debugging

Sub-Agents (Haiku or GPT-3.5):
- Web searches
- API documentation lookups
- Formatting code
- Generating boilerplate
- Simple data transformations

# Cost comparison:
# Sonnet: $3/M input tokens, $15/M output tokens
# Haiku: $0.25/M input tokens, $1.25/M output tokens
# 12x cost reduction for appropriate tasks

Example routing:
"Use the web-search sub-agent to find the latest FastAPI documentation
for background tasks, then summarize the findings."

# Direct sub-agent usage explicitly

# ❌ Implicit (unreliable):
"Look up the Stripe API documentation and implement payment processing"
# Claude might route incorrectly or not use sub-agents

# ✅ Explicit (reliable):
"Use the documentation-search agent to find Stripe payment intent API docs.
Once you have the information, implement the payment processing endpoint."

# Sub-agent usage guidelines:
# 1. Information gathering: Use sub-agents
# 2. Code changes: Use main agent
# 3. Verification: Use sub-agents for checks, main agent for fixes

# Use sub-agents ONLY for information, not execution

# ✅ Good: Information gathering
"Use the GitHub sub-agent to:
1. List open issues labeled 'bug'
2. Get the last 10 commits to main branch
3. Check CI/CD status

Then summarize findings and propose a fix for the highest priority bug."

# ❌ Bad: Direct execution via sub-agent
"Use the GitHub sub-agent to create a pull request with these changes"
# You lose visibility and control

# Principle: Sub-agents gather, main agent executes
# You approve all changes

# api/CLAUDE.md (Backend rules)
## API Development Rules
- All endpoints async
- Pydantic models required
- OpenAPI docs mandatory
- Authentication on all non-public endpoints
- Rate limiting on public endpoints
- Comprehensive error handling

# frontend/CLAUDE.md (Frontend rules)
## Frontend Development Rules
- TypeScript strict mode
- React functional components only
- PropTypes or TypeScript interfaces required
- Accessibility (WCAG 2.1 AA) compliance
- Mobile-first responsive design
- Performance budget: <2s initial load

# database/CLAUDE.md (Database rules)
## Database Rules
- Alembic migrations only
- Never modify existing migrations
- Include up AND down migrations
- Index all foreign keys
- Document migration purpose
- Test migrations on copy of production data

# Use another LLM to clarify prompts before sending to Claude

Your prompt (potentially vague):
"Add caching to the product API"

Run through clarification LLM:
"""
Context: E-commerce API with FastAPI and PostgreSQL

Vague prompt: "Add caching to the product API"

Generate clarifying questions and suggest improved prompt.
"""

Clarification LLM output:
"""
Questions needing clarification:
1. Which specific endpoints need caching?
2. What should be the cache duration?
3. What cache backend (Redis, Memcached, in-memory)?
4. What's the cache invalidation strategy?
5. Should this be read-through or write-through caching?

Improved prompt:
"Implement Redis caching for the GET /products/ list endpoint:
- Cache TTL: 5 minutes
- Cache key: Include query parameters (page, category, search)
- Invalidation: Automatic on product creation/update/deletion
- Use Redis cache backend (already configured at $REDIS_URL)
- Add cache hit/miss metrics
- Implement cache warming for top 100 products
- Include tests for cache behavior"
"""

# Build reusable slash commands for common operations

# /debug command
{
  "name": "debug",
  "description": "Comprehensive debugging workflow",
  "steps": [
    "Analyze the error and propose 3 possible root causes",
    "For each hypothesis, list verification steps",
    "Add detailed logging at key points",
    "Create minimal reproduction test case",
    "Implement fix with explanation",
    "Verify fix doesn't introduce regressions",
    "Document root cause and solution in DEBUGGING.md"
  ]
}

# /cleanup command
{
  "name": "cleanup",
  "description": "Code cleanup and refactoring",
  "steps": [
    "Identify code smells (long functions, duplications, complex conditionals)",
    "Propose refactoring approach",
    "Extract reusable functions/classes",
    "Improve variable/function naming",
    "Add missing docstrings",
    "Remove dead code",
    "Update tests to match refactored code",
    "Verify all tests still pass"
  ]
}

# /security command
{
  "name": "security",
  "description": "Security audit and hardening",
  "checks": [
    "SQL injection vulnerabilities (use parameterized queries)",
    "XSS attack vectors (escape output, CSP headers)",
    "CSRF protection (tokens on state-changing operations)",
    "Authentication bypass opportunities",
    "Authorization issues (check permissions)",
    "Secrets in code or logs",
    "Insecure dependencies (known CVEs)",
    "Missing rate limiting",
    "Insufficient input validation",
    "Insecure defaults"
  ]
}

// refactoring-log.json
{
  "feature": "Convert synchronous database calls to async",
  "started": "2025-01-20T09:00:00Z",
  "target_files": 47,
  "completed_files": 32,
  "progress": [
    {
      "file": "api/products/views.py",
      "status": "completed",
      "timestamp": "2025-01-20T09:15:00Z",
      "changes": [
        "Converted get_products() to async",
        "Replaced psycopg2 with asyncpg",
        "Updated tests to use pytest-asyncio"
      ],
      "tests_passing": true
    },
    {
      "file": "api/orders/views.py",
      "status": "in_progress",
      "timestamp": "2025-01-20T10:30:00Z",
      "changes": [
        "Converted create_order() to async",
        "TODO: Update payment processing integration"
      ],
      "tests_passing": false,
      "blockers": ["Payment gateway SDK doesn't support async"]
    }
  ],
  "next_files": [
    "api/users/views.py",
    "api/cart/views.py"
  ]
}

After each refactoring step:
"Update refactoring-log.json with:
- File modified
- Changes made
- Test status
- Any blockers
- Next file to tackle"

After completing any task:

"Re-check your own work and prove it was done correctly:

1. **Syntax**: Run linter/formatter, fix all issues
2. **Types**: Run type checker, resolve all errors
3. **Tests**: Run test suite, all must pass
4. **Security**: No new vulnerabilities introduced
5. **Performance**: No obvious performance regressions
6. **Documentation**: Code is documented
7. **Edge Cases**: Handled appropriately
8. **Error Handling**: Comprehensive exception handling
9. **Code Review**: Would this pass peer review?
10. **Verification**: Provide evidence (test output, lint results)"

Example verification:
```bash
# Linting
$ black api/ --check
All done! ✨ 🍰 ✨
15 files would be left unchanged.

# Type checking
$ mypy api/ --strict
Success: no issues found in 15 source files

# Tests
$ pytest tests/ -v --cov=api
=================== test session starts ===================
tests/test_auth.py::test_registration PASSED        [ 10%]
tests/test_auth.py::test_login PASSED                [ 20%]
...
=================== 50 passed in 12.34s ===================
Coverage: 94%

# Security scan
$ bandit -r api/
No issues identified.

// Minimal viable MCP configuration
{
  "mcpServers": {
    // Critical MCPs
    "sequential-thinking": {
      // Complex reasoning and planning
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "memory": {
      // Persistent context across sessions
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    },
    "github": {
      // Version control integration
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },

    // Tech stack specific (choose based on your stack)
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

// Avoid MCP bloat:
// - Only add MCPs you use weekly
// - Remove unused MCPs (they consume context)
// - Tech-stack specific MCPs only

# .claude/hooks/pre-run
#!/bin/bash
# Runs before Claude executes any code changes

echo "=== Pre-run validation ==="

# 1. Check git status (no uncommitted changes from previous session)
if [[ -n $(git status -s) ]]; then
    echo "⚠️  Uncommitted changes detected"
    git status -s
fi

# 2. Check dependency versions
echo "Checking dependencies..."
pip list --outdated

# 3. Verify environment variables
required_vars=("DATABASE_URL" "REDIS_URL" "SECRET_KEY")
for var in "${required_vars[@]}"; do
    if [[ -z "${!var}" ]]; then
        echo "❌ Missing required env var: $var"
        exit 1
    fi
done

# 4. Run quick smoke tests
echo "Running smoke tests..."
pytest tests/smoke/ -q

echo "✅ Pre-run validation passed"

# .claude/hooks/post-run
#!/bin/bash
# Runs after Claude completes a task

echo "=== Post-run validation ==="

# 1. Run linters
black api/ --check
isort api/ --check-only
pylint api/

# 2. Run type checking
mypy api/ --strict

# 3. Run test suite
pytest tests/ --cov=api --cov-fail-under=90

# 4. Security scan
bandit -r api/
safety check

# 5. Check for secrets
detect-secrets scan --baseline .secrets.baseline

# 6. Update documentation
python scripts/generate_api_docs.py

# 7. Update PROJECT_CONTEXT.md timestamp
echo "Last modified: $(date)" >> PROJECT_CONTEXT.md

echo "✅ Post-run validation complete"

# Screenshots explain problems faster than text

# Instead of:
"The button is misaligned, the spacing is wrong, and the color doesn't
match the design"

# Use:
1. Take screenshot of actual UI
2. Take screenshot of expected design
3. Drag both into Claude Code
4. Prompt: "Make the actual UI match the design mockup"

# For bugs:
1. Screenshot of error message
2. Screenshot of relevant code
3. Screenshot of network tab (if API issue)
4. Screenshot of console (if JavaScript issue)

# Visual context is 10x clearer than text descriptions

# Opus 4.1: Complex reasoning and planning
- Architecture decisions
- Algorithm design
- Debugging complex issues
- Security analysis
- Performance optimization strategy

# Sonnet 4: General development
- Feature implementation
- Code refactoring
- Test writing
- Documentation
- Code reviews

# Haiku: Simple, repetitive tasks
- Code formatting
- Boilerplate generation
- Simple transformations
- Documentation lookups
- Routine updates

Cost optimization:
- Plan with Opus 4.1 (expensive but thorough)
- Implement with Sonnet 4 (balanced cost/quality)
- Execute simple tasks with Haiku (cheapest)

# Step 1: Plan with Opus 4.1
"Design the architecture for a real-time notification system.

Requirements:
- 100k concurrent WebSocket connections
- <100ms delivery latency
- Guaranteed delivery
- Multi-region support

Provide:
1. System architecture diagram
2. Technology choices with justification
3. Scalability strategy
4. Failure modes and mitigation
5. Implementation roadmap"

# Step 2: Implement with Sonnet 4
"Using this architecture plan [attach Opus output], implement Phase 1:
WebSocket connection handler with Redis pub/sub backend.

Follow the architecture exactly as specified."

# Separation benefits:
# - Better architecture (Opus reasoning)
# - Faster implementation (Sonnet speed)
# - Lower cost (Opus for planning only)

# Install Claude Code undo repository
git clone https://github.com/ccundorepo/ccundorepo
cd ccundorepo
pip install -e .

# Usage
ccundo init  # Initialize undo tracking

# Claude makes changes
# Changes are automatically tracked

ccundo list  # Show change history
ccundo diff <id>  # Show specific changes
ccundo revert <id>  # Revert to previous state

# Benefits:
# - Granular undo (not just git commits)
# - Track intermediate states
# - Safe experimentation
# - Easy rollback of AI changes

# .claude/hooks/security-scan
#!/bin/bash
# Runs after every code change

echo "=== Security Scan ==="

# 1. Static analysis
bandit -r api/ -f json -o bandit-report.json

# 2. Dependency vulnerabilities
safety check --json > safety-report.json

# 3. Secret detection
detect-secrets scan --baseline .secrets.baseline

# 4. Code quality (security-focused rules)
pylint api/ --disable=all --enable=security

# 5. Third-party security review (if configured)
# coderabbit scan ./

# 6. Parse results
python .claude/scripts/parse_security_results.py

if [ $? -ne 0 ]; then
    echo "❌ Security issues detected!"
    exit 1
fi

echo "✅ Security scan passed"

# AI doesn't write secure code by default - ask explicitly

For EVERY endpoint/feature:

"Implement [feature] with these security requirements:

**Input Validation**:
- Validate all user inputs with Pydantic models
- Reject invalid data with 400 Bad Request
- Sanitize inputs to prevent injection attacks

**SQL Injection Prevention**:
- Use parameterized queries (no string interpolation)
- Use ORM (SQLAlchemy) where possible
- Validate table/column names if dynamic

**XSS Prevention**:
- Escape all user-generated content in responses
- Set Content-Security-Policy headers
- Use Content-Type: application/json

**Authentication**:
- Require valid JWT token
- Verify token signature and expiration
- Check user has required permissions

**Rate Limiting**:
- 100 requests per minute per user
- 1000 requests per minute per IP
- Exponential backoff on repeated failures

**Database Security**:
- Enable Row Level Security (RLS) in PostgreSQL
- Use separate read-only users for queries
- Never expose raw database errors to clients

**Logging**:
- Log all authentication attempts
- Log all permission denials
- Never log passwords or tokens
- Sanitize logs to prevent log injection"

# Implement rate limiting with Upstash or similar

from upstash_ratelimit import Ratelimit, SlidingWindow
from upstash_redis import Redis

# Initialize Redis client
redis = Redis(url=os.getenv("REDIS_URL"))

# Create rate limiter
ratelimit = Ratelimit(
    redis=redis,
    limiter=SlidingWindow(requests=100, window=60),  # 100 req/min
    prefix="ratelimit"
)

@app.post("/api/endpoint")
async def endpoint(request: Request):
    # Get client identifier (user ID or IP)
    identifier = request.state.user.id if request.state.user else request.client.host

    # Check rate limit
    result = await ratelimit.limit(identifier)

    if not result.allowed:
        raise HTTPException(
            status_code=429,
            detail=f"Rate limit exceeded. Retry after {result.reset}s",
            headers={"Retry-After": str(result.reset)}
        )

    # Process request
    return {"message": "Success"}

# "think harder" variations for complex problems

"think" - Standard reasoning (moderate token usage)
"think hard" - Deeper analysis (higher token usage)
"think harder" - Comprehensive analysis (high token usage)
"ultrathink" - Maximum reasoning depth (highest token usage)

Use cases:
- Complex debugging: "ultrathink about why this race condition occurs"
- Architecture decisions: "think harder about scaling this to 1M users"
- Security analysis: "think hard about attack vectors"
- Performance optimization: "ultrathink about reducing latency"

Warning:
- Increased token cost (2-5x)
- Not always better results (diminishing returns)
- Use only for genuinely complex problems

# Rules disappear after conversation compaction - counter this:

Strategy 1: Repeat in Chat with #
"#CRITICAL_RULE: Never modify existing database migrations
#CRITICAL_RULE: Always use async/await for database calls
#CRITICAL_RULE: Validate all inputs with Pydantic models"

Strategy 2: Save in Multiple Files
- Project root: CLAUDE.md (global rules)
- Directory specific: api/CLAUDE.md (API rules)
- In chat: Reference rules explicitly

Strategy 3: Include in System Prompts
- Edit Claude Code settings
- Add rules to system prompt (never compacted)

Strategy 4: Create Hook Reminders
```bash
# .claude/hooks/pre-run
echo "Rules reminder:"
cat CLAUDE.md
cat DONT_DO.md

# .claude/scripts/update_knowledge.sh
#!/bin/bash
# Run daily to update global knowledge base

echo "=== Updating Global Knowledge Base ==="

# 1. Extract learnings from recent commits
git log --since="1 day ago" --pretty=format:"%h - %s" >> .claude/recent_changes.txt

# 2. Analyze error logs for common issues
python .claude/scripts/analyze_errors.py >> .claude/common_issues.txt

# 3. Update dependency versions
pip list --outdated > .claude/outdated_dependencies.txt

# 4. Prompt Claude to summarize learnings
cat << EOF
Review the following and update GLOBAL_KNOWLEDGE.md with any new learnings:

Recent changes:
$(cat .claude/recent_changes.txt)

Common issues:
$(cat .claude/common_issues.txt)

Outdated dependencies:
$(cat .claude/outdated_dependencies.txt)

Add to GLOBAL_KNOWLEDGE.md:
- New patterns discovered
- Common mistakes to avoid
- Performance optimizations
- Security improvements
- Dependency updates needed
EOF

# 5. Cleanup temporary files
rm .claude/recent_changes.txt .claude/common_issues.txt .claude/outdated_dependencies.txt

echo "✅ Knowledge base updated"

# Agent self-improvement over time

After every significant task:
"Update GLOBAL_KNOWLEDGE.md with:

1. **What Worked Well**:
   - Approaches that were efficient
   - Tools that helped
   - Patterns worth repeating

2. **What Didn't Work**:
   - Failed approaches
   - Time wasters
   - Anti-patterns encountered

3. **Lessons Learned**:
   - Better ways discovered
   - Edge cases to remember
   - Performance insights

4. **Future Improvements**:
   - How to do this faster next time
   - What to automate
   - What to document better

Example entry: