Code Generation with Claude Code.

# .claude/CLAUDE.md (committed to repo, ~300 words)

# Project
Next.js 15 App Router + TypeScript strict + Tailwind v4 + Drizzle ORM.

# Commands
- Dev: `pnpm dev`
- Tests: `pnpm test`
- Lint + typecheck: `pnpm lint && pnpm typecheck`
- Build: `pnpm build`

# Code Style
- Named exports only (no default exports)
- 2-space indent
- Server Actions in app/actions/. Prefer over /api/
- Drizzle queries in lib/db/queries/
- Components: server by default; "use client" only when state or effects needed

# Architecture
- Auth: middleware.ts at root; protect /account and /admin
- Schema: lib/db/schema.ts is the single source of truth
- Types: derive from schema where possible (z.infer / drizzle types)

# .claude/rules/react.md
# globs: ["**/*.tsx", "**/*.jsx"]
#
# ## React Component Rules
# - Tailwind for all styles; no CSS modules, no styled-components
# - Props: typed interface (no inline { foo: string })
# - Server Components by default
# - "use client" only when useState/useEffect/event handlers required

# .claude/rules/api.md
# globs: ["app/api/**"]
#
# ## API Route Rules
# - Always validate input with zod schema imported from lib/schemas/
# - Wrap handler in middleware that injects { user, request_id }
# - Return shape: { status: "ok", data } | { status: "error", error: { code, message } }
# - Log errors with request_id for trace correlation

# .claude/rules/db.md
# globs: ["lib/db/**"]
#
# ## Database Rules
# - Drizzle ORM only. No raw SQL except in migrations
# - Queries in lib/db/queries/ subfolder
# - Types: drizzle-zod for runtime + drizzle-orm InferSelectModel for static

# Workflow: Shift+Tab → Plan Mode
#
# Developer prompt:
#   "Plan: split this monolith into 3 services. Auth, billing, notifications.
#    Identify shared utilities, shared DB schemas, and call boundaries."
#
# Claude (in Plan Mode, read-only):
#   1. Reads app/, lib/, prisma/schema.prisma
#   2. Sketches dependency graph
#   3. Returns structured plan:
#      - auth/ owns: User, Session, AuthMethod
#      - billing/ owns: Customer, Invoice, Payment
#      - notifications/ owns: Email, Push, AuditLog
#      - shared/: lib/db/connection.ts, lib/utils/id.ts
#      - call boundaries: HTTP for sync, queue for async
#      - migration order: shared → auth → billing → notifications
#
# Developer reviews, asks: "Is the queue Redis or SQS?"
# Claude refines plan with the answer.
# Developer: "Approved. Execute step 1 only."
# Claude switches to Code Mode and executes that step.

# .claude/skills/react-components/SKILL.md
---
name: react-components
description: Generate production-grade React components (Tailwind + TS strict).
when_to_use: When asked to create or modify a .tsx component file.
allowed-tools: [Read, Grep, Glob, Edit]
---

You are generating a React component for this Next.js 15 codebase.

## Conventions
- Server Components by default. Use "use client" only when state/effects required.
- Props: typed interface, never inline.
- Tailwind for all styling; no CSS modules.
- Named export, never default.
- Include a JSDoc one-liner for any non-trivial prop.

## Pattern
```tsx
interface FooProps {
  // ...
}

export function Foo({ ... }: FooProps) {
  return ( ... );
}
```

# Spawn a code-review subagent
from anthropic import Anthropic
client = Anthropic()

REVIEW_PROMPT = """You are a code reviewer. Two passes.

PASS 1. Per-file:
For each changed file, check:
  - Conformance with .claude/rules/ matching this file's path
  - Test coverage for changed lines
  - No regressions in imports or exports

PASS 2. Integration:
Across all changed files:
  - API boundaries consistent (caller signature == callee signature)
  - Shared types aligned
  - DB schema and ORM usage match

Return STRUCTURED verdict:
{
  "per_file": [{file, issues: [...]}],
  "integration": [{issue, files_affected: [...]}],
  "blocker_count": int,
  "warning_count": int
}"""

# Spawn. Note allowed-tools is scoped Read/Grep/Bash only
resp = client.messages.create(
    model="claude-sonnet-4.5",
    max_tokens=8192,
    system=REVIEW_PROMPT,
    tools=[READ_TOOL, GREP_TOOL, BASH_TOOL],
    messages=[{"role": "user", "content": f"Review PR diff: {pr_diff}"}],
)

# In CLAUDE.md, document the key files:
#
# # Key Files
# - Database schema: @lib/db/schema.ts
# - Auth middleware: @middleware.ts
# - API request validator: @lib/validators/api.ts
# - Server action helpers: @lib/actions/_helpers.ts
#
# Then in a prompt:
#   "How does the rate limiter integrate with auth? @middleware.ts @lib/auth.ts"
#
# Claude pulls in only those two files + transitively their imports.
# Context stays focused; the whole repo doesn't bloat the message.

# Wrong: one prompt, two orthogonal goals
# "Refactor this Redux store to Zustand and also optimize bundle size."
# Result: refactor 80% done, then optimization feedback causes rework.
# ~40% wasted work.

# Right: sequential sessions
#
# Session 1 (Plan Mode): refactor only
#   "Plan: refactor app/store/ from Redux to Zustand. Pure structural;
#    do not change file boundaries or optimize anything yet."
# Approve plan, execute, commit.
#
# Session 2 (new context, Plan Mode): optimize
#   "Plan: now optimize bundle size on the new Zustand store. What dynamic
#    imports? What tree-shake wins? Any code-split candidates?"
# Approve plan, execute, commit.
#
# Each session has clean context and one goal. Code review is per-PR easier.

# Developer flow:
#
# 1. Claude generates: `export default function Foo() {}`
# 2. Developer corrects: "Use named export. Save this to .claude/rules/react.md."
# 3. Claude:
#    - Edits .claude/rules/react.md, adds:
#      "## Exports
#       - Named exports only. Never `export default`."
#    - Updates the original file to use named export.
#    - Commits both in the same change.
#
# 4. Next session. For ANY developer on the team. Claude reads the rule
#    and never generates the default export again. Convention drift = 0.

def save_rule_to_repo(rule_text: str, target_file: str):
    """Pseudocode: Claude actually does this through Edit + Bash tools."""
    with open(f".claude/rules/{target_file}", "a") as f:
        f.write(f"\n{rule_text}\n")
    subprocess.run(["git", "add", f".claude/rules/{target_file}"])