Best Practices

# Project-level CLAUDE.md example
# Place at your repository root

## Project Overview
This is a Next.js 15 app with TypeScript and Tailwind CSS.

## Architecture
- /src/app/ - App Router pages
- /src/components/ - Reusable UI components
- /src/lib/ - Utility functions and configs

## Commands
- pnpm dev - Start dev server
- pnpm test - Run tests
- pnpm lint - Run linter

## Conventions
- Use functional components with hooks
- Prefer immutable patterns (spread, map, filter)
- All new files must have tests

# Ask Claude to create a handoff document
> Write a HANDOFF.md summarizing what we did today,
> open decisions, and next steps.

# In your next session
> Read HANDOFF.md and continue from where we left off.

# In your CLAUDE.md, add verification commands:
## After Every Change
- Run: pnpm test
- Run: pnpm lint
- Run: pnpm typecheck

# Or set up a PostToolUse hook in .claude/settings.json:
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "pnpm test --bail 2>&1 | tail -20"
      }
    ]
  }
}

# Good verification prompts:
> Now review that implementation for edge cases
> Run the tests and fix any failures
> Check if this handles null/undefined inputs
> Does this match the existing code style?

# Instead of one big prompt:
> Build a complete auth system with OAuth, sessions, and RBAC

# Break it down into phases:
> Phase 1: Set up the session store with Redis.
>   Only create the session middleware - no auth yet.
>   Run tests before moving on.

> Phase 2: Add email/password authentication.
>   Use the session store from Phase 1.
>   Add login, logout, and registration routes.

> Phase 3: Add OAuth (Google, GitHub).
>   Integrate with the existing session/auth system.

> Phase 4: Add role-based access control.
>   Define roles: admin, editor, viewer.
>   Add middleware to protect routes.

# Trigger levels of extended thinking:

> think about how to refactor this module
# Light analysis, good for moderate complexity

> think hard about the tradeoffs between
> microservices vs monolith for our scale
# Deeper analysis, explores more alternatives

> ultrathink about the security implications
> of our auth architecture
# Maximum reasoning depth, best for critical decisions

# Bad: vague prompt
> Fix the bug in the login page

# Good: specific prompt with context
> In src/app/auth/login.tsx, the handleSubmit
> function throws a null reference when the
> email field is empty. Add input validation
> before the API call on line 45. The validation
> should show an inline error message matching
> the style in src/components/FormError.tsx.

# Include constraints directly in your prompt:
> Add a user search endpoint to the API.
> Requirements:
> - Follow the pattern in src/api/products.ts
> - Use Zod for input validation
> - Add rate limiting (100 req/min)
> - Return paginated results
> - Include unit tests with >80% coverage
> - All existing tests must still pass
> - No console.log statements

# Less effective: just instructions
> Add a cache layer to getUserById

# More effective: intent + instructions
> Users are seeing 2s load times on profile pages
> because getUserById hits the database every time.
> Add a Redis cache layer with 5-minute TTL.
> Invalidate on user update. Follow the caching
> pattern we use in getProductById.

# GitHub Actions example: automated code review
name: Claude Code Review
on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Claude Review
        run: |
          claude -p "Review the changes in this PR.
            Focus on: security issues, performance,
            and code style. Output as markdown." \
            --output-format json > review.json

# .claude/settings.json - shared team config
{
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(pnpm test*)",
      "Bash(pnpm lint*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

# Create worktrees for parallel agents
git worktree add ../project-agent-1 -b feature/auth
git worktree add ../project-agent-2 -b feature/api

# Run Claude in each worktree
cd ../project-agent-1 && claude -p "Implement auth"
cd ../project-agent-2 && claude -p "Build API endpoints"

# Merge results back
git checkout main
git merge feature/auth
git merge feature/api

# .claude/skills/api-endpoint/SKILL.md
---
name: create-api-endpoint
description: Create a new REST API endpoint
---

## Steps
1. Create route handler in src/api/
2. Add Zod validation schema
3. Add rate limiting middleware
4. Write integration tests
5. Update OpenAPI spec

## Template
Follow the pattern in src/api/products.ts
Always include error handling middleware
Use the shared response format from src/lib/response.ts