CLAUDE.md Examples: Web App, Monorepo, Rules & Anti-patterns (Copy-Paste)

CLAUDE.md is the project instruction file Claude Code reads automatically at the start of every session. Concepts and setup are covered in a separate guide; this article collects copy-paste examples by scenario plus common anti-patterns. Every example follows the format in the official Anthropic memory docs. (As of June 2026; company names and stacks are illustrative.)

What to put in it

The official guidance is to write down what you'd otherwise re-explain. Add an entry when: Claude makes the same mistake a second time, a code review catches something Claude should have known, you type the same correction you typed last session, or a new teammate would need the same context. Keep it to facts needed in every session — build commands, conventions, layout, "always do X" rules — and move multi-step procedures or area-specific content into skills or path-scoped rules.

Example 1 — Web app project (./CLAUDE.md)

The most common form, shared with your team via version control. Be specific about commands, conventions, and cautions.

# Project: Internal Dashboard (example)

## Stack
- Next.js (App Router) + TypeScript + Tailwind

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test` (always run before committing)
- Lint: `pnpm lint`

## Conventions
- 2-space indentation, use semicolons
- Components in `src/components/`, API handlers in `src/app/api/`
- `pnpm lint` must pass before committing

## Cautions
- Do not edit schema files in `src/lib/db/` without a migration

Example 2 — Monorepo root

In a monorepo, keep only shared rules at the root and let each package have its own CLAUDE.md. Use @import to pull in a README or release doc (relative and absolute paths, up to 4 hops).

# Monorepo root (example)

Each package has its own CLAUDE.md. Keep only shared rules here.

## Shared rules
- Package manager: pnpm (no npm/yarn)
- Test any package with `pnpm -F <pkg> test`

## Imports
See @README for overview.
- Release process @docs/release.md

Example 3 — Path-scoped rules (.claude/rules/)

Large projects can split instructions into topic files under .claude/rules/. With YAML paths frontmatter, a rule loads only when Claude works with matching files, saving context.

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules
- All endpoints include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

Example 4 — Projects already using AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If you already use AGENTS.md, create a CLAUDE.md that imports it so both tools read the same instructions without duplication.

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`

Common anti-patterns

• Vague instructions: write verifiable rules — "use 2-space indentation" beats "format code nicely".
• Giant files: target under 200 lines per file. Longer files consume more context and reduce adherence. Splitting with @import doesn't reduce context (imports load at launch), so use path-scoped rules to trim.
• Contradicting rules: if two rules conflict, Claude may pick one arbitrarily. Review periodically and remove conflicts.
• Cramming procedures / one-offs: move multi-step procedures to skills and area-specific rules to path-scoped rules.

The refinement order

Generate a draft with /init (it suggests improvements if a file already exists), then add rules for corrections that recur in real use. Use /memory to verify which CLAUDE.md and rules files are loaded in the current session. CLAUDE.md is delivered as context, not the system prompt, so it isn't strict enforcement — anything that must run at a specific point (like before every commit) is safer written as a hook.

Related reading

For the underlying concepts and setup, see the complete CLAUDE.md guide. To package repeatable workflows, see the Claude Code skills guide.

New here?: Creating Your First CLAUDE.md (beginner)