Writing Effective CLAUDE.md Files

Module: Configuration | Lesson: 2 of 5 | Time: ~10 minutes

What You Will Learn

• How to structure a CLAUDE.md file for maximum impact
• What makes instructions specific enough for Claude to follow
• How to use multiple CLAUDE.md files and the .claude/rules/ directory
• Patterns used by experienced Claude Code users

Prerequisites

• Completed What Is CLAUDE.md?

Main Content

Keep It Short and Focused

The single most important rule for CLAUDE.md: keep it under 200 lines. Claude pays more attention to shorter, focused files. A 50-line file with clear instructions will outperform a 500-line file that tries to cover everything.

Length Matters

If your CLAUDE.md grows beyond 200 lines, Claude may start to skim or miss details -- just like a person would with an overly long briefing. When your file gets too long, split it into multiple files (covered below).

Recommended Structure

Here is a battle-tested structure that works well for most projects:

# Project Name

## Overview
One or two sentences about what this project does and who it is for.

## Tech Stack
- Language: TypeScript
- Framework: Next.js 14
- Database: PostgreSQL
- Package manager: npm
- OS: Windows 11

## Key Commands
- Install dependencies: `npm install`
- Run dev server: `npm run dev`
- Run tests: `npm test`
- Build for production: `npm run build`

## Code Conventions
- Use TypeScript strict mode
- Components go in src/components/
- Use camelCase for variables, PascalCase for components
- Always add JSDoc comments to exported functions
- Use PowerShell commands (not bash) when generating scripts

## Common Pitfalls
- Do NOT use `rm` -- use `Remove-Item` (we are on Windows)
- The database connection string is in .env (never commit this file)
- Tests must pass before any code is considered complete

Let us walk through why each section matters.

Section 1: Overview

Keep this to one or two sentences. Claude uses it to understand the big picture so it can make appropriate decisions.

Bad: "This is a project." Good: "A REST API for a pet adoption platform. Shelters post available animals; adopters browse and apply."

Section 2: Tech Stack

List every major technology. Be explicit about versions when they matter. Always mention that you are on Windows -- this prevents Claude from suggesting Mac or Linux commands.

Bad: "Uses JavaScript and a database." Good: "JavaScript (ES2022), Express.js 4.18, SQLite via better-sqlite3, Windows 11."

Section 3: Key Commands

This is one of the most valuable sections. When Claude knows how to build and test your project, it can verify its own work by running these commands after making changes.

Let Claude Check Its Work

Including test and build commands means Claude can run them after making edits. This catches errors immediately instead of leaving them for you to discover later.

Section 4: Code Conventions

Be as specific as possible. Vague instructions produce vague results.

Vague (Avoid)	Specific (Use)
"Use appropriate commands"	"Use PowerShell commands, not bash"
"Follow naming conventions"	"Use camelCase for functions, PascalCase for classes"
"Keep code clean"	"Maximum 80 characters per line, no unused imports"
"Handle errors properly"	"Wrap async calls in try/catch, log errors to console.error"

Section 5: Common Pitfalls

Think about what a new developer would get wrong on their first day. These warnings save Claude from making the same mistakes.

Examples:

• "The /api/auth route is legacy -- do not modify it"
• "Always use forward slashes in import paths, even on Windows"
• "The config file is auto-generated -- do not edit config.generated.js"

Using Multiple CLAUDE.md Files

As your project grows, a single CLAUDE.md may not be enough. You can place CLAUDE.md files in subdirectories to give Claude context-specific instructions.

my-project/
  CLAUDE.md              <-- General project instructions
  frontend/
    CLAUDE.md            <-- Frontend-specific instructions
  backend/
    CLAUDE.md            <-- Backend-specific instructions
  tests/
    CLAUDE.md            <-- Testing conventions

When you are working in the frontend/ directory, Claude reads both the root CLAUDE.md and the frontend/CLAUDE.md. The subdirectory file can add or override instructions from the parent.

The .claude/rules/ Directory

For more granular control, you can create rule files in .claude/rules/ that apply to specific file patterns:

my-project/
  .claude/
    rules/
      frontend.md       <-- Rules for frontend code
      testing.md         <-- Rules for test files
      api.md             <-- Rules for API endpoints

Each file in .claude/rules/ contains instructions that Claude follows when working with matching areas of your project. This is a cleaner approach than having many CLAUDE.md files scattered across directories.

When to Use Rules vs Multiple CLAUDE.md Files

Use multiple CLAUDE.md files when different parts of your project are truly separate (like a frontend and backend in different frameworks). Use .claude/rules/ when you want to add focused rules for specific types of work within the same project.

Real-World Example: Before and After

Before (too vague, too long):

# My App
This is a web application. It uses React. Please write good code.
Make sure to test things. Use good variable names.
The app has a frontend and backend. Follow best practices.
... (300 more lines of generic advice)

After (specific, actionable, concise):

# TaskTracker

## Overview
A task management app. Users create, assign, and track tasks across teams.

## Tech Stack
- React 18 + TypeScript, Vite bundler
- Express.js backend, PostgreSQL database
- Windows 11 development, PowerShell terminal

## Commands
- Dev server: `npm run dev` (starts both frontend and backend)
- Tests: `npm test` (runs Jest + React Testing Library)
- Lint: `npm run lint`
- Always run `npm test` after making changes

## Conventions
- Components: PascalCase, one component per file in src/components/
- API routes: kebab-case (e.g., /api/task-list)
- State management: React Context only (no Redux)
- Error handling: try/catch with user-facing error messages

## Pitfalls
- The database migration must run before tests: `npm run db:migrate`
- Never modify src/generated/ -- these files are auto-generated
- Use `Remove-Item` not `rm` (Windows PowerShell)

Try It Yourself

Go back to the CLAUDE.md you created in the previous lesson and improve it.

1. Open your CLAUDE.md in a text editor:

   notepad C:\Users\YourName\claude-practice\CLAUDE.md

2. Add at least three of these sections:

   • A one-sentence project overview
   • Your operating system and terminal (Windows, PowerShell)
   • At least two specific conventions (naming, style, etc.)
   • One common pitfall or warning
   • A command Claude can run to verify things work

3. Save the file and start a new Claude Code session:

   cd C:\Users\YourName\claude-practice
   claude

4. Test your instructions by asking Claude to do something that should follow your conventions. For example, if you said "use camelCase," ask Claude to create a variable and check whether it follows the rule.

Iterate Over Time

Your CLAUDE.md does not need to be perfect on the first try. Start with the basics and add instructions as you discover things Claude gets wrong. Every time Claude makes a mistake that a CLAUDE.md instruction could prevent, add that instruction.

What You Learned

• Keep CLAUDE.md under 200 lines -- shorter files get better attention from Claude
• Structure it with clear sections: overview, tech stack, commands, conventions, pitfalls
• Be specific, not vague -- "use camelCase for functions" beats "use good naming"
• Include build and test commands so Claude can verify its own work
• Use multiple CLAUDE.md files for large projects with distinct areas
• Use .claude/rules/ for path-specific rules within a project

---

Help Us Improve

How was this lesson? Take 2 minutes to share your feedback — it helps us make the tutorials better for everyone.

Give Feedback →

Next Up

Next: Settings.json