You've got Claude Code running and completing tasks. Now make it work better by giving it the full picture of your project.
Claude Code reads your entire codebase, but it doesn't automatically understand your project's conventions, architecture, or business logic. A CLAUDE.md file in your project root changes that. Think of it as a briefing document that Claude reads at the start of every session.
Create your first CLAUDE.md file
Navigate to your project root and create a file called CLAUDE.md. Start simple:
# Project Overview
This is a Node.js API that manages user authentication and todo items.
## Tech Stack
- Express.js server
- PostgreSQL database
- JWT for authentication
- Jest for testing
## Code Style
- Use async/await, not promises
- Prefer functional components
- All database queries go through the models/ directory
- Write tests for new features before implementing
Save the file and run Claude Code on any task. It now knows these basics about your project.
What to include in CLAUDE.md
Architecture decisions matter most. Explain why you structured things the way you did. "User data flows through UserService before hitting the database" tells Claude more than listing your file structure.
Coding preferences save time. Instead of Claude guessing whether you use tabs or spaces, just say "Use 2-space indentation and semicolons." Include your preferred libraries: "Use lodash for utility functions, not native array methods."
Business context prevents mistakes. "Users can only see their own todos" stops Claude from writing code that exposes other users' data. "The admin role has special permissions" explains why some functions check user roles.
Review checklists catch issues. Add a section like "Before committing: run tests, check for console.logs, update documentation." Claude will remind you of these steps.
How Claude Code reads your project
Claude Code scans your entire codebase before starting work, but it prioritizes information differently than you might expect.
File structure comes first. Claude maps out your directories and understands the relationships between files. A well organized project with clear naming helps Claude work faster.
Recent changes get attention. Files you've modified recently carry more weight. Claude assumes these are the active areas where you want help.
CLAUDE.md overrides everything. Whatever you write here takes precedence over what Claude infers from your code. Use this power wisely.
Advanced context techniques
Link related files. If your authentication logic spans multiple files, note that in CLAUDE.md: "Auth flows through middleware/auth.js, controllers/user.js, and models/User.js." Claude will check all three when working on auth features.
Explain unusual patterns. If you're doing something clever or non-standard, document it. "We use a custom event system instead of callbacks, see utils/events.js for the pattern."
Set boundaries. Tell Claude what not to touch: "Never modify the database schema files directly, use migrations instead" or "The legacy/ directory should not be changed."
Include common commands. Add a section for project specific commands: "Run npm run dev:db to start the local database, npm run test:integration for full tests."
Test your context setup
Run a simple task to see if Claude understands your project better:
claude "explain how user authentication works in this project"
Claude should reference your tech stack, point to the right files, and use the terminology from your CLAUDE.md. If the explanation feels generic or misses important details, update your CLAUDE.md and try again.
Good project context transforms Claude Code from a general coding assistant into something that understands your specific project. The fifteen minutes you spend writing CLAUDE.md saves hours of explaining context in every conversation.