CLAUDE.md Guide: Tailoring Claude Code to Your Project

When you start using Claude Code, you may find yourself explaining the same things over and over — "this project uses TypeScript," "tests are written with Jest," "commit messages should be in English." Repeating that context every session gets tedious. CLAUDE.md lets you write that information once so Claude Code can pick it up automatically at the start of every conversation.

How Claude remembers your project - Claude Code Docs

Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automa...

docs.anthropic.com

What Is CLAUDE.md?

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every conversation. You can place it in multiple locations — each serving a different purpose. Since Claude Code loads all of them together, you can keep shared rules global and project-specific rules local.

Location	Scope	Primary use
./CLAUDE.md	Current project	Project-specific rules and setup
~/.claude/CLAUDE.md	All projects	Personal preferences and general rules
./subdir/CLAUDE.md	Subdirectory and below	Supplemental info for a specific directory

These locations also differ in when they're loaded. The project root's CLAUDE.md is loaded all at once when Claude Code starts, while a CLAUDE.md in a subdirectory is loaded on demand, only when Claude Code actually reads a file in that directory. In a project where frontend and backend code live side by side in the same repository, placing a dedicated CLAUDE.md in each directory means Claude Code doesn't have to load irrelevant context all the time.

What to Include

The right content for CLAUDE.md is anything you'd otherwise have to explain at the start of every conversation. Here are the main categories.

Project Overview and Tech Stack

Listing the languages, frameworks, and libraries you use helps Claude Code choose the right syntax and packages in its responses.

## Project Overview

- Frontend: Next.js 14 (App Router), TypeScript
- Backend: Go 1.22, Gin framework
- Database: PostgreSQL 16
- Testing: Jest (frontend), testify (backend)

Development Rules and Coding Conventions

Team-specific rules around commit messages, branch naming, and code style lead to more consistent suggestions from Claude Code.

## Development Rules

- Write commit messages in English following Conventional Commits format
- Branch names follow the `feature/YYYY-MM-DD-slug` format
- Use 2-space indentation

Frequently Used Commands

Including build, test, and deploy commands makes it easier for Claude Code to suggest the right ones.

## Commands

- `npm run dev` — Start development server
- `npm run test` — Run tests
- `npm run build` — Production build

Notes and Restrictions

It's also worth documenting what you don't want Claude Code to do — for example, "don't include database credentials in code" or "don't add this library." Spelling out constraints helps prevent unwanted suggestions.

## Notes

- Do not leave `console.log` in code
- Avoid using `any` type
- Consult before adding external libraries

How to Write It Well

A longer CLAUDE.md isn't necessarily a better one. Concise and well-structured content works best. Here are a few tips to keep in mind.

Tip	Details
Use bullet points and headings	Claude Code reads the file top to bottom, so structure helps key information land. Bullet points and tables work better than long paragraphs.
Be specific	"TypeScript 5.4, running in strict mode" gets more accurate responses than just "using TypeScript." Include actual version numbers and config values rather than vague descriptions.
Keep it up to date	CLAUDE.md isn't a one-time document — update it as your project evolves. Outdated information gives Claude Code a misleading picture of your project.
Don't let it grow too long	A very long CLAUDE.md buries the important details. Aim for around 200 lines and stick to the essentials to keep responses accurate.

Importing Other Files

CLAUDE.md supports a @path syntax for pulling in other files. The imported file's contents are expanded and loaded into context alongside CLAUDE.md.

See @README for a project overview.
See @package.json for the available npm commands.

This means you don't have to copy information that already lives in your README or package.json into CLAUDE.md, avoiding duplicate upkeep. Relative paths resolve relative to the file that contains the import, and an imported file can import further files of its own, up to a maximum depth of four hops.

Behavior With and Without CLAUDE.md

Claude Code works without CLAUDE.md, but you'll need to explain your project's context manually every session. Including a CLAUDE.md in your repository is especially valuable for teams — new members can start using Claude Code effectively right away without any extra onboarding.

Without CLAUDE.md	With CLAUDE.md
Claude Code infers the language and framework by reading your code	Conversation starts with full project context already loaded
No knowledge of project-specific rules, so suggestions tend to be generic	Suggestions reflect your coding conventions and available commands
You need to re-explain "we use X in this project" every session	Constraints like "don't use X" are respected automatically
Repeating the same instructions fills up the conversation context	Sharing it with the team means everyone uses Claude Code with the same context

Generating One with a Command

If starting from a blank CLAUDE.md feels daunting, you can generate a first draft with a Claude Code slash command. Running it analyzes your codebase and produces a CLAUDE.md covering things like build commands, testing instructions, and project structure. If a CLAUDE.md already exists, it isn't overwritten — you're offered suggested improvements instead.

Rather than using the generated content as-is, it helps to treat it as a starting point: as you work, add the bits you notice yourself repeating — "Claude made the same mistake twice" or "I keep explaining this the same way" — and the file grows into something that actually fits your project.

CLAUDE.md Sample

Here's an example CLAUDE.md based on everything covered above. Adjust the content to match your own project.

## Project Overview

This repository consists of a Next.js 14 (App Router) + TypeScript frontend and a Go 1.22 + Gin backend.

## Tech Stack

- Frontend: Next.js 14 (App Router), TypeScript 5.4 (strict mode)
- Backend: Go 1.22, Gin framework
- Database: PostgreSQL 16
- Testing: Jest (frontend), testify (backend)

## Commands

- `npm run dev` — Start development server
- `npm run test` — Run frontend tests
- `go test ./...` — Run backend tests
- `npm run build` — Production build

## Development Rules

- Write commit messages in English following Conventional Commits format (e.g., `feat: add user profile page`)
- Branch names follow the `feature/YYYY-MM-DD-slug` format
- Avoid using `any` type
- Consult before adding external libraries

Summary

This article covered the basics of CLAUDE.md, what to include, how to write it well, and its import feature. If you're using Claude Code with a team, keep these points in mind as you grow your CLAUDE.md over time.

• CLAUDE.md is a file Claude Code reads automatically, letting you share project context across every conversation
• Include your tech stack, development rules, frequently used commands, and any restrictions
• Structure with bullet points and headings, and be specific — it leads to more accurate suggestions
• Splitting CLAUDE.md across subdirectories lets Claude Code load only the context it needs, on demand
• The import feature lets you reuse existing files like your README, avoiding duplicate upkeep
• Without it, you repeat the same explanations every session; with it, Claude Code starts each conversation already informed
• Keep it updated as your project changes