CLAUDE.md templates — Claude Code Arsenal

$ cat CLAUDE.md · TEMPLATES

Four memory layers, copy-ready

Each layer has one job: behavior goes global, facts go per-project, local rules per directory, privacy in local. These templates follow the official docs and community best practice and are deliberately lean — use them as skeletons and fill in your real facts, don't paste them verbatim.

memory-hierarchy

~/.claude/├── CLAUDE.md ← globalon startup└── skills/← personal skills · all projects~/work/my-app/← you runclaudehere├── CLAUDE.md ← project · shared via giton startup├── CLAUDE.local.md ← personal prefsgitignore├── .claude/skills/← project skills└── src/ └── CLAUDE.md ← directory ruleslazy# startup walks up from cwd collecting CLAUDE.md;# subdir files inject when Claude reads that dir;# sibling directories never interfere.

SCOPE·ALL PROJECTSBehavior layer

Save at

~/.claude/CLAUDE.md

Loads

Loaded at the start of every session, for every project on this machine

Put in

Cross-project behavior rules that never change: language of communication, confirmation for destructive ops, engineering discipline, environment facts (timezone / default package manager)

Keep out

Anything project-specific — that belongs in the project layer; skip persona prompts too, words that don't change behavior just burn attention

~/.claude/CLAUDE.md

# Global working rules (apply to every project on this machine)

## Communication
- Reply in English; keep code, commands, and error messages verbatim
- Conclusion first, then reasoning; if unsure, say so — never invent APIs or config options

## Boundaries
- Deleting files, git push --force, database migrations, CI config edits and other
  destructive / high-impact operations: state the blast radius and get my approval first
- Never write secrets, tokens, or passwords into code or commit history;
  proactively warn me if .env or credentials look at risk of leaking
- Do not bump major versions of dependencies on your own

## Engineering discipline
- Minimal diffs: do only what was asked — no drive-by refactors, no extra abstractions
- After fixing a bug, run the relevant tests before calling it done
- Use Conventional Commits (feat/fix/chore/docs…)
- If the same task fails twice in a row, stop and restate your understanding of the problem

## My environment
- Timezone Asia/Shanghai; macOS + zsh; Node ≥ 20; pnpm as the default package manager

SCOPE·THIS REPOProject facts layer

Save at

Repo root ./CLAUDE.md, committed to git and shared with the team

Loads

Loaded on startup anywhere inside the repo (including subdirectories)

Put in

Five things: commands, structure, conventions, minefields, workflow — everything Claude can't infer from the code and would pay dearly for guessing wrong; the "commands to run verbatim" line is the single highest-value item

Keep out

Long architecture recaps (one @ reference to docs is enough), anything Claude can self-learn in a session, and multi-step procedures (make those a Skill)

./CLAUDE.md

# MyApp — project context

> E-commerce admin console · Next.js 15 + TypeScript + Prisma + PostgreSQL
> Architecture details live in @docs/architecture.md — not repeated here

## Commands (run verbatim, don't guess)
- Dev:          pnpm dev
- All tests:    pnpm test
- Single test:  pnpm test -- --grep "keyword"
- Quality gate: pnpm lint && pnpm typecheck
- Migrations:   pnpm db:migrate (local DB only; production migrations go through CI)

## Directory map
- app/        routes and pages (App Router)
- app/api/    API routes; auth middleware in app/api/_lib/
- lib/        domain logic and data-access wrappers
- prisma/     schema and migrations
- tests/      e2e; unit tests sit next to sources as *.test.ts

## Conventions
- TypeScript strict, no any; components use named exports only
- Data access goes through lib/db.ts — never new PrismaClient directly
- Styling is Tailwind only: no inline style, no new UI libraries
- New features ship with Vitest cases in the same directory

## Minefields (violations cause incidents)
- Existing files under prisma/migrations/ are read-only
- Signature-verification logic in app/api/webhooks/* must not be touched
- CI runs Node 20 — don't use APIs from newer versions

## Workflow
- Changes touching >3 files: propose a plan and get approval first
- Before finishing: pnpm lint && pnpm typecheck && pnpm test must pass

SCOPE·ONE DIRECTORYLocal rules layer

Save at

Any subdirectory, e.g. src/components/CLAUDE.md

Loads

Lazy-loaded — injected only when Claude reads files in that directory; sibling directories never see it, which saves context for free

Put in

Rules that hold only for this slice of code: component standards, module-specific test setups, per-package build commands in a monorepo

Keep out

Repo-wide conventions — push those up a layer or they get diluted by repeated loading; if a rule seems ignored, run /memory first to check whether it has even loaded

src/components/CLAUDE.md

# components/ rules (apply only while working in this directory)

- One folder per component: index.tsx + types.ts + *.test.tsx
- Base controls come from @/components/ui only — no new component libraries
- Prefer local useState; cross-component state goes through zustand (see @/stores)
- Server data flows through query hooks in hooks/ — no fetch inside components
- Every new component ships with *.stories.tsx (Storybook) alongside
- Accessibility: interactive elements need a visible focus state and aria labels

SCOPE·ONLY YOUPersonal layer

Save at

Repo root ./CLAUDE.local.md, added to .gitignore

Loads

Loaded on startup but never shared with the repo — team rules and personal taste stay separate

Put in

Personal environment and preferences: local service URLs, test-account pointers, your own communication habits

Keep out

Real secrets and passwords — write where to get them, not the values; gitignore is not a vault

./CLAUDE.local.md (remember to gitignore)

# Personal preferences (gitignored, not shared with the team)

- Local database: postgresql://localhost:5433/myapp_dev
- Local services: web 3000 / api 4000 / mail preview 8025
- Demo account: demo@local (password in team 1Password "MyApp Dev")
- Explain things to me in English; keep commit messages in English
- I'm on macOS + zsh — no Windows paths or PowerShell commands, please