# Claude Code CLAUDE.md — Best Practices Template

> Production-tested CLAUDE.md template for Claude Code projects. Covers coding conventions, test requirements, git workflow, and project-specific AI instructions.

## Install

Save in your project root:

## Quick Use

Create `CLAUDE.md` in your project root:

```markdown
# Project: My App

## Tech Stack
- TypeScript, Next.js 14 (App Router), Tailwind CSS, Prisma ORM
- Testing: Vitest + Playwright
- Package manager: pnpm

## Coding Conventions
- Use functional components with TypeScript interfaces
- Prefer named exports
- Use server components by default, "use client" only when needed
- Error handling: try/catch with proper error types, never swallow errors

## File Structure
- app/ — Next.js app router pages and layouts
- components/ — Reusable UI components (PascalCase.tsx)
- lib/ — Utilities, API clients, helpers
- types/ — Shared TypeScript types

## Testing Requirements
- Run `pnpm test` after any code changes
- Write tests for new functions (vitest)
- E2E tests for user-facing flows (playwright)

## Git Workflow
- Branch naming: feature/*, fix/*, refactor/*
- Commit messages: conventional commits (feat:, fix:, refactor:)
- Never force push to main

## Do NOT
- Modify files in /vendor/ or /generated/
- Add dependencies without asking
- Create .env files or hardcode secrets
- Add comments to obvious code
```

## What is CLAUDE.md?

CLAUDE.md is a project-level configuration file that tells Claude Code how to work in your codebase. It is the equivalent of `.cursorrules` for Cursor — project-specific AI instructions that improve code quality, enforce conventions, and reduce hallucination. Claude Code reads CLAUDE.md automatically from your project root and any parent directories.

**Answer-Ready**: CLAUDE.md is the project config file for Claude Code. Defines tech stack, coding conventions, testing requirements, and constraints. Claude Code reads it automatically. Equivalent of .cursorrules for Cursor. Essential for consistent AI-generated code.

**Best for**: Any team using Claude Code for development. **Works with**: Claude Code (all versions). **Setup time**: Under 5 minutes.

## Template Sections

### 1. Project Overview

```markdown
## Project
Brief description of what this project does.
Deployed at: https://example.com
Repo: github.com/org/repo
```

### 2. Tech Stack & Architecture

```markdown
## Stack
- Frontend: React 19, Next.js 15, Tailwind CSS
- Backend: Python 3.12, FastAPI, SQLAlchemy
- Database: PostgreSQL 16
- Cache: Redis 7
- Deploy: Docker + AWS ECS
```

### 3. Commands

```markdown
## Commands
- `pnpm dev` — Start dev server
- `pnpm test` — Run unit tests
- `pnpm lint` — Lint + format check
- `pnpm build` — Production build
- `pnpm db:migrate` — Run database migrations
```

### 4. Conventions

```markdown
## Conventions
- Use absolute imports (@/components/Button)
- Prefer Zod for runtime validation
- API routes return { data, error } shape
- Use date-fns for date operations (not moment)
```

### 5. Constraints (Critical)

```markdown
## Do NOT
- Modify the auth middleware without review
- Add new npm dependencies without discussion
- Write to the /public directory at runtime
- Use any environment variable not in .env.example
```

## Multi-Level CLAUDE.md

Claude Code reads CLAUDE.md from multiple locations:
```
~/.claude/CLAUDE.md              # Global (all projects)
~/projects/CLAUDE.md             # Workspace level
~/projects/my-app/CLAUDE.md      # Project level (highest priority)
~/projects/my-app/src/CLAUDE.md  # Subdirectory level
```

## Best Practices

1. **Start small** — 20-30 lines covering the essentials
2. **Be specific** — "Use date-fns" beats "use a date library"
3. **Include commands** — Claude Code runs tests/lint automatically
4. **Update regularly** — CLAUDE.md should evolve with your codebase
5. **Add constraints** — Tell Claude what NOT to do
6. **Keep it DRY** — Don't repeat what is obvious from package.json

## FAQ

**Q: Where should I put CLAUDE.md?**
A: Project root. Claude Code also reads from parent directories and ~/.claude/CLAUDE.md for global settings.

**Q: How long should it be?**
A: 30-100 lines is the sweet spot. Too short lacks context, too long wastes context window.

**Q: Does it work with Cursor too?**
A: No, Cursor uses `.cursorrules`. But the concept is identical — you can maintain both with similar content.

**Q: Can I use it for team standardization?**
A: Yes, commit CLAUDE.md to git. All team members get the same AI behavior.

## Source & Thanks

> - [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code)
> - [awesome-claude-md](https://github.com/anthropics/claude-code) — Examples and best practices

<!-- ZH -->

## 快速使用

在项目根目录创建 `CLAUDE.md`，定义技术栈、编码规范和约束。

## 什么是 CLAUDE.md？

Claude Code 的项目配置文件，定义 AI 在你的代码库中如何工作。等同于 Cursor 的 .cursorrules。

**一句话总结**：Claude Code 项目配置文件，定义技术栈/编码规范/测试要求/约束，自动读取，团队标准化，AI 代码质量必备。

**适合人群**：使用 Claude Code 的所有开发团队。

## 模板要素

### 1. 技术栈 — 语言/框架/数据库
### 2. 命令 — dev/test/lint/build
### 3. 规范 — 导入/命名/错误处理
### 4. 约束 — 不要做什么

## 多层级

全局 ~/.claude/ → 工作区 → 项目根 → 子目录，逐级覆盖。

## 常见问题

**Q: 多长合适？**
A: 30-100 行最佳。

**Q: Cursor 也能用？**
A: 不能，Cursor 用 .cursorrules，但概念相同。

## 来源与致谢

> [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code)

---
Source: https://tokrepo.com/en/workflows/b152c845-95bc-493e-af27-b7f882e8896b
Author: Skill Factory