Writing a CLAUDE.md

What Is CLAUDE.md?

CLAUDE.md is a configuration file that helps Claude Code understand your project’s context. Place it at your project root (or inside .claude/), and it’s automatically loaded at the start of every conversation.

Think of it as a handoff document — the same kind you’d write for a new team member joining your project.

Why Does It Matter?

Without a CLAUDE.md, the AI starts from scratch every time. This leads to:

• Code that doesn’t follow your project’s conventions
• Unnecessary dependency additions
• Ignoring project-specific constraints

A good CLAUDE.md prevents all of these issues.

Basic Structure

# Project Name

## Tech Stack
- Framework: React + Vite
- Styling: Tailwind CSS
- Language: TypeScript

## Coding Conventions
- Functional components only (no class components)
- No CSS-in-JS
- File names in kebab-case (e.g., user-profile.tsx)

## Project Structure
src/
  components/  # Shared components
  pages/       # Page components
  hooks/       # Custom hooks
  utils/       # Utility functions

## Don'ts
- Don't leave console.log statements
- Don't use the `any` type
- Don't add unnecessary comments

Tips for Effective CLAUDE.md

1. Focus on “Don’ts” Over “Dos”

AI tends to be eager to help. Constraints are more effective than encouragement.

## Restrictions
- Don't mock the database in tests (use real DB connections)
- Don't add excessive error handling
- Don't refactor code unless asked

2. Explain the “Why”

Adding reasoning helps the AI make better judgement calls in edge cases.

## Rules
- Use date-fns instead of dayjs (team standard, smaller bundle size)

3. Use the Right File Location

File	Purpose
~/.claude/CLAUDE.md	Personal settings (all projects)
project/CLAUDE.md	Project-specific rules
project/.claude/rules/*.md	Conditional rules

4. Keep It Short

If it’s too long, the AI may miss important parts. Aim for about one page. Write only what truly matters.

Next Steps

• Writing Effective Prompts — Tips for giving better day-to-day instructions