How to write a CLAUDE.md that gets results

Why Your CLAUDE.md File Is Make-or-Break for AI Coding

You’ve probably experienced this: Claude Code starts strong on your project, then gradually drifts. It begins using patterns you don’t like, imports files in ways that break your architecture, or writes code that technically works but feels foreign in your codebase.

The problem isn’t Claude Code itself. It’s that you haven’t given it your project’s constitution.

CLAUDE.md is the configuration file that transforms Claude Code from a well-meaning assistant making educated guesses into a spec-driven teammate that follows your exact rules. Think of it as your project’s DNA — the fundamental instructions that govern how AI interacts with your codebase.

Without CLAUDE.md, Claude Code operates in default mode: making assumptions about your architecture, coding style, and deployment process. Those assumptions are often wrong. With CLAUDE.md, Claude Code becomes an extension of your development process, consistently applying your patterns and conventions across every file it touches.

The Architecture of Effective CLAUDE.md Files

A well-structured CLAUDE.md file contains five essential sections, each serving a specific function in guiding Claude Code’s behavior.

Project Overview: The 30,000-Foot View

Start with a concise project description. One paragraph that explains what your application does, followed by your core technology decisions.

Here’s how creator Sarah Chen structures hers for a SaaS analytics dashboard:

“This is a real-time analytics dashboard for e-commerce businesses. Users connect their Shopify stores and see conversion funnels, customer lifetime value, and revenue predictions. Built with React + TypeScript + Supabase + Tailwind CSS. Feature-based folder structure where each business domain (auth, analytics, billing) has its own directory with components, hooks, and utilities.”

This setup immediately tells Claude Code three critical things: the business context (analytics for e-commerce), the technical foundation (React/TS stack), and the organizational philosophy (feature-based folders). Every subsequent code generation will align with these constraints.

Coding Conventions: Your Non-Negotiables

This section defines your code style with surgical precision. Generic style guides don’t work here — you need rules specific to your project’s needs.

For a Next.js creator building a content management system, effective conventions might include:

“Use functional components with hooks exclusively. No class components. All API calls route through /lib/api/ directory using custom hooks that return { data, error, loading }. Implement Zod schemas for all API responses and form inputs. Error handling requires try/catch blocks — never let errors fail silently. Database queries use Prisma with explicit select statements to avoid over-fetching.”

Notice the specificity. Instead of “use good error handling,” the rule specifies try/catch blocks and prohibits silent failures. Instead of “validate inputs,” it mandates Zod for both API responses and forms.

Forbidden Patterns: Drawing Hard Lines

This section prevents Claude Code from generating code you’ll need to refactor later. List patterns that are technically valid but violate your architectural decisions.

Common forbidden patterns for TypeScript projects:

“Never use ‘any’ type annotations. Always specify explicit types or use proper generic constraints. Never use inline styles — all styling through Tailwind classes with custom component variants. Never import from parent directories using ../.. notation — use absolute imports with @ aliases. Never mutate props directly — treat all props as immutable.”

The power of forbidden patterns lies in prevention. Without these rules, Claude Code might generate working code that introduces technical debt or breaks your architectural patterns.

Testing Requirements: Quality Gates

Define your testing philosophy and specific requirements for different types of code changes.

“Every new utility function requires a corresponding test file. API routes need integration tests that cover success and error scenarios. React components need tests for core user interactions. Run ‘npm test’ before every commit — no exceptions. Use Testing Library for component tests, focusing on user behavior rather than implementation details.”

This section ensures Claude Code generates testable code and includes test files when creating new functionality.

Deployment and Development Workflow

Document your development and deployment processes so Claude Code can generate code that fits your workflow.

“Development workflow: always test locally with ‘npm run dev’ and verify functionality before pushing. Deployment through Vercel — pushing to main branch triggers automatic production deployment. Feature branches deploy to preview URLs for testing. Environment variables stored in .env.local for development, Vercel dashboard for production.”

A Complete CLAUDE.md Template You Can Use Today

Here’s a starter template that works for most React-based projects. Copy this and customize it for your specific stack and preferences:

# Project Overview
[One paragraph describing what your app does and who uses it]

Tech Stack

– Frontend: React 18 + TypeScript + Tailwind CSS
– Backend: [Your backend choice]
– Database: [Your database]
– Deployment: [Your deployment platform]

Architecture

Feature-based folder structure. Each feature contains its own components, hooks, types, and utilities.

# Coding Conventions

React Components

– Use functional components with hooks only
– Props interfaces named [ComponentName]Props
– Export components as default, interfaces as named exports

API Integration

– All API calls through custom hooks in /hooks/api/
– Return { data, error, loading } pattern
– Use Zod for response validation

Styling

– Tailwind CSS classes only
– No inline styles
– Component variants using class-variance-authority

Error Handling

– Always use try/catch for async operations
– Log errors to console in development
– Show user-friendly messages in UI

# Forbidden Patterns
– Never use ‘any’ type — always specify explicit types
– Never use relative imports with ../ — use absolute imports
– Never mutate state directly — use immutable patterns
– Never skip error handling in async functions

# Testing
– New functions need unit tests
– Components need interaction tests
– API calls need integration tests
– Run tests before committing

# Deployment
– Test locally first with npm run dev
– Push to main for production deployment
– Feature branches create preview deployments

The Iteration Strategy: Building Your Perfect CLAUDE.md

Don’t try to write the perfect CLAUDE.md file on day one. Start minimal and evolve it based on real usage patterns.

Week One: Basic Structure

Begin with 15-20 lines covering your tech stack, folder structure, and 2-3 coding conventions you care most about. Indie game developer Marcus Rivera started his CLAUDE.md with just his Unity version, C# style preferences, and folder organization rules.

Week Two: Pattern Recognition

Pay attention to corrections you make to Claude Code’s output. If you find yourself fixing the same type of mistake twice, add a rule to prevent it. Marcus noticed Claude Code was generating MonoBehaviours when he preferred ScriptableObjects for game data, so he added that preference to his forbidden patterns.

Month One: Refinement

By this point, you’ll have 30-50 lines of highly specific rules that reflect your actual development patterns. The file becomes a living document that captures your project’s accumulated wisdom.

Content creator Jessica Wu maintains CLAUDE.md files for her three main projects — a newsletter platform, a course hosting site, and a client project management tool. Each file evolved differently based on the unique challenges of that codebase.

Common Mistakes That Kill CLAUDE.md Effectiveness

The most common mistake is writing generic rules that could apply to any project. “Use good naming conventions” tells Claude Code nothing useful. “Use camelCase for variables, PascalCase for components, and kebab-case for CSS classes” provides actionable guidance.

Another frequent error is over-specifying implementation details while under-specifying architectural principles. You don’t need to document every function signature, but you absolutely need to clarify how different parts of your application should interact.

Many creators also forget to update their CLAUDE.md as their projects evolve. Your authentication system might start simple but grow complex enough to warrant its own architectural rules. Update your CLAUDE.md to reflect these changes, or Claude Code will generate code that fights your current architecture.

Advanced CLAUDE.md Techniques for Complex Projects

Feature-Specific Rules

For larger projects, consider adding sections for specific features or modules. E-commerce developer Tom Chen includes special rules for his payment processing module:

“Payment Module Rules: All payment-related functions must include comprehensive logging. Never store credit card details locally — always use tokens. Payment failures require both user notification and admin alert. Refund logic needs manager approval workflow.”

Performance Guidelines

If performance is critical for your application, document your optimization preferences:

“Performance Requirements: Images must use Next.js Image component with appropriate sizing. Database queries need indexes documented in comments. React components with expensive calculations require useMemo. API responses over 1MB need pagination.”

Security Protocols

For applications handling sensitive data, include security-specific rules:

“Security Requirements: All user inputs require sanitization before database queries. Authentication checks on every API route. Sensitive data encrypted at rest. No secrets in client-side code — use environment variables.”

Measuring CLAUDE.md Success

You’ll know your CLAUDE.md file is working when you spend less time refactoring Claude Code’s output and more time building features. The generated code should feel native to your codebase from the first draft.

Track these metrics over a few weeks: How often do you need to rewrite Claude Code’s suggestions? How consistently does it follow your architectural patterns? How much time do you spend fixing style or convention issues?

A well-tuned CLAUDE.md should reduce correction time by 60-80% while maintaining code quality that matches your hand-written code.

Integration with Your Development Workflow

CLAUDE.md works best when integrated with your existing development practices. If you use code review processes, include your CLAUDE.md standards in review checklists. If you have documentation standards, treat CLAUDE.md as a living specification document that team members can reference.

For solo creators, consider your CLAUDE.md as documentation for your future self. Six months from now, when you return to a project, CLAUDE.md serves as a quick refresher on your architectural decisions and coding preferences.

Beyond the Basics: CLAUDE.md for Different Project Types

Different types of creative projects benefit from different CLAUDE.md approaches. A content creator building a blog needs different rules than a developer building a SaaS application.

For content-heavy projects, emphasize SEO requirements, content structure conventions, and performance optimization for media files. For data-intensive applications, focus on database interaction patterns, caching strategies, and data validation rules.

The key is matching your CLAUDE.md content to your project’s primary challenges and success criteria.

Frequently Asked Questions

How often should I update my CLAUDE.md file?

Update your CLAUDE.md whenever you find yourself correcting the same type of mistake from Claude Code multiple times. A good rule of thumb: if you fix the same pattern twice, add a rule to prevent it. Most active projects benefit from weekly reviews during heavy development phases.

Can CLAUDE.md be too detailed or restrictive?

Yes, over-specification can make your CLAUDE.md counterproductive. Focus on architectural decisions, coding conventions that matter to your project’s success, and patterns you’ve had problems with. Avoid documenting every possible scenario — aim for 80% coverage of common situations.

Should I have different CLAUDE.md files for different projects?

Absolutely. Each project should have its own CLAUDE.md that reflects its specific technology stack, business requirements, and architectural patterns. While some conventions might be similar across projects, the specific rules should match each project’s unique needs.

What’s the minimum viable CLAUDE.md for a new project?

Start with three sections: tech stack (5 lines), basic coding conventions (5-10 lines), and forbidden patterns (3-5 lines). This gives Claude Code enough context to generate appropriate code while leaving room for iteration as your project requirements become clearer.

How do I know if my CLAUDE.md rules are working effectively?

Monitor how much time you spend refactoring Claude Code’s output. Effective CLAUDE.md files reduce correction time by 60-80%. Also watch for consistency — if Claude Code generates code that feels native to your existing codebase without major modifications, your rules are working well.