CLAUDE.md Guide: 12 Examples to Configure Claude Code Like a Pro (2026)

CLAUDE.md Guide: 12 Examples to Configure Claude Code Like a Pro (2026)

CLAUDE.md is the single most powerful productivity tool in Claude Code. A well-written CLAUDE.md file cuts coding time by 30-40%, eliminates repetitive instructions, and ensures consistent code quality across sessions. This guide provides 12 real-world CLAUDE.md examples you can copy and adapt for your own projects.

New to Claude Code? Start with our beginner guide or see all 15 Claude Code best practices.

What Is CLAUDE.md?

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session. It acts as project-specific instructions -- telling Claude Code about your architecture, coding conventions, testing setup, and anything else it needs to know.

Think of it as onboarding documentation for your AI pair programmer. Without it, Claude Code makes assumptions about your project. With it, Claude Code follows your exact conventions from the first prompt.

Key facts:

• Placed at the root of your project (next to package.json or equivalent)
• Read automatically -- no need to reference it in prompts
• Supports markdown formatting (headings, lists, code blocks)
• Can be version-controlled and shared across your team
• Maximum effective length: ~200 lines (longer dilutes instructions)

How to Create CLAUDE.md

Run the built-in command:

claude /init

This generates a starter CLAUDE.md from your codebase. Then customize it using the examples below.

Alternatively, create the file manually:

touch CLAUDE.md

12 Real-World CLAUDE.md Examples

Example 1: Next.js App Router Project

# Project: SaaS Dashboard

## Tech Stack
- Next.js 15 (App Router), TypeScript strict
- Prisma + PostgreSQL
- Tailwind CSS, shadcn/ui components
- Vitest for testing

## Conventions
- Server components by default; add "use client" only when needed
- API routes in app/api/*/route.ts -- always validate input with zod
- Database access only in server components or API routes
- Use Prisma's $transaction for multi-table writes
- Error responses: { error: string, code: string }, never throw in API routes

## File Naming
- Components: PascalCase (UserCard.tsx)
- Utils/hooks: camelCase (useAuth.ts)
- API routes: route.ts in kebab-case folders

## Do NOT
- Import Prisma client directly in client components
- Use any -- use unknown + type narrowing
- Create new API routes without input validation

Example 2: Python FastAPI Backend

# Project: Analytics API

## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy 2.0
- PostgreSQL with Alembic migrations
- Pytest for testing
- Redis for caching

## Conventions
- Use async endpoints everywhere (async def, not def)
- Pydantic v2 models for all request/response schemas
- Repository pattern: business logic in /repositories, routes in /routers
- All database queries go through repository classes
- Return typed responses, never raw dicts

## Testing
- Every endpoint needs at least one happy path and one error case test
- Use fixtures from tests/conftest.py -- never create test DB manually
- Run: pytest tests/ -v --cov=app

## Database
- NEVER modify models without creating an Alembic migration
- Migration: alembic revision --autogenerate -m "description"
- Always test migrations up AND down

Example 3: Monorepo (Turborepo)

# Project: Design System Monorepo

## Structure
- /apps -- Next.js applications
- /packages -- Shared libraries (ui, utils, config)
- /tools -- Build scripts and configs

## Conventions
- All shared code goes in /packages, never duplicated across apps
- Import shared code: import { Button } from "@repo/ui"
- Each package has its own package.json and tsconfig.json
- Run tasks with turbo: turbo run build, turbo run test
- Changes to /packages/ui require updating the changelog

## Do NOT
- Create cross-app imports (apps/web importing from apps/admin)
- Add dependencies to individual apps that should be in packages
- Modify turbo.json without team approval

Example 4: React Component Library

# Project: UI Component Library

## Tech Stack
- React 18, TypeScript
- Styled-components (NOT Tailwind)
- Storybook for development and testing
- Rollup for bundling

## Component Rules
- Every component exports: the component, a Props type, and a ref type
- Use forwardRef for all interactive components
- Variants via props (variant="primary"), not CSS classes
- All components must have a corresponding .stories.tsx file
- Accessibility: every interactive element needs an aria-label if no visible text

## Testing
- Visual tests in Storybook (chromatic)
- Unit tests for utility functions with Vitest
- Do NOT test component rendering -- rely on Storybook visual tests

Example 5: Claude Code Subagents Configuration

# Project: Full-Stack App with AI

## Claude Code Setup
- Using subagents for parallel work (see .claude/subagents/)
- Test writer subagent handles all test files
- Reviewer subagent checks security and type safety

Subagent Rules

• Coder subagent: has access to all files EXCEPT tests/
• Test subagent: has access to all files, writes to tests/ only
• Reviewer subagent: read-only access, outputs review comments

Workflow

1. Describe feature in prompt
2. Coder implements, test-writer generates tests simultaneously
3. Reviewer checks output before commit
4. All three outputs must pass before git commit

See our [Claude Code Subagents guide](/blog/claude-code-subagents-multi-agent-guide-2026) for full subagent setup.

### Example 6: Django REST API

```markdown
# Project: E-commerce Backend

## Tech Stack
- Django 5.0, Django REST Framework
- PostgreSQL, Celery + Redis for async tasks
- pytest-django for testing

## Conventions
- All API views use DRF ViewSets, never raw Django views
- Serializers in serializers.py, one per model
- Business logic in services.py -- never in views or models
- Use select_related/prefetch_related to avoid N+1 queries
- All endpoints need authentication (IsAuthenticated minimum)

## Testing
- Factory Boy for test data (tests/factories.py)
- Test every endpoint: list, create, retrieve, update, destroy
- Run: pytest --cov=apps --cov-report=term-missing

## Do NOT
- Put business logic in models.py (use services.py)
- Use Django templates (API-only project)
- Create migrations without testing on a fresh database

Example 7: TypeScript SDK/Library

# Project: Analytics SDK

## Tech Stack
- TypeScript 5.4, tsup for bundling
- Vitest for testing
- Zero runtime dependencies

## Conventions
- Every public function has JSDoc with @param and @returns
- Strict TypeScript: no implicit any, no unchecked index access
- Export from src/index.ts only -- internal modules stay internal
- Error handling: return Result<T, E> type, never throw

## Publishing
- Version: semantic versioning (BREAKING.FEATURE.FIX)
- Run: npm version patch && npm publish
- Changelog: auto-generated from conventional commits

Example 8: Existing Codebase Cleanup

# Project: Legacy Migration

## Context
- Migrating from JavaScript to TypeScript (50% complete)
- Old files in /legacy, new files in /src
- Do NOT modify /legacy files unless fixing a critical bug

## Migration Rules
- When touching a .js file, convert it to .ts in the same PR
- Add types for all function parameters and return values
- Replace require() with import statements
- Update imports in all files that reference the converted file

## Priority
1. API routes (highest traffic)
2. Database models
3. Utility functions
4. UI components (last)

Example 9: MCP Server Integration

# Project: DevOps Dashboard

## MCP Configuration
- GitHub MCP server: configured in .claude/mcp.json
- Filesystem MCP server: read-only access to /docs
- Do NOT use MCP servers for write operations -- always review changes manually

## MCP Rules
- GitHub operations: read issues, create PRs, check CI status
- Never push directly to main via MCP
- Always reference the issue number in commit messages

See our MCP Servers guide for setup instructions.

Example 10: Testing-First Configuration

# Project: Payment Processing

## Testing Philosophy
- Tests BEFORE implementation (TDD)
- Every PR must maintain 90%+ coverage
- Integration tests for payment flows are mandatory
- Mock external APIs -- never hit real payment APIs in tests

## Test Structure
- Unit tests: *.test.ts next to source files
- Integration tests: /tests/integration/
- E2E tests: /tests/e2e/ (run nightly on CI)
- Fixtures: /tests/fixtures/ (shared test data)

## Do NOT
- Skip writing tests "for now" -- always write them first
- Use real database in unit tests (mock the repository)
- Commit without running: npm run test:ci

Example 11: Security-Focused Project

# Project: Healthcare API

## Security Requirements (CRITICAL)
- All PHI (Protected Health Information) must be encrypted at rest
- API responses must never include more data than requested
- Audit log every database write (who, what, when)
- Rate limit all endpoints: 100 req/min per user
- Input validation on EVERY endpoint -- no exceptions

## Code Patterns
- Use parameterized queries only (never string interpolation in SQL)
- Sanitize all user input with DOMPurify before storage
- JWT tokens expire in 15 minutes, refresh tokens in 7 days
- Password hashing: bcrypt with cost factor 12

## Do NOT
- Log request bodies (may contain PHI)
- Return full user objects -- always select specific fields
- Store API keys in code -- use environment variables

Example 12: Minimal/Beginner Setup

# Project: Personal Portfolio

## Stack
- Next.js 15, TypeScript, Tailwind
- Deployed on Vercel

## Rules
- Use the App Router (not Pages Router)
- All pages in /app directory
- Components in /components
- Keep it simple -- no unnecessary dependencies

CLAUDE.md Best Practices

Do:

• Keep it under 200 lines
• Use specific examples, not generic advice
• Include "Do NOT" sections for critical rules
• Version control it with your project
• Update it when conventions change

Don't:

• Put generic coding advice ("write clean code")
• Include lengthy explanations -- Claude Code understands context
• List every file in your project -- only non-obvious structure
• Duplicate information that's in your README

How CLAUDE.md Interacts with Other Claude Code Features

Frequently Asked Questions

Where does CLAUDE.md go?

Place it at the root of your project, next to package.json (or equivalent). Claude Code reads it automatically.

Can I have multiple CLAUDE.md files?

Claude Code reads one CLAUDE.md per project root. For subdirectory-specific rules, use a .clauderc file or add rules in your project's .claude/commands/ directory.

Does CLAUDE.md work with Cursor or other tools?

No. CLAUDE.md is specific to Claude Code. Cursor uses .cursorrules and OpenCode uses its own config format. See our Claude Code vs Cursor comparison.

How long should CLAUDE.md be?

Keep it under 200 lines. Claude Code reads the entire file into context, so longer files consume more tokens and dilute the most important instructions.

Can I use CLAUDE.md for multi-agent setups?

Yes. Each subagent reads CLAUDE.md independently. You can add subagent-specific rules in the subagent's system prompt. See our subagents guide.

The Bottom Line

A well-crafted CLAUDE.md file is the difference between Claude Code guessing what you want and Claude Code knowing what you want. Start with /init, then customize using the examples above. The 30 minutes you spend writing CLAUDE.md saves hours of correcting Claude Code's assumptions.

Want to take Claude Code further? Ivern AI connects Claude Code, Cursor, and other AI agents into coordinated squads -- a researcher gathers context, Claude Code implements, and a reviewer validates. All through a unified interface with BYOK pricing.

Related guides: Claude Code Best Practices (15 Pro Tips) · How to Use Claude Code (Beginner Guide) · Claude Code Subagents · Claude Code vs Cursor · Claude Code vs OpenCode · Claude Code Task Management · MCP Servers Guide · Best Claude Code Alternatives · AI Coding Assistant Pricing · All Tutorials