afrexai-claude-code-production

What this skill does

# 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
-