CLAUDE.md is a file you place at the root of your project. When Claude Code opens your project, it reads this file first. Every instruction in it shapes how Claude Code behaves in your codebase. Think of it as the rules of engagement between you and the AI.
Most developers either skip CLAUDE.md entirely or fill it with vague instructions that do not actually change behavior. This guide shows you what to put in it, organized by what actually matters.
Start with what the project is
The first section tells Claude Code what it is working on. Not a marketing description. A technical summary that gives the AI enough context to make good decisions.
Bad example: "This is an innovative platform for connecting people." Claude Code learns nothing useful from this.
Good example: "Multi-tenant SaaS application for property management. Next.js 14 App Router, tRPC v11, Prisma with PostgreSQL. Three user roles: landlord, tenant, maintenance. Tenants submit maintenance requests. Landlords approve and assign. Maintenance staff update status and upload completion photos."
In three sentences, Claude Code now knows the framework, the API pattern, the database layer, the user roles, and the core workflow. When you ask it to add a feature, it makes decisions that align with this architecture instead of guessing.
Define the tech stack explicitly
List every major dependency and the version that matters. Claude Code uses this to write code that matches your actual stack, not the latest version it knows about.
Include: the framework and version, the database and ORM, the authentication library, the CSS approach, the testing framework, and any unusual dependencies. If you use a specific state management library or a specific component library, list them.
Why this matters: if your project uses NextAuth v5 (beta) and you do not specify that, Claude Code might write NextAuth v4 patterns. If you use Prisma 5 and do not say so, it might use syntax that changed between versions. These mismatches cost time and create bugs.
Establish the directory structure
Tell Claude Code where things live. Not every file — the organizational pattern.
"API routes live in src/app/api/. tRPC routers live in src/server/routers/ and are registered in src/server/routers/_app.ts. React components live in src/components/ organized by feature. Utility functions live in src/lib/. Database schema is in prisma/schema.prisma."
When Claude Code knows the structure, it puts new files in the right place. Without this, it makes reasonable guesses that might not match your project's conventions.
Set coding standards that matter
Do not list every style preference. Focus on the decisions that affect correctness and consistency.
Database patterns: "Always use upsert with unique constraints for seed data. All database operations are async. Never use raw SQL when Prisma provides the operation." These rules prevent real bugs.
Error handling: "API routes return structured error responses with status codes. Never expose internal error messages to clients. Log errors server-side with context." These rules prevent security issues and improve debugging.
Naming conventions: only if yours differ from the obvious. If you use camelCase for variables and PascalCase for components, Claude Code already assumes that. If you use a specific prefix for API routes or a specific suffix for hook files, say so.
What to leave out: do not tell Claude Code to use semicolons or spaces instead of tabs. Your linter handles that. Do not tell it to write clean code or follow best practices. Those instructions are too vague to change behavior.
Define data handling rules
This is where CLAUDE.md becomes a governance document. If your project handles sensitive data, define what the AI can and cannot do with it.
"PII fields (email, phone, name) must never appear in console.log statements, error messages, or client-side state that is visible in browser dev tools. Payment data (card numbers, bank accounts) must never be stored outside the payment processor's tokenized response. Session tokens must be httpOnly cookies with secure flag in production."
These rules prevent the most common data handling mistakes. Claude Code reads them and avoids writing code that logs PII or stores payment data in places it should not be.
For regulated industries, add the specific regulations that apply: "This application processes healthcare data subject to HIPAA. PHI must never be transmitted without encryption. Audit logs must capture every access to patient records including the user ID, timestamp, and the record accessed."
Specify what NOT to do
Negative instructions are surprisingly effective. Tell Claude Code what you do not want.
"Do not add comments that restate what the code does. Do not add error handling for scenarios that cannot occur based on the type system. Do not create abstraction layers for one-time operations. Do not add features beyond what was requested."
These instructions prevent the over-engineering that AI tools tend toward. Claude Code, left to its own defaults, will add helpful comments, defensive error handling, and utility functions for things that do not need them. Explicit instructions to stop doing that produce cleaner code.
"Do not modify the authentication system without explicit instruction. Do not change the database schema without explicit instruction. Do not install new dependencies without explicit instruction." These rules create guardrails around high-impact changes that should require deliberate decisions.
Include deployment context
Claude Code makes better decisions when it knows how the code gets deployed.
"Deployed on Railway via Dockerfile. The CMD runs prisma db push before starting the server. Environment variables are set in Railway, not in code. The production database is PostgreSQL on Railway's internal network. Static assets are served by Next.js standalone output."
This prevents Claude Code from writing deployment scripts for Vercel when you deploy on Railway, or from hardcoding values that should be environment variables.
Update it when things change
CLAUDE.md is not a write-once document. When you add a new major feature, add a section describing it. When you change your deployment target, update that section. When you establish a new pattern (a new router type, a new component pattern), document it.
The file should reflect the current state of the project. Outdated instructions are worse than no instructions because they actively mislead Claude Code into writing code that does not match your current architecture.
A real example
Here is a condensed CLAUDE.md for a property management application:
Project: Multi-tenant SaaS for property management. Next.js 14 (App Router), tRPC v11, Prisma 5, PostgreSQL, NextAuth v5 with JWT strategy. Three roles: LANDLORD, TENANT, MAINTENANCE.
Structure: API routes in src/app/api/, tRPC routers in src/server/routers/, components in src/components/ by feature, utilities in src/lib/, schema in prisma/schema.prisma.
Database: Upserts for seeds. All queries must include tenantId filter for multi-tenant isolation. Never query across tenants without explicit admin authorization.
Auth: protectedProcedure for logged-in users, landlordProcedure for property owners, adminProcedure for platform admins. Every route that returns tenant data must verify the requesting user belongs to that tenant.
Data: No PII in logs. Maintenance photos stored in S3 with signed URLs (never public URLs). Tenant contact information only visible to their landlord and maintenance staff assigned to their property.
Do not: Add dependencies without asking. Modify auth without asking. Skip tenant isolation on any database query. Create admin backdoors or debug endpoints.
Deploy: Railway, Dockerfile, standalone output, port 8080. Prisma db push runs on startup.
That is roughly 200 words. It takes 5 minutes to write. It prevents hours of correction and dozens of bugs over the life of the project.
Take the full Claude Code course to master project configuration
Get posts like this in your inbox
No spam. New articles on AI strategy, governance, and building with AI for small business.