# 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 the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## 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 -->

## Quick Use

Create `CLAUDE.md` at the project root, defining tech stack, coding conventions, and constraints.

## What is CLAUDE.md?

Claude Code's project config file, specifying how the AI works in your codebase. Equivalent to Cursor's .cursorrules.

**TL;DR**: Claude Code project config. Defines tech stack / coding conventions / testing requirements / constraints. Auto-read. Team standardization. Essential for AI code quality.

**Best for**: Every dev team using Claude Code.

## Template Elements

### 1. Tech Stack — languages / frameworks / databases
### 2. Commands — dev/test/lint/build
### 3. Conventions — imports / naming / error handling
### 4. Constraints — what not to do

## Layering

Global ~/.claude/ → workspace → project root → subdirectories, each overriding the last.

## FAQ

**Q: How long should it be?**
A: 30–100 lines is optimal.

**Q: Can Cursor use it?**
A: No — Cursor uses .cursorrules, but the concept is the same.

## Source & Thanks

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

---
Source: https://tokrepo.com/en/workflows/claude-code-claude-md-best-practices-template-b152c845
Author: Skill Factory