Claude Code CLAUDE.md Starter Template for Existing Codebases

CLAUDE.md is the smallest useful operating file

Claude Code becomes much more useful when it knows how your repository actually works. Without a persistent project file, every session starts with the same warm-up: which package manager to use, where the app lives, which directories are generated, which commands are safe, and what “done” means. That repeated explanation is not just annoying. It creates inconsistent work.

The practical fix is a small CLAUDE.md. The official Claude Code memory documentation describes CLAUDE.md as persistent instructions loaded into a session. It also makes an important distinction: this file is context, not a hard enforcement layer. If you need to block a command or path, combine the file with settings, permissions, hooks, CI, and repository rules. The security documentation is worth reading before you let an agent work near secrets, deploy scripts, or destructive git commands.

This article gives you a starter file that works for an existing codebase, not a greenfield demo. It is intentionally short. A useful CLAUDE.md should act like a harness, meaning a practical scaffold that keeps the agent oriented while it works. For broader patterns, read Claude Code CLAUDE.md templates and the Claude Code permissions guide.

Copy-paste CLAUDE.md starter template

Start with facts Claude should use in nearly every session. Do not turn the first version into a full company handbook. You can add rules after real failures, but the first file should cover project shape, commands, boundaries, quality rules, and done criteria.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Save this at the repository root as CLAUDE.md. If the project already has an AGENTS.md, the memory docs show that Claude Code reads CLAUDE.md, not AGENTS.md; create a small CLAUDE.md that imports the existing file and then adds Claude-specific rules. Personal notes belong in CLAUDE.local.md or user-level memory, not in a team-shared file.

Put enforcement in settings, not prose

The template tells Claude how to behave, but it does not enforce safety by itself. A common mistake is writing “do not push” in CLAUDE.md and assuming that is enough. It is not. Use settings for tool permissions and use CLAUDE.md for intent, review style, and project context.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Place that kind of configuration in .claude/settings.local.json for a personal guardrail or .claude/settings.json for a shared project default. Before copying it into a real repository, confirm the current schema in the official settings page. The exact tools you allow should match the work. A content update needs read, edit, search, and validation commands. A deployment workflow needs a much more careful boundary.

Three real use cases

Use case	What to write in CLAUDE.md	What improves
Localized article maintenance	Target slug, locale list, frontmatter fields to preserve, body length, CTA rules, verification steps	Fewer missing locales, English leftovers, broken CTAs, and stale dates
Small SaaS bug fix	Editable directories, test command, database change approval, logging expectations	Less drive-by refactoring and fewer risky migrations
Team code review	Severity format, file and line references, reproduction steps, test-gap reporting	Reviews become actionable instead of vague approval text

For localized content, the file should say exactly which locale directories matter and which fields must not change. That prevents a worker from improving only blog-en while leaving blog-fr or blog-id thin. It also helps preserve revenue paths such as products, training, and lead forms.

For SaaS bug fixes, the useful rule is not “write good code.” It is “read the failing component, patch the smallest surface, run the matching test, and do not modify billing or auth without explicit approval.” Claude Code can often see nearby improvements, but a paid product benefits from controlled scope.

For code review, define the output before the review starts. Ask for severity, file path, line number, user impact, reproduction, and missing test. The official CLI reference is useful when you want to run a one-shot review from a script instead of staying in an interactive terminal.

Concrete pitfalls to avoid

The first pitfall is making the file too broad. A 300-line policy file looks serious, but it burns context and is less likely to be followed. Keep the project file under active maintenance. When a rule is only relevant to one directory, move it to a path-scoped rule or a local workflow document.

The second pitfall is mixing secrets into instructions. Do not place API keys, customer names, private dashboard links, or unreleased revenue numbers in CLAUDE.md. Write the handling rule instead: secrets live in environment variables, never print them, and ask before opening files that may contain them.

The third pitfall is keeping stale commands. If the repository moved from Jest to Vitest, from Yarn to npm, or from Next.js to Astro, update the commands immediately. Stale instructions are worse than no instructions because they make Claude Code confidently run the wrong thing.

The fourth pitfall is using the file as a substitute for review. CLAUDE.md can ask for validation, but it cannot prove the validation happened. Ask for a final verification receipt: command run, result, files touched, links checked, and known risks. That habit catches many small publishing mistakes.

A practical rollout sequence

Adopt the file in four passes. First, write the minimal version from this article. Second, use it on three small tasks: one content edit, one small UI patch, and one review. Third, add only the rules that would have prevented an actual mistake. Fourth, move hard boundaries into settings, CI, branch protection, or deployment approvals.

The same sequence works for an individual blog and for a team repository. A solo builder mainly needs repeatable commands and fewer forgotten checks. A team also needs ownership, permission mode, review policy, and onboarding notes. If you try to solve all of that in the first CLAUDE.md, the file becomes unreadable before it becomes useful.

There is also a business reason to keep the file clear. Articles, landing pages, checkout links, product cards, and consultation forms are revenue surfaces. If Claude Code changes markup or translations without checking those paths, traffic can keep flowing while conversions quietly break. Put CTA checks into the done criteria.

For reusable prompts, setup material, and checklists, use the ClaudeCodeLab products page. For a team rollout with permissions, review gates, training material, and repository-specific CLAUDE.md rules, use Claude Code training and consultation. The best starting file is not the longest file. It is the smallest file that prevents the next repeated mistake.