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...
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 |
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. Stick to the essentials and link out to detailed specs when needed. |
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 |
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
- 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
- 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