How to Write CLAUDE.md and What It Changes: Controlling AI Behavior Through a Project Configuration File
What CLAUDE.md Is
CLAUDE.md is the file Claude reads first when beginning work on a project. When this file is placed at the root of the project directory, AI references it before starting any task and uses the policies, constraints, and structural explanations it contains to guide its behavior.
In short, it is how I tell AI in advance how it should behave in this particular project.
Before and After Adding CLAUDE.md
Without CLAUDE.md, AI operates on general judgment. Here is a specific problem that illustrates the difference.
While building this site, I had communicated to AI that it should only run the production deployment command after receiving my explicit approval. But I had not written this anywhere in a configuration file. On several occasions, in the middle of other tasks, AI attempted to execute the production deployment command. It was not acting maliciously. It had judged the deployment step as a necessary part of completing the work.
After I added the following to CLAUDE.md, that problem stopped occurring.
## Non-Negotiable Rules
- Do not run `npm run build` without explicit user approval. It triggers a production deployment.Three Types of Content That Work Well in CLAUDE.md
There are three categories of content that consistently improve AI behavior when included in CLAUDE.md.
Prohibition rules
These specify what AI must never do. Examples: “Do not run the production deployment command without approval,” “Do not modify the existing navigation structure,” “Do not commit sensitive information.” Writing prohibitions as direct statements rather than conditional rules makes them more effective.
Term definitions
These clarify the meaning of project-specific vocabulary. For example: “In this project, ‘blog’ refers to files under src/content/blog/” and “Documents refers to files under src/content/docs/.” Without these definitions, AI can interpret an instruction like “write an article” in ways that lead it to the wrong directory.
Directory structure explanation
This tells AI where things are. As a project grows, it becomes easier for AI to misplace files or look in the wrong location. Explaining the role of each major directory in CLAUDE.md helps AI place and reference files correctly.
Guidelines for Writing CLAUDE.md
It is important not to let CLAUDE.md grow too long. If I try to write every rule into this single file, AI processes a large volume of text every time it begins a task, and important rules become difficult to find.
The practical approach I use is to write only the overall project orientation and the most critical rules in CLAUDE.md, and to move detailed rules and procedures into separate files under shared/rules/ and shared/skills/. CLAUDE.md then points to those files for specifics.
Summary
CLAUDE.md is the file that tells AI “how to behave in this project” once, eliminating the need to repeat the same explanations in every conversation. Writing prohibition rules, term definitions, and directory structure explanations in this file stabilizes AI behavior across sessions. The next article in this series covers how lessons.md records past problems to prevent them from repeating.