Appendix A: CLAUDE.md Templates

Ten starting points by stack. Copy the closest one, replace the bracketed values, and add your traps under "Do not touch." Each follows the eight-section structure from Chapter 4, trimmed to what changes behavior.

A.1 TypeScript Node.js backend

# [Service name]
[One sentence: what it does, who calls it.]

## Stack
- TypeScript 5 strict, Node 22, ESM. [Fastify|Express|NestJS]. [Prisma|Drizzle] + PostgreSQL.

## Commands
- Install `pnpm install` | Dev `pnpm dev` | Test `pnpm test` | One test `pnpm vitest run <path>`
- Typecheck `pnpm typecheck` | Lint `pnpm lint --fix`

## Conventions
- Named exports only. No `any`; use `unknown` and narrow.
- Validate all external input with [zod] at the boundary.
- Services return results; routes map them to HTTP. No HTTP types in services.

## Architecture
- routes/ -> services/ -> repositories/. Only repositories touch the DB.

## Do not touch
- [generated client path], [legacy module]

## Workflow
- Typecheck and run affected tests after every change. Commit per step: `type(scope): summary`.

## Security
- Secrets via config module only. No raw SQL strings. Never log tokens or PII.

A.2 React frontend (Vite or Next.js)

# [App name]
## Stack
- React 19, TypeScript strict, [Next.js App Router|Vite]. [Tailwind|CSS Modules]. [TanStack Query].
## Commands
- Dev `pnpm dev` | Test `pnpm test` | E2E `pnpm playwright test` | Build `pnpm build`
## Conventions
- Function components only. Server components by default (Next.js); add "use client" only when needed.
- Data fetching through [query hooks in src/api]. No fetch calls inside components.
- Accessible by default: semantic elements, labels on inputs, keyboard support.
- Use design tokens from [src/styles/tokens]. No hardcoded colors.
## Do not touch
- [src/components/ui] is the shared design system. Propose changes, do not edit.
## Workflow
- For UI changes, screenshot the result and compare to the mockup before finishing.
## Security
- Never use dangerouslySetInnerHTML without sanitizing. No secrets in client code or NEXT_PUBLIC vars.

A.3 Python data or ML pipeline

# [Pipeline name]
## Stack
- Python 3.12, uv for env and deps. [Polars|pandas], [PyTorch|scikit-learn]. [Airflow|Dagster].
## Commands
- Sync `uv sync` | Test `uv run pytest -q` | Lint `uv run ruff check --fix` | Types `uv run mypy src`
## Conventions
- Type hints on all public functions. Pure transforms in src/transforms, I/O in src/io.
- Fixed random seeds in training and evaluation. Log every experiment to [tracker].
## Do not touch
- data/raw is immutable. Never write to it.
## Workflow
- Check for train/test leakage on any change to splits or features.
## Security
- No credentials in notebooks. No production PII in local data; use the masked sample in data/sample.

A.4 Go microservice

# [Service name]
## Stack
- Go 1.23, standard library HTTP + [chi]. [sqlc] + PostgreSQL. gRPC for internal calls.
## Commands
- Test `go test ./...` | Race `go test -race ./...` | Lint `golangci-lint run` | Gen `make generate`
## Conventions
- Errors wrapped with context: fmt.Errorf("doing x: %w", err). No panics in request paths.
- Pass context.Context as the first argument everywhere. Respect cancellation.
- Interfaces defined where they are consumed, not where implemented.
## Do not touch
- Generated files under internal/db/gen and api/gen. Edit the .sql or .proto and regenerate.
## Security
- Parameterized queries only (sqlc). Validate all request bodies. Timeouts on all outbound calls.

A.5 Rust systems code

# [Crate name]
## Stack
- Rust stable, edition 2021. [tokio] async. Workspace with crates in crates/.
## Commands
- Check `cargo check` | Test `cargo test --workspace` | Lint `cargo clippy -- -D warnings` | Fmt `cargo fmt`
## Conventions
- No unwrap or expect outside tests. Use thiserror for library errors, anyhow in binaries.
- Every unsafe block has a SAFETY comment justifying it. New unsafe requires human review.
## Workflow
- Clippy must be clean before commit.

A.6 Kubernetes manifests

# [Platform manifests]
## Layout
- base/ shared resources, overlays/[dev|staging|prod] via Kustomize. Charts in charts/.
## Commands
- Render `kustomize build overlays/staging` | Validate `kubeconform -strict` | Helm `helm template`
## Conventions
- Every workload: requests and limits, liveness and readiness probes, runAsNonRoot, readOnlyRootFilesystem, drop ALL capabilities.
- Images pinned by digest in prod overlays.
## Do not touch
- overlays/prod requires human review. Never run kubectl apply or delete.

A.7 Terraform infrastructure

# [Infra repo]
## Layout
- modules/ reusable modules. envs/[dev|staging|prod] root modules. Remote state in [backend].
## Commands
- Fmt `terraform fmt -recursive` | Validate `terraform validate` | Plan `terraform plan` | Policy `checkov -d .`
## Conventions
- All resources tagged: owner, env, cost-center. Encryption at rest on by default.
- No hardcoded account IDs or regions; use variables.
## Do not touch
- Never run apply or destroy. Never edit state. envs/prod changes need human review.
## Workflow
- After any change, run plan and summarize every destroy or replace.

A.8 Mobile (React Native or Flutter)

# [App name]
## Stack
- [React Native 0.7x with Expo|Flutter 3.x]. State: [Zustand|Riverpod].
## Commands
- Start `[npx expo start|flutter run]` | Test `[pnpm test|flutter test]` | Lint `[pnpm lint|flutter analyze]`
## Conventions
- Platform-specific code isolated in *.ios.* and *.android.* files or platform channels.
- All user-facing strings through the i18n layer.
## Security
- Tokens in secure storage (Keychain/Keystore), never AsyncStorage or SharedPreferences.
- Certificate pinning config in [path] is not to be weakened.

A.9 Monorepo (pnpm workspace or Nx)

# [Monorepo name]
## Layout
- apps/[web|api|admin], packages/[ui|config|types|auth]. Each package has its own CLAUDE.md.
## Commands
- Install `pnpm install` | Affected tests `pnpm nx affected -t test` | One package `pnpm --filter <pkg> test`
## Rules
- Apps may import packages. Packages never import apps. packages/types has no runtime deps.
- Changes to packages/auth or packages/config affect everything: run all affected tests.
- Read the package's own CLAUDE.md before editing inside it.
## Architecture reference
@docs/architecture.md

A.10 Identity or auth-heavy service

# [Auth service]
## Stack
- [Language/framework]. OIDC provider: [library|platform]. Sessions in [Redis].
## Conventions
- Use the vetted library for every protocol step. Never hand-roll JWT parsing, signature checks, or crypto.
- Authorization Code + PKCE for all public clients. Validate state and nonce. Exact-match redirect URIs.
- Access tokens short-lived; refresh tokens rotated and revocable.
- Identical errors and similar timing for unknown user vs wrong password (no enumeration).
## Security (IMPORTANT)
- Never log tokens, codes, passwords, or full identifiers.
- Any change in src/flows, src/tokens, or src/crypto: stop and request human security review.
- Run the security-reviewer agent before every commit.

For the protocol reasoning behind A.10, see the authentication implementation guide.