Claude Code CLAUDE.md Starter Template: The Smallest File That Prevents Repeated Mistakes

A weak CLAUDE.md makes every Claude Code session start colder than it should

If you keep explaining the same project rules to Claude Code, the problem is not only prompting. The project needs a small operating file that records commands, guardrails, and done criteria.

This starter template is for existing codebases. It pairs well with Claude Code First Task Runbook.

What the starter template should contain

You do not need a giant policy document. Start with stack, commands, risky paths, output preferences, and definition of done.

# CLAUDE.md

## Project snapshot
- stack: Astro + TypeScript
- package manager: npm
- main app: site/

## Commands
- dev: cd site && npm.cmd run dev
- build: cd site && npm.cmd run build

## Guardrails
- do not touch: .env, dist, generated exports
- ask before: destructive git commands, production deploys, secret rotation

## Definition of done
- code change is applied
- verification command has run
- remaining risks are stated

That is enough to make the next session more stable.

Example for a content site

For an Astro content site, add rules for matching slugs across locales, setting pubDate and updatedDate intentionally, requiring heroImage, and verifying live h1, canonical, body language, and CTA links.

The failure mode to avoid is having every locale file present while the non-English body is still English. Correct frontmatter is not enough.

When to add more rules

Grow CLAUDE.md only after repeated pain. Add exact build commands after build confusion, multilingual rules after locale drift, review expectations after shallow reviews, and deploy verification after stale pages.

Next step

Use the free cheatsheet if you need command reminders. Buy Setup Guide if permissions, hooks, MCP, or CLAUDE.md quality are the real bottleneck. Use consultation for team operating rules.