CLAUDE.md templates by stack: what Go needs vs. Next.js vs. AI agents (with examples)

#ai #claude #productivity #tooling

Every time I start a new project with Claude Code, the first 20 minutes used to be wasted.

Not on architecture. Not on setup. On writing the CLAUDE.md file from scratch.

After doing this for the 10th time across different stacks, I mapped out exactly what goes into a high-quality CLAUDE.md for each major framework — and the patterns are very different depending on the stack.

Here's what I learned.

CLAUDE.md for a Go REST API vs. a Next.js SaaS: completely different files

Go REST API needs:

## Error Handling
- Always fmt.Errorf("context: %w", err) — never return raw errors
- Log once at the top of the call stack; never re-log when wrapping
- Domain errors in internal/domain/ as sentinel errors

## Code Structure
- cmd/: Entry points only — no business logic
- internal/handler/: HTTP parsing + calling services
- internal/service/: Pure business logic — no HTTP, no DB
- internal/repository/: All DB queries — none elsewhere

Next.js SaaS needs completely different rules:

## Critical Rules
- Server Components by default; "use client" only for event handlers
- Never useEffect to fetch data — use Server Components or React Query
- Auth: protect routes in middleware.ts only — never in page components
- Stripe: sync subscription state via webhooks — never trust client data
- Never expose Supabase service key to client components

These files solve different problems. One is about Go's error wrapping conventions. The other is about React's rendering model and auth patterns. A generic CLAUDE.md doesn't help either project.

The 5 sections every CLAUDE.md needs (regardless of stack)

After comparing templates across 25 stacks, every effective CLAUDE.md has:

1. Architecture map — where each type of code lives

- handlers/: HTTP only — no business logic
- services/: Business logic — no HTTP, no DB
- models/: DB models only

2. Anti-patterns — what Claude should never do

## Never
- Never put business logic in route handlers
- Never call DB directly from controllers
- Never return raw errors — always wrap with context

3. Domain-specific rules — the stack's non-obvious gotchas

## Stripe
- Webhooks are the source of truth — never trust client-sent state
- Always verify signatures with constructEvent()
- Idempotency keys required for all payment operations

4. Testing conventions

## Tests
- Unit tests for all service layer functions
- Integration tests hit real DB — no mocks
- E2E with Playwright for critical user flows only

5. Environment variables — referenced by name so Claude uses them correctly

## Env vars
- DATABASE_URL: PostgreSQL connection string
- STRIPE_WEBHOOK_SECRET: for webhook verification
- NEXT_PUBLIC_SUPABASE_URL: safe to expose to client

Which stacks need the most specific CLAUDE.md?

From most to least critical to get right:

Multi-tenant SaaS — one missing organizationId filter = data breach
Stripe billing — webhook idempotency is non-obvious and breaks production
AI Agent apps — max iterations and timeout patterns prevent infinite loops
React Native — navigation patterns differ completely from web React
Go APIs — error wrapping conventions are strict and Claude gets them wrong without guidance