How to Write a CLAUDE.md File to Optimize AI Output

by

How to Write a CLAUDE.md File to Optimize AI Output

The single highest-leverage thing you can do to improve Claude Code’s output is write a good CLAUDE.md file. It is the difference between an agent that guesses at your conventions and one that follows them. This guide explains what the file is, why it matters, how to structure it, and includes practical examples you can adapt for real projects.

[IMAGE: Example of a CLAUDE.md file structure with project rules]

What is the CLAUDE.md File?

A CLAUDE.md file is a plain Markdown document you place in your project that gives Claude Code standing instructions about how to work in that codebase. Think of it as an onboarding document you would hand a new teammate — except the agent actually reads it every time it works in your project.

It lives at the root of your repository (and optionally inside subdirectories for more specific rules). Because it is just Markdown, there is nothing to install or maintain beyond editing text.

Why You Need a Custom Instruction File

Without explicit instructions, the agent infers your intentions from the code it happens to see — and it often guesses wrong. A CLAUDE.md file:

  • Encodes your conventions so generated code matches your existing style.
  • Reduces rework by preventing the agent from introducing patterns you would reject.
  • Provides context about architecture and important files the agent might otherwise miss.
  • Sets guardrails around files, dependencies, and actions you want handled carefully.

If the agent frequently overlooks files, a strong instructions file also helps it prioritize the right code. When that fails, our guide to resolve hidden file issues covers the deeper causes.

How to Structure Your CLAUDE.md

A useful file is organized and specific. Aim for clear sections the agent can parse.

Defining Project Rules and Standards

Start with the non-negotiables:

  • Project overview — one or two sentences on what the project does.
  • Coding standards — formatting, naming conventions, and preferred patterns.
  • Testing expectations — which framework to use and when to write tests.
  • Do-not-touch list — files, directories, or dependencies that require caution.

Adding Tech Stack Specifics

Next, describe the technical environment so the agent generates compatible code:

  • Languages and versions.
  • Frameworks and major libraries.
  • Build, test, and lint commands.
  • Any project-specific tooling the agent should use.

A concise skeleton looks like this:

# Project: Acme Dashboard

## Overview
A web dashboard for visualizing sales metrics.

## Tech Stack
- TypeScript
- React with Vite
- Vitest for testing

## Conventions
- Use functional components and hooks
- Prefer async/await over promise chains
- Keep components under 200 lines

## Commands
- Build: `npm run build`
- Test: `npm run test`

## Do Not
- Modify files in `/generated`
- Add new dependencies without asking

CLAUDE.md Best Practices Examples

Tailor the file to your stack. Two common cases:

Example for Frontend React Projects

# Project: Marketing Site

## Tech Stack
- React + TypeScript
- Tailwind CSS
- Vitest + Testing Library

## Conventions
- Functional components only
- Co-locate component styles and tests
- Use semantic HTML for accessibility

## Commands
- Dev: `npm run dev`
- Lint: `npm run lint`

[IMAGE: CLAUDE.md best practices examples for a React frontend project]

Example for Python Backend Projects

# Project: Orders API

## Tech Stack
- Python 3.12
- FastAPI
- pytest

## Conventions
- Type hints on all public functions
- Use Pydantic models for request/response schemas
- Follow PEP 8 formatting

## Commands
- Run: `uvicorn app.main:app --reload`
- Test: `pytest`

For larger repositories, you can layer these files. Learn how to structure advanced monorepo rules with a root file plus package-specific overrides.

Common Mistakes to Avoid

Even a well-intentioned file can underperform. Watch for these:

  • Being vague. “Write clean code” tells the agent nothing. “Keep functions under 40 lines” does.
  • Overloading it. A giant file consumes context budget and buries the important rules. Keep it focused.
  • Letting it go stale. Update the file as your conventions evolve, or the agent will follow outdated rules.
  • Skipping commands. If you do not list build and test commands, the agent may run the wrong ones.
  • Forgetting guardrails. Always state what the agent should not touch.

Once your instructions are dialed in, you can explore other power user techniques to get even more from the agent. A sharp CLAUDE.md is the foundation everything else builds on — invest a few minutes and every future session gets better.

Frequently Asked Questions

Where should the CLAUDE.md file go?

Place it at the root of your repository so it applies project-wide. You can add additional CLAUDE.md files inside subdirectories for more specific rules.

How long should a CLAUDE.md file be?

Keep it focused. A concise file covering your stack, conventions, commands, and guardrails works better than a long document that buries important rules and consumes context.

What should I include in a CLAUDE.md file?

A project overview, tech stack, coding conventions, build and test commands, and a list of files or actions the agent should avoid.

Does CLAUDE.md work for any programming language?

Yes. It is plain Markdown, so it works for any stack. Simply describe the languages, frameworks, and conventions relevant to your project.

Why is my CLAUDE.md being ignored?

Vague instructions are easy to overlook, and an overly long file can push key rules out of context. Make rules specific, keep the file focused, and confirm it sits where the agent can read it.

Leave a Comment