ConfigsApr 8, 2026·2 min read

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.

Skill Factory
Skill Factory · Community
TL;DR
A production-tested CLAUDE.md template that configures Claude Code with project conventions, test rules, and git workflow.
§01

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.

§02

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.

§03

How to use

  1. Create a CLAUDE.md file in your project root:
# Project: My App
§04

Tech Stack

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

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:
§06

Test Requirements

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

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.
§08

Example

A complete minimal CLAUDE.md for a Go microservice:

# Project: user-service
§09

Tech Stack

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

Conventions

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

Commands

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

Do Not

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

Related on TokRepo

§14

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.

Frequently Asked Questions

Where should I place the CLAUDE.md file?+

Place it in the root of your project repository. Claude Code automatically detects and reads CLAUDE.md when you start a session in that directory. You can also place additional CLAUDE.md files in subdirectories for module-specific rules.

How long should a CLAUDE.md file be?+

Aim for 2,000 to 4,000 tokens (roughly 1-2 pages of text). This is enough to cover tech stack, conventions, test rules, and git workflow without consuming too much of the context window. Prioritize rules that Claude Code frequently gets wrong without guidance.

Can CLAUDE.md replace in-chat instructions?+

For recurring rules, yes. Put anything you would repeat across sessions into CLAUDE.md. For one-off requests (like a specific refactoring task), use in-chat instructions. Think of CLAUDE.md as your project constitution and chat messages as individual tasks.

Does CLAUDE.md work with other AI coding tools?+

CLAUDE.md is specific to Claude Code (Anthropic). Other tools like Cursor use .cursorrules, and GitHub Copilot uses .github/copilot-instructions.md. The concepts are similar, but the file names and supported features differ.

How do I test if my CLAUDE.md is working correctly?+

Start a new Claude Code session and ask it to perform a task covered by your rules (e.g., create a new component). Check whether it follows your conventions without you specifying them. If it does not, your rules may be unclear or contradictory.

Citations (3)
Related on TokRepo
AI coding toolsPrompt libraryFeatured workflows
🙏

Source & Thanks

Discussion

Sign in to join the discussion.
No comments yet. Be the first to share your thoughts.

Related Assets

Claude-Flow — Multi-Agent Orchestration for Claude Code

Layers swarm and hive-mind multi-agent orchestration on top of Claude Code with 64 specialized agents, SQLite memory, and parallel execution.

Skill Factory

ccusage — Real-Time Token Cost Tracker for Claude Code

CLI that reads ~/.claude logs and breaks down Claude Code token spend by day, session, and project — pluggable into your statusline.

Skill Factory

SuperClaude — Workflow Framework for Claude Code

Adds 16+ slash commands, 9 cognitive personas, and a smart flag system to Claude Code in one pipx install.

Skill Factory
◈Home🔍Search👤Me