Claude Code CLAUDE.md — Best Practices Template

What it is

CLAUDE.md is a project-level configuration file that tells Claude Code how to work within your specific codebase. This template provides a battle-tested structure covering coding conventions, test requirements, git commit rules, and project-specific AI instructions.

Developers who use Claude Code for daily coding, refactoring, or code review benefit from a well-structured CLAUDE.md. It reduces repeated instructions and ensures consistent behavior across sessions.

How it saves time or tokens

Without a CLAUDE.md, you spend tokens re-explaining project conventions every session. With this template, Claude Code reads your rules once and follows them automatically. The estimated token cost of the template itself is around 3,800 tokens, but it saves multiples of that by eliminating repetitive instructions across dozens of interactions.

The template also prevents common mistakes: wrong test framework, incorrect import style, or commits to the wrong branch.

How to use

1. Create a CLAUDE.md file in your project root:

# Project: My App

Tech Stack

• TypeScript, Next.js 14, Tailwind CSS
• PostgreSQL with Prisma ORM
• Jest for unit tests, Playwright for e2e

Coding Conventions

• Use named exports, not default exports
• Prefer async/await over .then() chains
• All components in PascalCase, utilities in camelCase

2. Add test and git rules:

Test Requirements

• Every new function needs a unit test
• Run npm test before committing
• Coverage must not drop below 80%

Git Workflow

• Branch from main, never commit directly
• Commit messages: type(scope): description
• Squash merge only

3. Start Claude Code in your project directory. It reads CLAUDE.md automatically.

Example

A complete minimal CLAUDE.md for a Go microservice:

# Project: user-service

Tech Stack

• Go 1.22, Chi router, sqlc for queries
• PostgreSQL 16, Redis for caching
• Docker Compose for local dev

Conventions

• Errors: return (T, error), never panic
• Logging: slog with structured fields
• Tests: table-driven, use testify/assert

Commands

• make dev -- start local environment
• make test -- run all tests
• make lint -- golangci-lint

Do Not

• Modify generated files in internal/db/
• Add dependencies without checking go.sum
• Use global variables

Related on TokRepo

• AI tools for coding -- More AI-powered development tools and configurations
• Prompt library -- Curated prompts and templates for AI workflows

Common pitfalls

• Making CLAUDE.md too long. Keep it under 4,000 tokens. Claude Code reads it every session, so bloated files waste context window.
• Contradicting rules. If you say 'use default exports' in one section and 'use named exports' in another, Claude Code picks one unpredictably.
• Forgetting to update CLAUDE.md when the tech stack changes. Stale rules cause Claude Code to generate code for the wrong framework version.