CLAUDE.md Template

A copy-paste skeleton for a project-level CLAUDE.md. Adapt the stack, commands, architecture, and rules to your project. Delete any section that doesn’t apply.

This is the surface area only — the discipline behind what belongs in each section is in CLAUDE.md.

Skeleton

CLAUDE.md

## Project
[One line: what this project does and who uses it]

## Stack
[Framework, language, database, deployment target]

## Commands
- Dev: `[command]`
- Build: `[command]`
- Test single: `[command] -- [path]`
- Test all: `[command]`
- Lint: `[command]`
- Type check: `[command]`

## Architecture
- [folder] → [what lives here]
- [folder] → [what lives here]
- [folder] → [what lives here]
- [file] → [what this file does]

## Rules
- [Rule that prevents a specific mistake]
- [Rule that prevents a specific mistake]
- IMPORTANT: [The one rule Claude keeps breaking]

## Workflow
- [How you want Claude to approach tasks]
- [Commit conventions]
- [Testing expectations]

## Out of scope
- [Things Claude should not touch]
- [Files that are manually maintained]
- [Integrations Claude shouldn't modify]

Notes for adapting it

• Delete sections that don’t apply. A CLAUDE.md with three sections beats one with seven empty placeholders.
• Workflow rules are usually skill candidates, not system prompt material. If your workflow rules only matter for some tasks (e.g. “make minimal changes during refactors”), demote them to a skill. Keep CLAUDE.md for rules that apply on every read, edit, and trivial query. See CLAUDE.md for the test.
• Out of scope is high-leverage. A short list of paths Claude should treat as read-only — generated files, append-only logs, manually maintained migrations — prevents a whole class of “Claude rewrote my generated types” mistakes.
• Target under 80 lines. When it grows past that, prune before splitting via @import. Splitting reorganises but doesn’t reduce — only deleting and demoting do.

Worked example

Mapping a typical set of rules into the skeleton.

Always belong — keep in CLAUDE.md

# Stack
- Static export only, no SSR (deployed to S3).

# Security
- NEVER commit .env files or secrets.

# Conventions
- All async calls must use try/catch.
- Use functional components only — no class components.
- IMPORTANT: run type check after every code change.

Each rule above shapes behaviour on every read, every edit, every trivial query. That’s what belongs in CLAUDE.md.

Better as skills — don’t belong in CLAUDE.md

These are common candidates that CLAUDE.md recommends demoting:

• “Prefix commits: feat:, fix:, docs:, refactor:” — only applies at commit time. A skill triggered on commit (or a prepare-commit-msg hook) loads only when relevant — better than paying the cost on every session.
• “All PRs must pass npm run verify before merge” — better enforced by a CI check or a pre-push hook. The rule only matters at PR time.
• “Make minimal changes; don’t refactor unrelated code” — applies during edits, not on every read. Skill candidate.
• “Create separate commits per logical change” — applies at commit time only.

If you put these in CLAUDE.md because you want the reminder loaded on every session, accept the cost — methodology rules are the most common reason CLAUDE.md files bloat past their useful size.

The test for every rule you consider adding: does removing it cause Claude to do the wrong thing on the next trivial query? If not, the rule doesn’t belong there.