What is CLAUDE.md? The Project Guardrails File That Keeps AI Coding on Track
I spent weeks building a project with Claude. Everything went fine at first. Then my project got bigger. Claude started making weird decisions.
One session, it used const for everything. Next session, it switched to let. One day it organized files by feature. The next day, it put everything in folders by type. My codebase turned into a mess of inconsistent patterns.
I kept typing the same instructions every session. “Use TypeScript strict mode.” “Organize by feature, not file type.” “No console.log in production.” Over and over, wasting hours.
Then I found the solution: a single file called CLAUDE.md.
The Problem: Claude Has No Memory Across Sessions
Claude doesn’t remember what you told it yesterday. Every new session starts fresh. This works fine for small projects. But when you have 50+ files and complex architecture, things break down.
Here’s what happened to me:
- Session 1: Claude set up API routes with a specific error handling pattern
- Session 5: Claude added new routes with a completely different error handling approach
- Session 10: The codebase had 3 different ways to handle errors, and none of them worked together
I tried writing instructions in a README. Claude ignored them. I tried commenting extensively in the code. Claude still made inconsistent choices.
The Solution: CLAUDE.md as Project Constitution
CLAUDE.md is a markdown file you place in your project root. Claude reads this file at the start of every session. It acts like a constitution for your project.
# Project Guardrails
## Coding Style
- Use TypeScript strict mode- Prefer `const` over `let`- No console.log statements in production code- Max function length: 50 lines- Max file length: 500 lines
## File Organization
- Organize by feature, not file type- Each feature gets its own folder- Shared utilities go in `/utils`
## Error Handling
- Always wrap API calls in try/catch- Log errors with context- Return user-friendly error messages- Never expose internal details in errors
## Git Workflow
- Commit messages: `<type>: <description>`- Types: feat, fix, refactor, docs, test, chore- Create feature branches from main- Rebase before mergingThe key insight: this file persists across sessions. You write it once, Claude follows it forever.
Why This Works: Claude Reads It Every Time
When you start a Claude Code session, it automatically looks for CLAUDE.md in your project root. If it finds the file, it reads it as instructions before doing anything else.
This means:
- You don’t repeat yourself every session
- Claude has consistent context about your project
- New Claude sessions follow the same rules as old ones
- Your coding style stays uniform across the entire codebase
Real Example: How It Changed My Workflow
Before CLAUDE.md, my sessions looked like this:
Me: Help me add a new API endpointClaude: [writes code with different patterns than yesterday]
Me: Wait, can you follow the same error handling as the other endpoints?Claude: [rewrites code]
Me: And use the same folder structure?Claude: [moves files around]
Me: And no console.log please?Claude: [removes console.log]After CLAUDE.md:
Me: Help me add a new API endpointClaude: [writes code following all established patterns immediately]The difference is night and day.
Common Sections to Include
Based on my experience and what I’ve seen in other projects, here are the sections that provide the most value:
1. Coding Style Rules
## Coding Style
- Use 2-space indentation- Prefer arrow functions- No unused variables- Explicit return types for functions- Use Zod for runtime validationThese rules keep your codebase consistent. Without them, Claude might switch between arrow and regular functions, or add/remove type annotations randomly.
2. File Organization Patterns
## File Organization
- One component per file- Tests go next to the file they test- Keep related files in the same folder- Don't create deep nesting (max 3 levels)This prevents Claude from creating scattered file structures that make your project hard to navigate.
3. Error Handling Standards
## Error Handling
- Always use try/catch with async operations- Create custom error classes for different error types- Include stack traces in development- Show user-friendly messages in production- Log all errors to monitoring serviceConsistent error handling is critical for debugging. Without this section, Claude might mix patterns across the codebase.
4. Security Requirements
## Security
- Never commit secrets or API keys- Validate all user input- Use parameterized queries for database operations- Implement rate limiting on all endpoints- Run security linter before commitsSecurity rules are especially important. Claude might accidentally create vulnerabilities if you don’t specify constraints.
5. Testing Requirements
## Testing
- Write tests for all new features- Use describe/it blocks for organization- Mock external dependencies- Aim for 80% code coverage- Run tests before every commitTesting rules ensure Claude writes tests consistently and to your standards.
How Reddit Users Use It
I found a useful tip on Reddit from u/Fun_Nebula_9682, who mentioned using CLAUDE.md for a project called Bentu that took “an actual insane amount of work” and “MANY claude hours”:
“one tip if bentu keeps growing — drop a CLAUDE.md file in your project root with rules about your app’s behavior. as projects get bigger claude starts making weird decisions without guardrails, and that file keeps it on track without repeating yourself every session”
This confirms my experience: as projects grow, Claude needs more explicit guardrails to stay consistent.
Placement and Discovery
Claude Code looks for CLAUDE.md in these locations:
- Project root (most common)
- Current working directory
- Parent directories (walking up the tree)
For most projects, putting it in the root is the right choice. If you work in a monorepo, you might want one in the root and one in each sub-project.
Advanced: Conditional Rules
You can even make rules conditional:
## TypeScript Projects
<!-- This section only applies if tsconfig.json exists -->
- Use strict mode- No `any` types- Prefer interfaces for objects
## Python Projects
<!-- This section only applies if requirements.txt exists -->
- Use type hints- Follow PEP 8- Use Black for formattingClaude understands context and applies the right rules based on your project structure.
The Key Takeaway
CLAUDE.md is not just documentation. It’s active configuration that Claude reads and follows. One file, written once, saves hours of repeating instructions and prevents the “weird decisions” problem that plagues large projects.
If your project has more than 10 files and you work with Claude regularly, create a CLAUDE.md today. Start simple with your most important rules, then expand as you learn what Claude needs guidance on.
Final Words + More Resources
My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me
Here are also the most important links from this article along with some further resources that will help you in this scope:
Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!
Comments