Writing Effective CLAUDE.md Files
CLAUDE.md is the single most impactful thing you can add to a project. Learn the anatomy of a great one, see real examples, and avoid common mistakes.
What CLAUDE.md is and why every project needs one
CLAUDE.md is a markdown file that tells Claude Code how to work with your project. It is the single most impactful thing you can do to improve Claude Code's output quality. Without a CLAUDE.md, Claude Code makes assumptions about your project — your coding style, your conventions, your preferences. Sometimes those assumptions are right. Often they are not. A CLAUDE.md eliminates guesswork. It tells Claude Code: here is our tech stack, here are our coding standards, here is how we name files, here is how we handle errors, here are things you should never do. Think of it as onboarding documentation for an AI team member. Just as you would not expect a new developer to write good code without understanding your conventions, you should not expect Claude Code to match your standards without explicit guidance. The difference is dramatic. Projects with a well-written CLAUDE.md get consistently better output — fewer style corrections, fewer wrong assumptions, fewer "that is not how we do it" moments. It takes 15 minutes to write and saves hours every week.
The anatomy of a great CLAUDE.md
A great CLAUDE.md has five sections. First, Project Overview: two to three sentences explaining what the project is, who it is for, and what it does. This gives Claude Code the big picture. Second, Tech Stack: list every major technology — framework, language, database, hosting, key libraries. Be specific: "Next.js 14 App Router with TypeScript" not just "React." Third, Coding Standards: your rules for writing code. Indentation (tabs or spaces), naming conventions (camelCase, kebab-case), import ordering, error handling patterns, component structure. Be prescriptive. Fourth, File Structure: explain your directory layout and where different types of code live. "API routes go in src/app/api/, shared types in src/lib/types.ts, React components in src/components/." Fifth, Rules and Constraints: things Claude Code must always or never do. "Always use server components unless client interactivity is required." "Never use inline styles." "Always add JSDoc comments to exported functions." These rules are the guardrails that keep Claude Code's output consistent with your team's expectations.
Where to put it
CLAUDE.md files work at three levels. Project-level (most common): place CLAUDE.md in your project's root directory, next to package.json or pyproject.toml. Claude Code automatically reads this when you start a conversation in that directory. This is where your project overview, tech stack, and coding standards live. Directory-level: you can place additional CLAUDE.md files in subdirectories for area-specific instructions. For example, a CLAUDE.md in src/components/ might say: "All components in this directory are server components. Use Tailwind for styling. Export a single default component per file." A CLAUDE.md in src/api/ might say: "All routes return JSON. Use Zod for validation. Always return proper HTTP status codes." Claude Code merges directory-level instructions with the project-level file. User-level: a CLAUDE.md in your home directory (~/.claude/CLAUDE.md) applies to all projects. Use this for personal preferences that span projects — your preferred comment style, your terminal preferences, or global rules like "always explain changes before making them." The hierarchy is: user-level, then project-level, then directory-level. More specific instructions override general ones.
Real examples
Here is a condensed CLAUDE.md for a Next.js project: "## Project: Enigmatica\nAI education platform built with Next.js 14 App Router, TypeScript, Tailwind CSS. Hosted on Vercel.\n\n## Standards\n- Server components by default, 'use client' only when needed\n- Tailwind for all styling, no inline styles\n- All data in src/lib/data.ts (migrating to CMS later)\n- Mobile-first responsive design\n\n## Rules\n- NEVER create documentation files unless asked\n- ALWAYS use TypeScript, no 'any' types\n- Use semantic HTML with ARIA labels." For a Python API: "## Project: Invoice Processor\nFastAPI backend processing invoices via OCR and LLM extraction.\n\n## Stack: Python 3.12, FastAPI, SQLAlchemy, Pydantic v2, PostgreSQL\n\n## Rules\n- Type hints on all functions\n- Pydantic models for all request/response schemas\n- Alembic for migrations, never raw SQL DDL." For a marketing team (non-developers): "## Project: Marketing Content Repo\nMarkdown files for blog posts, email campaigns, and landing pages.\n\n## Rules\n- All files in content/ directory\n- File names: YYYY-MM-DD-title-slug.md\n- Front matter must include: title, date, author, category." Notice how each example is specific, prescriptive, and concise.
Common mistakes
The most common CLAUDE.md mistake is being too vague. "Write clean code" means nothing — Claude Code already tries to write clean code. Instead say: "Functions should be under 30 lines. Extract shared logic into utils/. Name boolean variables with is/has/should prefix." The second mistake is being too long. If your CLAUDE.md is 2,000 words, Claude Code will lose important details in the noise. Aim for 200-500 words. Be concise and prescriptive. Every sentence should be an actionable instruction or essential context. The third mistake is contradictory rules. "Use functional components" in one section and "use class components for complex state" in another. Claude Code follows instructions literally — contradictions confuse it. The fourth mistake is including information Claude Code can infer. Do not list every file in your project — Claude Code can read your directory. Do not explain what React is — Claude Code knows. Focus on what is unique to your project. The fifth mistake is never updating it. Your CLAUDE.md should evolve with your project. When you find yourself correcting Claude Code repeatedly about the same thing, add it to your CLAUDE.md. It is a living document, not a one-time setup.
Using the CLAUDE.md Generator tool
If starting from scratch feels daunting, Enigmatica has a free CLAUDE.md Generator tool at /tools/claude-md-generator. It walks you through a guided form: enter your project name, tech stack, coding standards, and rules, and it generates a well-structured CLAUDE.md file that you can copy into your project. The generator covers all five sections (overview, tech stack, standards, file structure, rules) and formats them using proven patterns from hundreds of production projects. It is especially useful for teams adopting Claude Code for the first time — instead of each developer writing their own CLAUDE.md, generate a team standard and iterate on it together. After generating your initial file, customise it. Add project-specific rules that the generator cannot know. Remove sections that do not apply. The generator gives you a strong starting point — your team's experience turns it into a great CLAUDE.md. One tip: run /init in Claude Code inside your project directory. It will analyse your codebase and suggest a CLAUDE.md based on what it finds. Compare this with the generator output and merge the best of both. Between the generator, /init, and the examples in this guide, you have everything you need to write a CLAUDE.md that transforms your Claude Code experience.
CLAUDE.md and System Prompts
This guide is hands-on and practical. The full curriculum covers the conceptual foundations in depth with structured lessons and quizzes.
Go to lesson