How to Write CLAUDE.md: Three Types of Effective Instructions
What you’ll learn
- How CLAUDE.md gives Claude Code the project’s working assumptions
- Three useful categories of content, including Non-Negotiable Rules
- How to keep the file focused on persistent instructions and write concrete, verifiable rules
Keep CLAUDE.md Focused on Repeated Working Assumptions
CLAUDE.md is a document that gives Claude Code a project’s assumptions and policies. Recording agreements that you have been explaining in each conversation makes them available for later work.
It does not need to contain everything. On this site, I record recurring assumptions such as operations requiring approval, the meaning of terms, and where files belong. The examples below distinguish instructions to keep in CLAUDE.md from requests handled in a conversation or controls configured in the execution environment.
Design the Boundary of Standing Instructions in CLAUDE.md
This article uses a CLAUDE.md file in the project’s top-level folder. Claude Code’s memory and settings have several scopes, and the instructions consulted can vary with the working location and configuration.[1][2]
The text in CLAUDE.md guides how AI decides to work. Reliably blocking a particular operation also requires settings that restrict what can be executed.
Before and After Adding CLAUDE.md
While building this site, I told AI in conversation that deployment operations required my explicit approval. I had not recorded that instruction in the project file, however, and AI tried to run a production build during other work on several occasions.
I added the following rule to CLAUDE.md.
## Non-Negotiable Rules
- Do not run `npm run build` without explicit user approval. It triggers a production build.Afterward, AI was more likely to ask before running the command. Text alone does not forcibly stop an operation, however. Operations that must be blocked also need permission settings or hooks. Hooks run automated processing at defined points, such as before or after a command.
Put Prohibitions, Terminology, and Directory Structure in CLAUDE.md
On this site, I group recurring assumptions into three kinds of instruction.
Prohibition rules
Record operations to avoid and their approval conditions: “Do not run the production build without approval,” “Do not change the existing navigation,” or “Do not commit sensitive information.” A commit saves file changes in the version history. The instruction should still state what is prohibited when permission settings or hooks also block execution.[2]
Term definitions
Record project-specific meanings, such as “Blog refers to files under src/content/blog/; documentation refers to files under src/content/docs/.” These definitions establish a shared assumption when the word “article” alone does not identify where a file belongs.
Directory structure explanation
A directory is a folder that groups files. Explain what belongs in each major folder. A term definition establishes what “blog” means; the directory guide helps locate existing files and place new ones.
Keep CLAUDE.md Short, Specific, and Persistent
Putting every procedure in CLAUDE.md lengthens instructions unrelated to the current task and makes priority rules harder to find.
On this site, I keep the project overview and the most important rules in CLAUDE.md. Detailed rules live under shared/rules/, and task-specific procedures under shared/skills/, with references from CLAUDE.md.
Summary: Keep CLAUDE.md Focused on Standing Instructions and Separate It from Enforcement
Whether an assumption belongs in CLAUDE.md depends on whether later work will need it too. Recurring prohibitions, term definitions, and file locations are worth recording. One-time requests can stay in conversation, while detailed procedures can live in separate documents so priority agreements remain easy to find.
Recording an instruction and blocking an operation are separate tasks. State approval requirements in CLAUDE.md, and use permission settings or hooks where reliable blocking is needed. Recording past problems and their resolutions leads to lessons.md, covered in a separate article.
References
- Anthropic, How Claude remembers your project, Claude Code Docs
- Anthropic, Claude Code settings, Claude Code Docs
For the latest releases and updates, check the official website and official documentation.