# CLAUDE.md Template: Free Starter File for Claude Code

> Free CLAUDE.md template for Claude Code: a short starter with stack, commands, directory map, hard rules, verification steps and a what-not-to-do list.

URL: https://www.matthewswong.com/en/toolkit/claude-md-template/

- Author: Matthews Wong (https://www.matthewswong.com/en/about/)
- Updated: 13 November 2026
- 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.

- Type: Template
- Works with: Claude Code
- Download: [CLAUDE.md](https://www.matthewswong.com/downloads/toolkit/claude-md-template/CLAUDE.md) (2.1 KB)
- License: Free to use, change and share, at work too.

## The file

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

### CLAUDE.md

````markdown
# [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]
````

## 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.

## From download to working

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.

## 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.

## 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.

## FAQ

### 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.

## Learn what this file packages

- Free lesson: [CLAUDE.md File Example: Global, Project and Local Layers](https://www.matthewswong.com/en/learn/claude-code-tips/claude-md-file-example/)
- Free lesson: [Where to Put Instructions in Claude Code: A Decision Guide](https://www.matthewswong.com/en/learn/claude-code-tips/where-to-put-instructions-claude-code/)
- [How to Write a CLAUDE.md That Improves AI Output](https://www.matthewswong.com/en/blog/writing-claude-md-memory-guide/)
- [How to Write a CLAUDE.md File That Works in Claude Code](https://www.matthewswong.com/en/blog/cara-menulis-claude-md-yang-efektif/)
- [AGENTS.md vs CLAUDE.md: Agent Context Files](https://www.matthewswong.com/en/blog/agents-md-vs-claude-md/)

## Sources

- [Claude Code docs: How Claude remembers your project](https://code.claude.com/docs/en/memory)
- [Claude Code docs: how CLAUDE.md files load](https://code.claude.com/docs/en/memory#how-claude-md-files-load)

[All toolkit items](https://www.matthewswong.com/en/toolkit/)

---

- HTML version: https://www.matthewswong.com/en/toolkit/claude-md-template/
- Bahasa Indonesia: https://www.matthewswong.com/id/toolkit/claude-md-template/
- Site index for agents: https://www.matthewswong.com/llms.txt
- Sitemap: https://www.matthewswong.com/sitemap.xml
- API description (OpenAPI): https://www.matthewswong.com/openapi.json
