What is a CLAUDE.md file?
A CLAUDE.md file is a project-level instruction file for Claude Code. It gives the agent stable context about your repository, your team's conventions, and the way you want work to be done. Instead of repeating the same directions in every chat, you write them once in Markdown and keep them close to the code they describe.
The most common location is the root of a project repository, next to files such as package.json, README.md, or pyproject.toml. A repository-level CLAUDE.md should explain the project in terms that are useful during coding: how to install dependencies, how to run tests, where important modules live, what patterns should be followed, and what mistakes are easy to make. You can also keep global personal instructions in ~/.claude/CLAUDE.md. Global instructions are useful for preferences that apply across projects, while repository instructions should stay focused on local facts.
The file can contain code standards, commands, context, rules, and skill trigger guidance. For example, a frontend application might tell Claude Code to use existing components before creating new ones, run npm run build after changes, avoid unrelated refactors, and preserve user-authored files. A Python service might document how database migrations work, which test suite is fast enough for local verification, and which modules own specific boundaries. A team using reusable skills can also list when a skill should trigger, such as using a code review skill whenever a pull request diff is inspected.
This matters because Claude Code benefits from persistent, precise context. A good CLAUDE.md acts like long-term memory for the project. It reduces repeated setup questions, makes agent behavior more consistent, and helps prevent changes that technically compile but violate team conventions. The file does not replace code review or tests, but it improves the starting point of every agent session.
Treat CLAUDE.md as operational documentation for an AI collaborator. Write the parts that would save time if a new senior engineer joined the project today. Include the commands that actually work, the architecture decisions that are not obvious from file names, and the constraints that matter in production. Avoid vague encouragement. Prefer concrete rules that can be followed and verified.
A useful file usually starts with a short project summary. Describe what the application does, who uses it, and which parts of the repository are most important. Then list the development commands that should be used during ordinary work. If your project has multiple package managers, multiple test runners, or a separate database migration workflow, document the correct path clearly. This helps Claude Code choose the same workflow your team expects.
Next, add coding standards that are specific enough to affect edits. For example, say whether new React components should be server components by default, whether API handlers must use a shared validation helper, or whether SQL changes require migration files and seed updates. In a backend service, mention transaction rules, logging expectations, retry behavior, and modules that should not import from each other. In a frontend app, mention design system usage, accessibility requirements, routing conventions, and localization requirements.
You can also use CLAUDE.md to capture review preferences. If the team wants risk-first code review, say that findings should lead and summaries should be secondary. If every bug fix needs a regression test, say so. If generated files should not be edited manually, name them. These instructions are especially helpful because they apply before the agent starts making changes, not after a mistake has already been made.
# Project Instructions ## Commands - npm run dev: start the local Next.js server - npm run build: compile and type-check before finishing - npm run lint: run lint checks ## Code Standards - Use existing components and utility functions first. - Keep API routes small and validate request bodies. - Do not commit secrets, sample tokens, or private customer data. ## Context This app uses Next.js App Router, Supabase, Tailwind CSS, and next-intl. Localized routes live under src/app/[locale]. ## Skill Triggers - Use the code-review skill when reviewing a diff. - Use the docs skill when adding public documentation pages.
Keep the file short enough to scan but complete enough to guide real work. If it grows too large, split detailed references into separate docs and link to them from the main file. The best version is not a policy encyclopedia; it is the set of facts and rules that prevents the next avoidable mistake.
Shared examples are useful because teams often discover better patterns by comparing instructions. A strong CLAUDE.md for a design system looks different from one for a data pipeline, a mobile app, or an internal operations tool. Browse examples, copy the pieces that match your workflow, then edit aggressively so the final file describes your project rather than a generic ideal.
Review the file whenever the project changes. New build tools, renamed directories, added services, and changed release processes should be reflected quickly. Stale instructions are worse than missing instructions because they make the agent confidently follow the wrong path. Keep the file in source control so edits are reviewed with the same care as other engineering changes.
Finally, remember that CLAUDE.md is not only for Claude. It is also readable documentation for humans. The act of writing clear agent instructions often exposes missing project documentation, unclear ownership, or commands that only work on one machine. A small, accurate file can improve both AI-assisted development and ordinary team onboarding.
Before publishing a CLAUDE.md, remove private URLs, customer names, tokens, internal hostnames, and deployment secrets. It is fine to share structure, commands, standards, and examples. It is not fine to leak credentials or proprietary details by accident.