7 CLAUDE.md Templates for Claude Code You Can Copy Into Real Projects

Most CLAUDE.md advice stops at “describe your tech stack.” That is not wrong, but it is not enough once Claude Code starts touching real work.

The useful question is not “Should I have a CLAUDE.md?” The useful question is: what should the file say for this specific repo so Claude Code stops making the same mistakes?

This guide fills the gap between the beginner example in the getting started guide and the broader rules in CLAUDE.md best practices. Instead of theory, you will get seven templates you can copy into real projects today.

If you want the shortest path:

1. Keep the free Claude Code Quick Reference Cheatsheet open.
2. Copy the template closest to your repo.
3. Add the “do not do this” rules before the “nice to have” notes.
4. If you want a larger template pack plus setup, hooks, and permissions examples, get The Complete Claude Code Setup & Configuration Guide.
5. If you need help standardizing this for a team, use the consultation page.

What a good CLAUDE.md actually does

A strong CLAUDE.md should reduce three specific failure modes:

• Claude Code edits the right area but uses the wrong local convention.
• Claude Code solves the task but skips the verification step you care about.
• Claude Code explores far too much because the repo boundaries are unclear.

That means a useful file usually includes:

• tech stack and commands
• directory map
• project-specific rules
• preferred workflow order
• prohibited actions or anti-patterns

The missing piece in many guides is the last two bullets. Claude Code gets better much faster when you tell it how to work and what not to do.

Template 1: Solo web app

Use this when you are the only developer and the repo is reasonably clean.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

The critical line here is not the stack. It is the instruction to verify mobile width and public URLs. That turns “it built” into “it shipped correctly.”

Template 2: Content site with revenue CTAs

This is the right shape for a site that publishes articles, free PDFs, and paid products.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

This style is useful because it teaches Claude Code the real KPI hierarchy. If you run a content business, a generic engineering template is too weak.

Template 3: Backend API repo

This one works for service code where data integrity matters more than layout.

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

The phrase “summarize risk in plain English” is underrated. It pushes Claude Code to explain impact instead of pretending every change is routine.

Template 4: Team repo with strict review

If multiple developers share the repo, your CLAUDE.md should reinforce collaboration boundaries.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

This template reduces one of the most common team complaints: the agent was technically productive, but the patch was hard to review.

Template 5: Legacy codebase rescue

Legacy repos need more guard rails because “clean it up” can easily become destructive.

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

For legacy work, “compatibility over elegance” is often the single highest-value sentence in the file.

Template 6: Scripts and automation repo

Use this for repos where the main risk is side effects rather than application bugs.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

This is the template I would reach for first if the repo touches deploys, outreach, content generation, or third-party APIs.

Template 7: Multi-package or monorepo setup

Monorepos fail when Claude Code does not know which package owns the behavior.

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

The key idea is ownership. Many bad monorepo edits happen because the agent crosses package boundaries too quickly.

The failure cases to avoid

Failure 1: Writing a company wiki inside CLAUDE.md

Long background essays waste tokens. Keep explanations short and operational.

Failure 2: Listing tools but not workflows

npm run test is useful, but “run tests after editing billing logic” is more useful.

Failure 3: Missing anti-rules

If a repo has one dangerous behavior, write it down. “Do not force push.” “Do not touch .env.” “Do not ship without public URL verification.” These lines prevent expensive mistakes.

Failure 4: Never updating the file

If Claude Code repeats the same error three times, your CLAUDE.md is probably underspecified.

How to choose the right template

Use this shortcut:

• Choose the solo app template if the repo is mainly product or UI work.
• Choose the content-site template if articles, PDFs, products, or multilingual publishing matter.
• Choose the API template if validation and data correctness matter most.
• Choose the team or monorepo template if coordination risk is the real bottleneck.
• Choose the legacy or automation template if mistakes are expensive and guard rails matter more than speed.

You do not need to merge all seven into one file. Start with one base template, then add only the rules that change behavior.

Best next step

Start small:

1. Copy one template into CLAUDE.md.
2. Add three project-specific “do not” rules.
3. Add the exact verification step that defines success in your repo.

If you want a fast daily reference first, download the free Claude Code Quick Reference Cheatsheet. If you want more complete CLAUDE.md examples, setup checklists, hooks, permissions, and workflow patterns, get The Complete Claude Code Setup & Configuration Guide. If your team wants help turning these templates into a repeatable operating model, use the consultation page.

Related articles

• CLAUDE.md Best Practices
• Claude Code Approval and Sandbox Guide
• Complete Beginner’s Guide to Claude Code
• Complete Guide to Harness Engineering