CLAUDE.md Files & /init

What is CLAUDE.md?

A CLAUDE.md file is a special Markdown document that gives Claude Code persistent instructions about your project. It's read automatically at the start of every session, ensuring Claude always knows your project's conventions, tech stack, and coding rules without you having to repeat them.

Think of it as a README.md for AI — but instead of helping humans understand your project, it helps Claude write code that fits perfectly into your codebase.

Generating CLAUDE.md with /init

The fastest way to create a CLAUDE.md is letting Claude analyze your project:

# Inside your project directory
claude

# Then type:
> /init

Claude scans your project structure, reads key files (package.json, tsconfig.json, etc.), and generates a comprehensive CLAUDE.md tailored to your codebase. You can edit it afterward to add anything it missed.

CLAUDE.md Location Hierarchy

Claude Code reads CLAUDE.md files from multiple locations, in order of specificity:

# 1. Global — applies to ALL your projects
~/.claude/CLAUDE.md

# 2. Project root — applies to the entire repo
/my-project/CLAUDE.md

# 3. Subdirectory — applies when working in that directory
/my-project/src/api/CLAUDE.md
/my-project/src/components/CLAUDE.md

More specific files add to (not replace) the global ones. This lets you set global preferences while adding project-specific or module-specific rules.

What to Include

Here's a well-structured CLAUDE.md example:

# CLAUDE.md

## Project Overview
Full-stack e-commerce app with Next.js 14 frontend and Go Fiber backend.

## Tech Stack
- Frontend: Next.js 14 (App Router), TypeScript strict mode
- Styling: TailwindCSS v4
- Backend: Go Fiber v2
- Database: MySQL 8, raw SQL (no ORM)
- Auth: JWT with httpOnly cookies

## Code Conventions
- Use functional components with hooks (no class components)
- File naming: kebab-case (e.g., user-profile.tsx)
- Use named exports, not default exports
- Import order: React → Third-party → Local → Styles

## Architecture
- API routes: app/api/[resource]/route.ts
- Shared components: components/ui/
- Business logic: lib/ (never in components)
- All DB queries use parameterized statements

## Commands
- Dev server: npm run dev
- Build: npm run build
- Test: npm test
- Lint: npm run lint

## Do NOT
- Use the Pages Router
- Use CSS Modules (TailwindCSS only)
- Install new dependencies without asking
- Use any deprecated React patterns

Key Sections Explained

Commands Section

Listing your common commands is especially valuable. When Claude needs to run tests or start a dev server, it knows exactly which commands your project uses instead of guessing.

Do NOT Section

This is often the most valuable section. Explicitly stating anti-patterns prevents Claude from generating code with legacy syntax, wrong framework patterns, or unwanted dependencies.

Architecture Section

Telling Claude where things go prevents misplaced files. Without this, Claude might put a utility function inside a component or create an API route in the wrong directory.

Updating CLAUDE.md Over Time

Your CLAUDE.md should evolve with your project. When you introduce a new convention or change your tech stack, update the file. Claude can even help:

> Update CLAUDE.md to reflect that we now use Drizzle ORM instead of raw SQL

What's Next

In the next episode, we'll explore Context — how Claude gathers information about your project, manages its context window, and how you can provide the right context for better results.