What 6 months and 12 projects taught me about configuring Claude Code
Every time you start a new Claude Code session, Claude has no memory of what happened before. It doesn't know your project structure, your preferences, how you deploy, or the mistakes you've already corrected. CLAUDE.md is how you give Claude persistent memory.
It's a markdown file at the root of your project that Claude reads automatically at the start of every session. Think of it as the operating manual you'd write for a new teammate who joins your project every single day with total amnesia.
Without it, you'll spend the first 5 minutes of every session re-explaining context. With a good one, Claude starts productive from the first prompt.
The key insight: CLAUDE.md isn't documentation for humans. It's instructions for an AI agent that can read, write, and execute code. Write it like you're programming behavior, not explaining architecture.
After iterating across 12 different projects, these are the five sections that consistently produce the best results. You don't need more than this to start.
Tell Claude who it's helping and what authority level it has. Is it a cautious junior dev that asks before acting? A senior engineer that makes architectural decisions? A solo operator that ships without asking?
The role shapes everything. A Claude told "you are the lead engineer" behaves very differently from one told "you are a helpful assistant." Be specific about the relationship.
How to run, build, test, and deploy in 2-3 commands. Claude will try to figure this out on its own if you don't tell it, but it'll waste time reading package.json files, guessing at build tools, and sometimes running the wrong thing entirely.
Save yourself 30 seconds every session. Just tell it: "Dev server: npm run dev. Tests: npm test. Deploy: npx wrangler deploy."
What talks to what. You don't need a novel here. A few lines describing the main components, where they live, and how they connect. Claude uses this to understand where to make changes and what might break.
A simple format works well: Frontend (React) -> API (Express, /src/api/) -> Database (Postgres). If you have external services, list those too. The goal is a mental map, not full documentation.
This is where CLAUDE.md earns its keep. Every project has things Claude should never do. These are rules you discover through painful experience.
Examples: "Never modify the auth middleware without asking first." Or "Never run database migrations automatically." Or "Never change the API response format for existing endpoints."
These are your "never" rules. Every time Claude does something wrong, add a guardrail. Over time, this section becomes your project's immune system.
Project-specific patterns that Claude should follow. Naming conventions, file organization, testing patterns, commit message style, error handling approach.
If you always put API routes in /src/routes/, say so. If you use a specific error handling pattern, show it. If your team uses conventional commits, specify the format. Claude will match your patterns if you tell it what they are.
These are the patterns I see most often when people first write their CLAUDE.md. Each one wastes context window and produces worse results.
Dumping every file path, every function name, and every implementation detail into CLAUDE.md. This wastes thousands of tokens of context on information Claude can discover by reading your code. Your config should tell Claude what it can't figure out on its own.
Only include information that saves time or prevents mistakes. If Claude can learn it by reading a file, let it read the file.
A config with great architecture docs but zero "never do X" rules. Claude will eventually make a destructive mistake. It'll force-push to main, delete a production database, or rewrite a file it shouldn't touch.
Start with the obvious ones: never force push, never delete without asking, never modify environment files. Then add specific ones as you discover what goes wrong in your project.
Claude spends the first two minutes of every session trying to figure out how to run your project. It reads package.json, tries different commands, sometimes installs things you don't want. Three lines of quick-start prevents all of this.
Always include: how to install dependencies, how to run the dev server, and how to deploy. Even if it seems obvious.
Your CLAUDE.md should grow with your project. Don't try to write the perfect config on day one. Here's the natural progression:
The rule of thumb: If you've said it to Claude three times, it belongs in CLAUDE.md. If you've never needed to say it, it doesn't.
Beyond CLAUDE.md, there are two other configuration surfaces worth knowing about.
Custom shortcuts you can invoke with /command-name. They live in your project's .claude/commands/ directory as markdown files. Each file becomes a command.
Use them for repetitive workflows. A /deploy command that runs your deploy pipeline. A /test command that runs the right test suite with the right flags. A /review command that applies your code review checklist.
The filename becomes the command name. The file contents become the prompt Claude executes. Simple as that.
Run the full deploy pipeline: 1. Run tests: npm test 2. Build: npm run build 3. Deploy: npx wrangler deploy 4. Verify the deployment is live Report the result.
Claude Code's configuration file lives at ~/.claude/settings.json. This is where you set global preferences that apply across all projects.
Useful settings include: custom environment variables, permission rules for tools Claude can use without asking, and hooks that run before or after specific actions.
{
"permissions": {
"allow": [
"Bash(npm run dev)",
"Bash(npm test)",
"Bash(npx wrangler deploy)"
]
}
}
This tells Claude it can run those specific commands without asking for permission each time. Start conservative and add permissions as you build trust.
Copy this into a file called CLAUDE.md at the root of your project. Fill in the blanks, delete the comments, and you're set.
# [Project Name] ## Role [Define who Claude is in this project. Examples:] [- "Claude is the senior engineer. Make architectural decisions independently."] [- "Claude is a careful assistant. Always ask before modifying existing files."] [- "Claude is the sole developer. Ship fast, ask forgiveness."] ## Quick Start [How to run the project in 2-3 commands] - Install: [npm install / pip install -r requirements.txt / etc.] - Dev server: [npm run dev / python manage.py runserver / etc.] - Tests: [npm test / pytest / etc.] - Deploy: [npx wrangler deploy / git push main / etc.] ## Architecture [Describe what talks to what. Keep it short.] [Example:] [- Frontend: React app in /src/client/] [- API: Express server in /src/api/] [- Database: Postgres via Prisma ORM] [- Auth: JWT tokens, middleware in /src/middleware/auth.js] [- Hosting: Vercel (frontend) + Railway (API)] ## Guardrails [Rules Claude must follow. Add more as you discover what goes wrong.] - Never force push to main/master - Never delete files without asking first - Never modify environment or secrets files - Never run database migrations automatically [- Never modify the auth middleware without asking] [- Never change API response formats for existing endpoints] [- Always run tests before suggesting a deploy] ## Conventions [Project-specific patterns to follow] [- File naming: kebab-case for files, PascalCase for components] [- Imports: absolute imports from /src/] [- Error handling: always use the AppError class in /src/lib/errors] [- Commits: conventional commits (feat:, fix:, chore:)] [- Tests: colocate test files next to source files]
30 slash commands, 12 thinking frameworks, a full design toolkit, and an install.sh that sets it all up in one shot.
A lightweight macOS dictation app. Talk to your computer, get text. Built for people who think faster than they type.
macOS menu bar app that tracks your Claude Code usage. Know exactly how much context you're burning.
Turn your scattered business workflows into intelligent, queryable APIs. AI-powered data endpoints for every business.