Agentic Development Best Practices

# Subagent-Driven Development Pattern

# Step 1: Understand — Read the spec, explore the codebase
claude "Read docs/feature-spec.md and identify all tasks"

# Step 2: Decompose — Break into independent tasks
# Key: tasks should touch DIFFERENT files to avoid conflicts

# Step 3: Execute in waves — Launch independent tasks in parallel
claude --background "Build the SearchBar component in components/ui/SearchBar.tsx"
claude --background "Add the /api/search endpoint in app/api/search/route.ts"
claude --background "Write tests for search in __tests__/search.test.ts"

# Step 4: Review — Check results when agents finish
claude "Review recent changes for integration issues and type errors"

# Step 5: Commit — After each logical unit, not batched at the end
claude /commit

# Use specialized review agents for different concerns

# General code review — catches bugs, style issues, missing edge cases
claude "Review the changes in the last 3 commits as a code-reviewer"

# Security review — finds injection risks, auth gaps, data exposure
claude "Review app/api/ as a security-sentinel. Check for:
- Input validation on all endpoints
- Authentication and authorization checks
- SQL injection or XSS vectors
- Sensitive data in responses"

# Performance review — spots N+1 queries, unnecessary rerenders, memory leaks
claude "Review components/ as a performance-oracle. Check for:
- Unnecessary re-renders (missing memo, unstable references)
- Large bundle imports that could be lazy-loaded
- Missing loading and error states"

# TDD with Claude Code

# Step 1: You write the failing test (the specification)
# __tests__/calculateScore.test.ts
import { calculateScore } from '../lib/scoring'

describe('calculateScore', () => {
  it('returns 0 for empty answers', () => {
    expect(calculateScore([])).toBe(0)
  })

  it('awards 10 points per correct answer', () => {
    expect(calculateScore([
      { correct: true },
      { correct: true },
      { correct: false },
    ])).toBe(20)
  })

  it('applies 1.5x multiplier for streak of 3+', () => {
    const answers = Array(4).fill({ correct: true })
    expect(calculateScore(answers)).toBe(60) // 40 * 1.5
  })
})

# Step 2: Tell Claude to make it pass
claude "Make all tests in __tests__/calculateScore.test.ts pass.
Create lib/scoring.ts with the implementation."

# Step 3: Iterate — add more tests, tell Claude to make them pass

# Memory management patterns

# After fixing a non-trivial bug:
# Add the root cause and fix to CLAUDE.md or a debugging.md
# so future agents do not repeat the investigation

# After an architectural decision:
# Document the decision and reasoning in CLAUDE.md
# "We use localStorage instead of a database because..."

# After discovering a gotcha:
# Add it to the Rules section of CLAUDE.md
# "Motion v12 requires import from 'motion/react', NOT 'framer-motion'"

# What NOT to save:
# - Temporary task state (what you are currently working on)
# - Speculative conclusions (unverified assumptions)
# - Information already in CLAUDE.md (avoid duplication)

# Security rules to encode in CLAUDE.md

## Safety Rules
- NEVER edit .env, credentials, or secret files
- NEVER run destructive commands (--force, --hard, rm -rf)
- NEVER commit sensitive files — warn if user requests it
- NEVER skip pre-commit hooks (--no-verify)
- NEVER auto-deploy without explicit human approval
- Docker ports: bind to 127.0.0.1 only (no 0.0.0.0)

## Permission Gates
# Claude Code has built-in permission prompts for:
# - Running shell commands (Bash tool)
# - Writing or editing files
# - Making network requests
# Review these prompts carefully — they are your last line of defense

# Bad: Vague, no context, no constraints
claude "make the app better"

# Good: Specific task, clear context, explicit constraints
claude "Add error boundaries to all page-level components in app/.
Each error boundary should:
- Catch render errors and display a GlassPanel with the error message
- Include a 'Try Again' button that calls reset()
- Log errors to console in development only
- Follow the existing component patterns in components/ui/
Reference: components/ui/GlassPanel.tsx for the panel style"

# Good: Reference existing files as examples
claude "Create a new mini-game component for the quiz challenge.
Follow the same pattern as components/games/PromptDuel.tsx:
- Accept onComplete(score: 0-100) prop
- Use GlassPanel for the container
- Include a timer display
- Use Motion for enter/exit animations"

# Regular cleanup tasks for agent-generated codebases

# 1. Consolidate duplicates — agents often recreate utilities
claude "Find any duplicated utility functions across lib/ and components/.
Consolidate them into the appropriate lib/ module."

# 2. Normalize naming — different sessions may use different conventions
claude "Audit all component prop interfaces for naming consistency.
Standardize: onX for callbacks, isX for booleans, xCount for numbers."

# 3. Remove dead code — agents sometimes leave unused imports or functions
claude "Find and remove all unused exports and imports across the codebase.
Run the TypeScript compiler after to verify nothing breaks."

# 4. Simplify over-abstraction — agents tend to over-engineer
claude "Review lib/utils.ts for over-abstracted functions.
If a function is only used once, consider inlining it."

# A complete agentic development cycle

# 1. Start with context
# - Read CLAUDE.md, review the plan, understand the codebase

# 2. Decompose the feature
# - Break into 3-5 independent tasks
# - Identify file boundaries (no overlap between tasks)

# 3. Write tests first (TDD)
# - Define acceptance criteria as failing tests
# - Each test file maps to one subagent task

# 4. Execute in parallel
# - Launch one agent per task
# - Main thread handles the critical path

# 5. Review the results
# - Low risk: quick scan
# - Medium risk: code-reviewer agent
# - High risk: security-sentinel + architecture-strategist

# 6. Commit and update memory
# - One commit per logical unit
# - Update CLAUDE.md with any new patterns or gotchas

# 7. Repeat for the next feature