DEV Community

Cover image for How to Write a Good CLAUDE.md File
Asmaa Almadhoun
Asmaa Almadhoun

Posted on

How to Write a Good CLAUDE.md File

#ai #claude #codequality #programming

AI performs less like a genius and more like a new teammate. The quality of its work depends on the clarity of its instructions.

A practical guide to building maintainable AI instructions that improve code quality, reduce token usage, and scale across projects.

Why CLAUDE.md Matters

CLAUDE.md is the first source of project context Claude reads when working in a repository.

A well-written file helps Claude:

  • Understand the project quickly
  • Follow established architecture patterns
  • Avoid repeating mistakes
  • Produce more consistent outputs
  • Use fewer tokens

A poorly written file becomes a giant instruction dump that grows over time, increases token consumption, and makes it harder for Claude to identify what actually matters.

Rule of thumb: Keep always-on instructions small. Load detailed guidance only when needed.

My Recommended Structure

After trying multiple approaches, I found the “Separate permanent project knowledge from topic-specific guidance” guide in Claude and organized it as it should be.

.claude/
├── CLAUDE.md
├── rules/
│   ├── FileArchitecture.md
│   ├── UI-Standards.md
│   ├── Forms.md
│   ├── Testing.md
│   ├── Api-Patterns.md
│   └── Shared-Components.md
└── skills/
    ├── create-feature/
    │   └── SKILL.md
    └── add-pagination/
        └── SKILL.md
Enter fullscreen mode Exit fullscreen mode

What Belongs in CLAUDE.md

The root file should answer only three questions:

1. What is this repository?

Provide a short summary:

This repository contains a React application built using TypeScript and Vite.
Enter fullscreen mode Exit fullscreen mode

2. What must never be forgotten?

Include only critical project invariants.

Examples:

- React and shared dependencies must remain version-aligned.
- Never bypass authorization checks.
- Always use shared components before creating new ones.
Enter fullscreen mode Exit fullscreen mode

3. Where are the detailed rules?

Provide a lightweight rule index.

## Rules

| Rule File | Read When |
|------------|------------|
| rules/ui-standards.md | Editing UI components |
| rules/forms.md | Working on forms |
| rules/testing.md | Writing tests |
| rules/api-patterns.md | Editing services or API integrations |
| rules/architecture.md | Creating new features |
Enter fullscreen mode Exit fullscreen mode

Always-On vs On-Demand Context

The biggest optimization is moving detailed guidance into rule files.

Root CLAUDE.md

Contains:

  • Project overview
  • Critical rules
  • Rule index

Rule Files

Contain:

  • Topic-specific guidance
  • Code examples

Summery

Finally, the best CLAUDE.md files don’t try to teach AI everything. They teach AI where to look.

If you liked my effort, support this content by pressing Like. It motivates me to share more!

Top comments (0)