📋 CLAUDE.md Master — Project Docs

CLAUDE.md = A Manual for the AI

When a new colleague joins the team, what do you give them? Probably a “team operations guide” of some kind. “Use this format for reports, follow this deployment process, don’t touch this folder” — that sort of thing.

CLAUDE.md serves exactly that role. It’s the very first document Claude Code reads when it “joins” your project. Write your project info, rules, and warnings in this file, and Claude Code automatically reads and follows them.

Why Do You Need It?

“Can’t I just explain things during conversation?” Sure, you can. But there are 3 problems with that.

Creating Your First CLAUDE.md

Creating a CLAUDE.md is simple. Just create a file named CLAUDE.mdin your project root folder. The name must be exactly CLAUDE.md — case-sensitive.

Method 1: Auto-generate with /init (Easiest)

Running /init in Claude Code analyzes your project and auto-generates a CLAUDE.md. The easiest way to start.

/init

Claude Code analyzes your file structure, package.json, config files, etc. and creates a CLAUDE.md draft. Just modify what you need.

Method 2: Ask Claude to Create It

Analyze this project and create a CLAUDE.md.
Include build methods, file structure, and coding rules.

Method 3: Write It Yourself

You can write it manually in a text editor or VS Code. Start with this template:

# CLAUDE.md

## Project Overview
This project is [one-line description].

## Tech Stack
- Framework: Next.js 14
- Styling: Tailwind CSS
- Language: TypeScript (strict mode)

## Commands
```bash
npm run dev       # Dev server
npm run build     # Production build
npm run lint      # Code linting
```

## File Structure
- src/app/        — Pages
- src/components/ — Reusable components
- src/lib/        — Utility functions
- public/         — Static files

## Coding Rules
- Components: export default function (no arrow functions)
- Styling: Tailwind classes only
- State management: zustand
- Import order: React > Next > external libs > internal modules

## Cautions
- Do not commit .env files
- No modifications to node_modules/

CLAUDE.md File Priority

CLAUDE.md can exist in multiple locations, each applying at different scopes. Like company policy → team policy → personal settings, they merge from broadest to narrowest scope.

In most cases, you only need #2 (global) and #3 (project root). The rest are for larger projects.

Reference Other Files with @import

As CLAUDE.md grows longer, it can become hard to read. Use @import to split content across multiple files.

# CLAUDE.md

## Project Overview
This project is an e-commerce platform.

@import docs/coding-rules.md
@import docs/api-guide.md
@import docs/deployment.md

When Claude Code reads CLAUDE.md, it also reads the @imported files, treating them as one big document.

When to use @import?

project/
├── CLAUDE.md                  # Main (overview + @import list)
├── docs/
│   ├── coding-rules.md        # Detailed coding rules
│   ├── api-guide.md           # API integration guide
│   └── deployment.md          # Deployment procedures
└── src/
    └── CLAUDE.md              # src-folder-specific rules

.claude/rules/ — Conditional Rules

You can create rules like “only apply this when editing .ts files.” Create a .claude/rules/ folder in your project root and add rule files inside.

Folder Structure

project/
├── .claude/
│   └── rules/
│       ├── typescript.md       # Applied when working on .ts files
│       ├── testing.md          # Applied when working on test files
│       └── deployment.md       # Applied for deployment tasks
├── CLAUDE.md
└── src/

Rule File Example

Add metadata between --- markers at the top of each rule file. Use globs to specify which files it applies to and description for a brief explanation.

---
description: TypeScript file writing rules
globs: "**/*.ts,**/*.tsx"
---

# TypeScript Rules

- Strict mode: no any types
- Interfaces without I prefix (UserProps OK, IUserProps X)
- Use const object + as const instead of enum
- Always specify function return types

---
description: Test file writing rules
globs: "**/*.test.ts,**/*.spec.ts"
---

# Testing Rules

- Test framework: Jest + React Testing Library
- Use describe > it structure
- Write test names in English
- Mocking: use jest.mock(), mock external libraries

With this setup, Claude Code automatically references the TypeScript rules when editing .ts files, and the testing rules when writing .test.ts files. No need to say “remember, strict mode, no any” every time.

CLAUDE.md Examples by Project Type

CLAUDE.md content varies by project type. Here are 3 ready-to-use examples. Copy the one that fits and customize it.

# CLAUDE.md

## Project
Company homepage. 5 pages (Home, About, Services, Blog, Contact).

## Tech Stack
- Next.js 14 (App Router)
- Tailwind CSS
- TypeScript

## Commands
- Dev: npm run dev (port 3000)
- Build: npm run build
- Deploy: git push → Vercel auto-deploy

## File Structure
- app/           — Pages (App Router)
- components/ui/ — Reusable UI components
- lib/           — Utility functions
- public/        — Images, fonts

## Design Rules
- Font: Pretendard
- Primary color: #171a20 (near-black)
- Accent color: #3e6ae1 (blue)
- Corners: rounded-xl (cards), rounded-md (buttons)
- Spacing: py-20 between sections

## Coding Rules
- Components: export default function
- CSS: Tailwind only (no inline styles)
- Images: next/image required
- English content

## Cautions
- Never commit .env.local
- No files over 10MB in public/

# CLAUDE.md

## Project
Work automation script collection. Data scraping, Excel processing, email sending.

## Environment
- Python 3.12
- Virtual env: .venv (python -m venv .venv)
- Packages: requirements.txt

## Running
```bash
source .venv/bin/activate    # Mac/Linux
.venv\Scripts\activate      # Windows
pip install -r requirements.txt
python main.py
```

## File Structure
- scripts/     — Individual automation scripts
- data/        — Input data (CSV, Excel)
- output/      — Execution results (gitignore)
- utils/       — Common utility functions
- .env         — API keys (gitignore)

## API Integrations
- DART: https://opendart.fss.or.kr/guide/main.do
- Gemini: https://ai.google.dev/docs
- All API keys read from .env

## Rules
- Error handling: try/except required
- Logging: use logging module instead of print
- Type hints: required in function signatures
- Large files (>10MB) go to output/

# CLAUDE.md

## Project
Claude Code learning/experimental project.
A space for free experimentation.

## Environment
- Node.js 22
- No framework

## Rules
- Experiment freely (breaking things is OK)
- Save outputs to output/ folder
- Write comments in English

## Notes
- Lessons from this project will be applied to real projects later

Try It Yourself

Create a CLAUDE.md right now. 5 minutes is all you need.

cd my-project-folder
claude

/init

Create a ~/.claude/CLAUDE.md file.
Contents:
- Respond in English
- Commit messages in conventional commit format
- Code comments in English

# If CLAUDE.md says "use arrow functions for components":

Create a button component.

# → Claude Code should use arrow functions.
# If not, CLAUDE.md wasn't read properly.

Verification Checklist

CLAUDE.md Writing Tips + Sources

Practical tips for more effective CLAUDE.md usage.