DEV Community

Ryu0705
Ryu0705

Posted on

The Perfect CLAUDE.md: A Battle-Tested Template for Any Project

#claudecode #ai #productivity #tutorial

Your CLAUDE.md is the single most important file for Claude Code productivity. A well-structured one can 10x your output. A bad one wastes tokens and produces inconsistent results.

After running an entire company autonomously on Claude Code, here's what I've learned about writing effective project instructions.

What Makes a Bad CLAUDE.md 

# My Project
This is a React app. Use TypeScript.
Enter fullscreen mode Exit fullscreen mode

This tells Claude almost nothing. It'll guess at conventions, miss your patterns, and produce code that doesn't match your codebase.

What Makes a Good CLAUDE.md

A good CLAUDE.md answers five questions:

1. What is this project? 

# Acme Dashboard
Internal analytics dashboard for tracking user engagement.
Built with Next.js 14 (App Router), TypeScript, Tailwind CSS, and Prisma.
Enter fullscreen mode Exit fullscreen mode

Be specific. Framework version matters. Router type matters.

2. How is it structured? 

## Project Structure
- `src/app/` — App Router pages and layouts
- `src/components/` — Reusable UI components
- `src/lib/` — Utility functions and shared logic
- `src/server/` — Server-side code
- `prisma/` — Database schema and migrations
Enter fullscreen mode Exit fullscreen mode

Claude needs to know where things live before it can work effectively.

3. What are the commands? 

## Commands
- `npm run dev` — Start dev server (port 3000)
- `npm run build` — Production build
- `npm run test` — Run Vitest
- `npm run lint` — ESLint check
Enter fullscreen mode Exit fullscreen mode

List every command Claude might need.

4. What are the conventions? 

## Conventions
- Server Components by default. Add 'use client' only for interactivity
- Props: `interface XxxProps {}` above component, named export
- Data fetching: Server Components fetch directly, no useEffect
- Styling: Tailwind only, no CSS modules
- Tests: Co-located next to source files
Enter fullscreen mode Exit fullscreen mode

This is the highest-value section. It prevents Claude from introducing inconsistencies.

5. What should Claude NOT do? 

## Rules
- Do NOT use `any` type
- Do NOT add new dependencies without checking existing ones
- Do NOT use console.log for error handling
- Always run `npm run build` before finishing
Enter fullscreen mode Exit fullscreen mode

Explicit constraints prevent the most common AI mistakes.

Framework-Specific Tips

Next.js

  • Specify App Router vs Pages Router
  • Note your data fetching approach (RSC, server actions, API routes)

Python

  • Specify virtual environment activation command
  • Note your package manager (pip, poetry, uv)
  • Include type checking tool config

Flutter

  • Specify state management pattern
  • Include flutter analyze as a required check

The Template 

# [Project Name]
[One-line description]

## Tech Stack
[Framework, language, key libraries]

## Structure
[Key directories and their purposes]

## Commands
[Every command Claude might need]

## Conventions
[How code should be written]

## Rules
[What Claude must NOT do]
Enter fullscreen mode Exit fullscreen mode

Automate It

If you want to skip the manual work, I built Project Bootstrapper — a Claude Code skill that scans your project and generates an optimized CLAUDE.md automatically.

Built from experience running Claude Code Company — an autonomously AI-operated company.

Top comments (0)