Skip to main content
Template

CLAUDE.md Template for Any Repository

A 70-line starter CLAUDE.md: project, stack, commands, hard rules, how to verify work and what not to do.

By Matthews WongUpdated Checked against Claude Code 2.1.323 docs

Key takeaway

A starter CLAUDE.md you copy to the root of a repository and edit. It has eight short sections with bracketed placeholders: what the project is, stack, commands, directory map, hard rules, conventions, how to verify work and what not to do. Claude Code reads the file at the start of every session, so the template stays near 70 lines and leaves long procedures to skills.

1 file

The file

Exactly what the download contains. Read it first, then copy or download.

CLAUDE.md
# [Project name]

<!--
Starter CLAUDE.md. Save it at the repository root, replace every [bracketed]
part, and delete any section that has nothing true to say. Claude reads this
file at the start of every session, so each line should earn its place.
Comments like this one are for people; delete them when you are done.
-->

## What this project is

[One or two sentences: what it does, who uses it, and where it runs.]

## Stack

- Language and runtime: [for example TypeScript on Node.js 22]
- Framework: [name and major version]
- Data: [database, ORM or query layer]
- Tests: [test runner]
- Deploy: [how and where it ships]

## Commands

```bash
[dev command]     # start the app locally
[test command]    # run the tests; single file: [how]
[lint command]    # lint and format check
[build command]   # production build
```

## Directory map

```text
[src/app/]        [routes or entry points]
[src/lib/]        [shared logic]
[src/db/]         [schema and migrations]
[tests/]          [where tests live and how they are named]
```

## Hard rules

These break the build or production when ignored.

1. [Rule, and what fails when it is broken]
2. [Rule, and what fails when it is broken]
3. Never commit secrets. Configuration comes from [where].

## Conventions

- [Naming: files, functions, database columns]
- [Imports: the alias or the order to use]
- [Errors: how they are raised, logged and returned]
- Follow the patterns in the file you are editing before adding a new one.

## How to verify work

- Read a file before editing it, and the files that call it.
- For a bug, reproduce it first, then fix it, then run the same reproduction.
- After each change run `[test command]` and `[lint command]`, and report
  the real output. Do not say it works without running it.
- [Any check specific to this project, such as a type check or a migration
  dry run]

## What not to do

- Do not refactor or rename things outside the task unless asked.
- Do not add a dependency without asking.
- Do not edit [generated files or folders]; change [their source] instead.
- Do not commit or push unless asked. One logical change per commit.
- [Anything this team has been burned by before]
How to use it

From download to working

Use it when

  • You are starting to use Claude Code in a repository that has no CLAUDE.md yet.
  • Claude keeps guessing your test or build command, or keeps breaking the same rule.
  • Your current CLAUDE.md has grown long and you want a lean structure to move it into.
  • Your team wants the same sections in every repository.
  1. Save it at the repository root

    Download the file and save it as CLAUDE.md in the root of your repository. Claude Code also accepts .claude/CLAUDE.md. Commit it so the whole team shares the same instructions.

  2. Fill the commands first

    Replace the four command placeholders with the exact dev, test, lint and build commands. These are the lines Claude uses most, and the ones it cannot reliably guess.

  3. Write the hard rules from real failures

    List the few things that break the build or production, each with what fails. Be specific: a rule that names the file and the check is followed more consistently than a general one.

  4. Delete what you cannot fill

    Remove any section or bullet that has nothing true to say, and delete the comment at the top. An empty placeholder costs context in every session and tells Claude nothing.

  5. Start a new session and check

    Start Claude Code in the repository and run /memory, which lists your CLAUDE.md files, and confirm the project file is there. Then ask for a small change and watch whether it runs your test command without being told.

What is inside

Why it is written this way

Short, because it loads every session

Claude reads CLAUDE.md at the start of every session, and the docs set a target of under 200 lines per file because longer files use more context and reduce adherence. The template is about 70 lines, which leaves room for your own rules.

Commands in one code block

Dev, test, lint and build sit together with a comment each, including how to run a single test file. Claude can copy the exact command instead of working it out from package files.

Hard rules apart from conventions

Things that break the build are numbered and say what fails. Style preferences go under Conventions. Keeping them apart shows which lines are not negotiable.

A section on how to verify work

Read before editing, reproduce a bug before fixing it, run the tests after each change and report the real output. These working habits are filled in already, because they apply to almost any repository.

Notes for people in an HTML comment

The how-to note at the top is a block-level HTML comment. Claude Code strips such comments before the file reaches Claude's context, so you can keep maintainer notes there without spending tokens on them.

Watch for

What goes wrong

  • CLAUDE.md is context, not enforcement. For a rule that must never be broken, add a hook or a permission deny rule as well.
  • Do not paste your whole README or style guide into it. A long procedure that matters for one kind of task belongs in a skill, which loads only when needed.
  • Two instructions that contradict each other leave Claude to pick one. Review the file when the project changes and remove what is out of date.
  • Never put secrets, tokens or passwords in CLAUDE.md. It is committed to the repository and read into every session.
Questions

Frequently asked

Short answers before you download it.

Where does CLAUDE.md go?

Project instructions go in CLAUDE.md at the repository root, or in .claude/CLAUDE.md, and are shared with the team through version control. Personal instructions for all your projects go in ~/.claude/CLAUDE.md. Private notes for one project go in CLAUDE.local.md, which you add to .gitignore.

How long should a CLAUDE.md be?

The Claude Code docs set a target of under 200 lines per file, because longer files consume more context and reduce adherence. This template starts near 70 lines. When it grows, move instructions that matter for only part of the codebase into path-scoped rules or a skill.

Should I use /init or this template?

They work together. /init has Claude analyze your codebase and generate a starting CLAUDE.md with the commands and conventions it discovers. This template gives you the sections to check that draft against, including the hard rules and the what-not-to-do list that Claude cannot discover on its own.

Does Claude always follow CLAUDE.md?

Not always. The docs state that Claude treats the file as context, not enforced configuration, and that specific, concise instructions are followed more consistently. To block an action regardless of what Claude decides, use a PreToolUse hook.

Does a CLAUDE.md in a subfolder load too?

Yes, but later. Files in the working directory and every directory above it load at launch. A CLAUDE.md in a subdirectory loads on demand, once Claude reads or edits a file in that subdirectory. That makes subfolder files a good place for rules that apply to one part of a large repository.

Go deeper

Learn what this file packages

Free lessons and articles on this site that explain the ideas behind it.

Sources

Primary sources checked on the research date. Follow them for the current version.

More from the toolkit

Take these too

TemplateFree

.mcp.json Template for Team MCP Servers

A project .mcp.json with one stdio server and one HTTP server, with secrets and paths kept in environment variables.

  • Claude Code

2 files5.1 KB.zip

PromptFree

Plan Before Code Prompt

A planning prompt that covers business, domain, tech design and steps, then lists the decisions it needs from you.

  • Claude Code
  • Cursor
  • Claude.ai

1 file2.3 KB.md

MCP starterFree

MCP Server Starter in TypeScript

A stdio MCP server with two tools, a resource, a prompt and a smoke test, on the v2 SDK.

  • Claude Code
  • Claude Desktop
  • Any MCP client

9 files11.1 KB.zip

All toolkit items