afrexai-claude-code-production

# Claude Code Production Engineering The complete methodology for shipping production code with Claude Code at 10X speed. Not installation scripts — actual patterns, workflows, and techniques that compound your output. --- ## Quick Health Check (run mentally before every session) | Signal | Healthy | Fix | |--------|---------|-----| | CLAUDE.md exists at project root | ✅ | Create one (see §1) | | .claueignore configured | ✅ | Add noise directories | | Session context under 60% | ✅ | `/compact` or start fresh | | Clear task scope before prompting | ✅ | Write task brief first | | Tests exist for target code | ✅ | Write tests first (§7) | | Git clean before big changes | ✅ | Commit or stash | | Sub-agents for parallel work | ✅ | Use `/new` or Task tool | | Verifying output, not trusting blindly | ✅ | Always review diffs | Score: /8. Below 6 = slow, buggy sessions. Fix before coding. --- ## 1. Project Setup — CLAUDE.md Architecture CLAUDE.md is your project's brain. Claude reads it at session start. A good one saves thousands of tokens per session. ### Template ```markdown # Project: [name] ## Tech Stack - Language: TypeScript (strict mode) - Framework: Next.js 15 App Router - Database: PostgreSQL via Drizzle ORM - Testing: Vitest + Playwright - Styling: Tailwind CSS v4 ## Architecture Rules - Max 50 lines per function, 300 lines per file - One responsibility per file - All exports typed — no `any` - Errors as values (Result type), not thrown exceptions - Database: migrations via `drizzle-kit generate` then `drizzle-kit push` ## File Structure src/ app/ → Next.js routes (thin — call services) lib/ → Business logic (pure functions) db/ → Schema, migrations, queries components/ → UI (server components default, 'use client' only when needed) types/ → Shared type definitions ## Commands - `pnpm dev` — start dev server - `pnpm test` — run vitest - `pnpm test:e2e` — run playwright - `pnpm lint` — eslint + tsc --noEmit - `pnpm db:generate` — generate migration - `pnpm db:push` — apply migration ## Conventions - Imports: absolute from `@/` (mapped to `src/`) - Naming: camelCase functions, PascalCase components/types, SCREAMING_SNAKE constants - Commits: conventional commits (feat:, fix:, refactor:, test:, docs:) - PRs: always create branch, never commit to main directly ``` ### CLAUDE.md Rules 1. **Be specific** — "TypeScript strict" not "use types." Stack versions, not just names. 2. **Include commands** — Claude needs to know how to run things. Exact commands, not descriptions. 3. **Architecture decisions** — document WHY, not just what. "Errors as values because we use Result type" tells Claude the pattern. 4. **Keep it under 200 lines** — CLAUDE.md is read every session. Bloat wastes tokens. 5. **Update when patterns change** — stale CLAUDE.md causes Claude to fight your codebase. 6. **Nested CLAUDE.md** — subdirectories can have their own. Claude merges them. Use for monorepo packages. ### .claueignore ``` node_modules/ .next/ dist/ coverage/ *.lock .git/ *.min.js *.map public/assets/ ``` Rule: if Claude doesn't need to read it, ignore it. Large lock files and build artifacts waste context. --- ## 2. Prompting Patterns — The 5 That Matter ### Pattern 1: Task Brief (use for any non-trivial work) ``` Task: Add user authentication with magic links Context: Using Resend for email, no password system exists yet Constraints: - Server actions only (no API routes) - Session via httpOnly cookies - Token expires in 15 minutes Acceptance: User enters email → receives link → clicks → logged in → cookie set Start with: the database schema for sessions and tokens ``` Why it works: scope + constraints + acceptance criteria + starting point. Claude doesn't wander. ### Pattern 2: Show, Don't Tell Bad: "Make the API more robust" Good: "Add input validation to POST /api/users — validate email format, name 1-100 chars, reject extra fields. Return 422 with field-level errors matching this shape: `{ errors: { field: string, message: string }[] }`" Rule: if you can't describe the exact output shape, you don't know what you want yet. Think first. ### Pattern 3: Incremental Refinement ``` Step 1: "Create the database schema for a todo app with projects and tasks" [review output] Step 2: "Now add the CRUD service layer for tasks — pure functions, no framework imports" [review output] Step 3: "Now the API routes that call those services — input validation with zod" ``` Why: Claude produces better code in focused steps than in one massive prompt. Each step builds verified context. ### Pattern 4: Fix With Evidence Bad: "It's broken" Good: "Running `pnpm test` gives this error: ``` TypeError: Cannot read properties of undefined (reading 'id') at getUserById (src/lib/users.ts:23:15) ``` The function expects a User object but receives undefined when the database query returns no rows. Add a null check and return a Result type." Rule: paste the actual error. Claude is excellent at fixing bugs when it can see the stack trace. ### Pattern 5: Architecture Discussion ``` I'm deciding between these approaches for real-time updates: A) Server-Sent Events from Next.js API routes B) WebSocket via separate service C) Polling every 5 seconds Context: 500 concurrent users, updates every 30 seconds on average, deployed on Vercel. What are the tradeoffs? Recommend one with reasoning. ``` Use this for decisions, not implementation. Get the answer, THEN switch to Task Brief for building. --- ## 3. Context Management — The #1 Productivity Lever ### Context Is Milk — It Spoils | Context % | Action | |-----------|--------| | 0-30% | Fresh. Do complex work here. | | 30-60% | Good. Continue current task. | | 60-80% | Getting stale. Finish current unit, then compact. | | 80%+ | Dangerous. `/compact` immediately or start new session. | ### When to Start Fresh (`/new`) - Switching to unrelated task - Context above 70% - Claude starts repeating itself or making mistakes it didn't make earlier - After shipping a feature (clean slate for next one) ### When to Compact (`/compact`) - Mid-task but context bloating from exploration - After a debugging session (lots of error output consumed context) - Before a complex implementation step ### Context-Efficient Habits 1. **Don't paste entire files** — reference by path. Claude can read them. 2. **Don't re-explain** — if it's in CLAUDE.md, don't repeat it in prompts. 3. **Use specific file paths** — "Look at `src/lib/auth.ts` line 45" not "look at the auth code." 4. **Close tangents** — if Claude goes down a rabbit hole, redirect immediately. Don't let bad output consume context. 5. **One concern per message** — "Fix the auth bug AND refactor the database layer AND add tests" = context explosion. Sequential > parallel in a single session. --- ## 4. Sub-Agent Orchestration — Parallel Productivity ### When to Use Sub-Agents | Scenario | Pattern | |----------|---------| | Independent features | Spawn sub-agent per feature | | Tests + implementation | One agent writes tests, main writes code | | Research + build | Sub-agent researches API docs, main builds | | Refactor + maintain | Sub-agent refactors module A, main works on B | | Code review | Sub-agent reviews your PR with fresh eyes | ### Task Tool Pattern (Claude Code native) ``` Use the Task tool to: 1. Research the Stripe API for subscription billing 2. Return: webhook event types we need, API calls for create/update/cancel, error codes to handle ``` Task tool spawns a sub-agent with its own context. Results come back summarized. Perfect for research that would bloat your main context. ### Handoff Documents When a sub-agent finishes complex work, have it write a HANDOFF.md: ```markdown ## What Was Done - Implemented Stripe webhook handler at src/app/api/webhooks/stripe/route.ts - Added 4 event handlers: checkout.session.completed, invoice.paid, invoice.payment_failed, customer.subscription.deleted ## Key Decisions - Used Stripe SDK v14 (not raw HTTP) for type safety - Webhook signature verification via stripe.webhooks.constructEvent() - Idempotency: check processed_events table before handling ## What's Next - Wire up subscription status updates to user table - Add retry logic for failed database writes - E2E test with Stripe CLI: `stripe trigger checkout.session.completed` ## Gotchas - Must use raw body (not parsed JSON) for signature verification - Next.js App Router: export const runtime = 'nodejs' (not edge) ``` --- ## 5. Debugging Workflow — Systematic, Not Random ### The DEBUG Protocol **D**escribe the symptom (what you see vs. what you expect) **E**rror output (paste full stack trace, not summary) **B**isect (when did it last work? what changed?) **U**nit isolate (can you reproduce in a test?) **G**enerate hypothesis (ask Claude for 3 possible causes, ranked) ### Effective Bug Prompts ``` Bug: Users see stale data after updating their profile. Expected: After PUT /api/profile, the profile page shows updated data. Actual: Old data persists until hard refresh (Cmd+Shift+R). Stack: - Next.js 15 App Router - Server component fetches user data - Client component with form calls server action - Server action calls db.update() Hypothesis: Next.js is caching the server component fetch. Need to revalidate. Can you confirm and show me the fix? ``` ### When Claude Gets Stuck 1. **Add constraints** — "The fix must not change the API contract" narrows the search space. 2. **Share what you've tried** — "I already tried revalidatePath('/profile') and it didn't work because..." 3. **Ask for alternatives** — "Give me 3 different approaches to solve this, with tradeoffs." 4. **Fresh session** — sometimes the context is poisoned. Start clean with just the bug description. --- ## 6. Refactoring Patterns — Safe Large-Scale Changes ### The Refactoring Safety Net Before any refactoring session: ``` Before we start refactoring: 1. Run the test suite and confirm it passes: `pnpm test` 2. Commit current state: `git add -A && git commit -m "chore: pre-refactor checkpoint"` 3. Create a branch: `git checkout -b refactor/[description]` ``` ### Safe Refactoring Prompts **Extract function:** ``` Extract the email validation logic from src/lib/users.ts (lines 34-67) into a separate function `validateEmail` in src/lib/validation.ts. Update all imports. Run tests after. ``` **Rename across codebase:** ``` Rename the `getUserData` function to `fetchUserProfile` across the entire codebase. This includes: function definition, all call sites, all imports, all test references. Run `pnpm test` and `pnpm lint` after to verify nothing broke. ``` **Split large file:** ``` src/lib/api.ts is 800 lines. Split it into: - src/lib/api/users.ts (user-related functions) - src/lib/api/projects.ts (project-related functions) - src/lib/api/shared.ts (shared types and helpers) - src/lib/api/index.ts (re-exports for backward compatibility) Preserve all existing exports from the index file so no external imports break. Run tests after each file move. ``` ### Multi-File Refactoring Rules 1. **One type of change at a time** — don't rename AND restructure AND optimize simultaneously. 2. **Run tests after each step** — catch breaks early, not after 20 files changed. 3. **Preserve exports** — use index.ts re-exports so consumers don't break. 4. **Commit incrementally** — one commit per logical change, not one giant commit. --- ## 7. Test-Driven Development With Claude Code ### The TDD Loop ``` Step 1: "Write a failing test for: creating a user with valid email stores them in the database" Step 2: [verify test fails for the right reason] Step 3: "Now write the minimum code to make this test pass" Step 4: [verify test passes] Step 5: "Refactor the implementation — the test must still pass" ``` ### Why TDD Works Especially Well With Claude - **Tests are acceptance criteria** — Claude knows exactly what "done" means. - **Immediate verification** — no ambiguity about whether the code works. - **Prevents gold-plating** — "minimum code to pass" stops Claude from over-engineering. - **Regression safety** — future changes can't silently break working features. ### Test-First Prompts ``` Write tests for a `calculateShipping` function that: - Free shipping for orders over $100 - $5.99 flat rate for orders $50-$100 - $9.99 flat rate for orders under $50 - International orders: add $15 surcharge - Express: 2x the base rate - Edge cases: $0 order, negative amount (throw), exactly $50, exactly $100 Use vitest. Don't implement the function yet — just the tests. ``` Then: "Now implement `calculateShipping` to pass all tests." --- ## 8. Git Workflow With Claude Code ### Pre-Work Checklist ```bash git status # Clean working tree? git pull # Up to date? git checkout -b feat/[description] # New branch ``` ### Commit Strategy | Scope | Commit Pattern | |-------|---------------| | Single function added | `feat: add calculateShipping function` | | Bug fixed | `fix: handle null user in profile fetch` | | Tests added | `test: add shipping calculation edge cases` | | Refactor (no behavior change) | `refactor: extract validation into shared module` | | Multiple related changes | Commit each logical unit separately | | Large feature | Multiple commits on feature branch, squash on merge | ### Claude Code Git Prompts ``` # After completing work: "Commit the changes with an appropriate conventional commit message. Group related files into logical commits if there are multiple concerns." # For PR creation: "Create a PR description for these changes. Include: - What changed and why - How to test it - Any migration steps needed - Screenshots if UI changed" ``` --- ## 9. Code Review Mode — Claude as Reviewer ### Review Prompt Template ``` Review this code for: 1. Correctness — does it do what it claims? 2. Security — any injection, auth bypass, data leak risks? 3. Performance — N+1 queries, unnecessary re-renders, missing indexes? 4. Maintainability — clear naming, reasonable complexity, documented edge cases? 5. Testing — are the tests sufficient? Any missing cases? Be specific. For each issue, cite the file:line and suggest a fix. Skip style nits unless they affect readability. ``` ### Self-Review Before PR ``` I'm about to open a PR. Review all changed files (`git diff main`) for: - Any hardcoded secrets or credentials - TODO/FIXME/HACK comments that should be resolved - Console.logs that should be removed - Missing error handling - Type assertions (as any) that should be proper types - Missing tests for new public functions ``` --- ## 10. Production Shipping Checklist Before deploying any Claude-generated code: ### P0 — Must Do - [ ] All tests pass (`pnpm test && pnpm test:e2e`) - [ ] Linting clean (`pnpm lint`) - [ ] Type checking clean (`tsc --noEmit`) - [ ] No hardcoded secrets in code (grep for API keys, tokens, passwords) - [ ] Error handling exists for all external calls (DB, API, file I/O) - [ ] Input validation on all user-facing endpoints - [ ] Database migrations reviewed (no data loss, backward compatible) ### P1 — Should Do - [ ] Performance: no N+1 queries, no unbounded lists, pagination exists - [ ] Logging: structured logs at appropriate levels (not console.log) - [ ] Auth: all new endpoints have proper authorization checks - [ ] Rate limiting on public endpoints - [ ] Rollback plan documented (how to revert if broken) ### P2 — Nice to Have - [ ] Load test with expected traffic - [ ] Monitoring alerts for new endpoints - [ ] Documentation updated (API docs, README, CHANGELOG) - [ ] Accessibility checked (if UI changes) --- ## 11. Anti-Patterns — What Kills Productivity