CLAUDE.md is the single most impactful file for Claude Code productivity. Every session, Claude re-reads this file, so every line has a token cost. Over-engineering it wastes tokens; under-investing leads to hallucinations and wasted iterations.
At Pristren, we maintain CLAUDE.md across our monorepo (Zlyqor web, admin, desktop apps). Here's what we've learned in production.
What Belongs in CLAUDE.md
1. Stack One-Liner
State your tech stack concisely. Example:
# Stack: Next.js 16, MongoDB, pnpm, Tailwind 4, TypeScript 5.7
This sets context for every subsequent command and decision.
2. Dev Commands
List essential commands per app. Use a table for clarity:
## Commands
| App | Command |
| zlyqor_web | `pnpm dev` (port 3000) |
| admin | `pnpm dev:admin` (port 3001) |
| desktop | `pnpm tauri dev` |
- Test: `pnpm test` (all apps)
- Lint: `pnpm lint`
- Build: `pnpm build`
3. Auth Patterns
Document how authentication works. For us:
## Auth
- Every protected route calls `getCurrentUser()` first.
- All DB queries filter by `organization_id`.
- Use `withAuth` wrapper for API routes.
4. Package Manager Policy
Enforce consistency:
## Package Manager
- Use **pnpm** only. No npm, no yarn.
- Node version: >=20 LTS (check `.nvmrc`).
5. Design System Pointer
Link to design docs, don't embed tokens:
## Design System
- See [Figma](https://figma.com/file/...) for colors, spacing, typography.
- Use Tailwind classes only; no inline styles.
6. Non-Negotiable Boundaries
State what Claude must never do:
## Rules
- Never skip auth checks.
- Never use `npm`.
- Never commit to `main` directly.
- Never hardcode secrets.
What Does NOT Belong
- Full API documentation — link to
docs/folder. - 50-step deploy runbooks — move to
.claude/skills/deploy/. - SEO enrichment procedure — move to
.claude/skills/seo-audit/. - Historical rationale — why you chose MongoDB is irrelevant.
- Personal preferences — keep it team-agreed.
Example Structure
Here's a minimal but effective CLAUDE.md:
# Zlyqor Monorepo
## Stack
Next.js 16, MongoDB, pnpm, Tailwind 4, TypeScript 5.7
## Apps
| App | Port | Purpose |
| zlyqor_web | 3000 | Main platform |
| admin | 3001 | Admin dashboard |
| desktop | 3002 | Tauri desktop app |
## Commands
cd zlyqor_web && pnpm dev
pnpm test
pnpm lint
pnpm build
## Auth
Every protected route: getCurrentUser() first.
Filter every DB query by organization_id.
## DB
Use MongoDB with Mongoose. All queries scoped to organization_id.
## Skills
- SEO audits: `.claude/skills/seo-audit/`
- Deploy: `.claude/skills/deploy/`
CLAUDE.local.md
For personal machine paths, experimental flags, or API key names (never values). Add to .gitignore.
# CLAUDE.local.md example
OPENAI_API_KEY_NAME=OPENAI_PROD_KEY
LOCAL_PATH=/Users/me/projects
Token Impact
200 lines ≈ ~3,000 tokens per session. 800 lines × 20 sessions/day × 4 developers = 64,000 tokens/day wasted. Treat CLAUDE.md like a hot path in performance profiling.
How to Keep It Under 200 Lines
- Use skills for complex workflows. A skill is a markdown file in
.claude/skills/that Claude can invoke on demand. - Link, don't embed — reference external docs.
- Review monthly — remove stale commands, add new ones.
- Use tables for structured data (apps, ports, commands).
Common Mistakes
- Too verbose — 500+ lines with tutorials. Move to skills.
- Too sparse — missing auth patterns leads to insecure code.
- Outdated — commands that no longer work waste tokens.
- Personal — machine-specific paths in shared file.
FAQ
What is CLAUDE.md best practices 2026?
CLAUDE.md best practices for 2026 focus on keeping the file under 200 lines, including only essential stack info, dev commands, auth patterns, and non-negotiable boundaries. Longer workflows should be moved to .claude/skills/ to save tokens and improve Claude's focus.
How does CLAUDE.md best practices 2026 work?
Claude Code reads CLAUDE.md at the start of every session. By following best practices, you ensure Claude has the right context without wasting tokens on irrelevant details. The file acts as a project-level instruction manual that Claude uses to understand your codebase.
What are the best practices for CLAUDE.md best practices 2026?
Key best practices: keep it under 200 lines, use a stack one-liner, list essential commands, document auth and DB patterns, set non-negotiable rules, and move complex workflows to skills. Also use CLAUDE.local.md for personal config.
How much does CLAUDE.md best practices 2026 cost?
There's no direct cost for CLAUDE.md itself, but token usage impacts your Claude Code bill. A 200-line file costs ~3,000 tokens per session. Over-engineering to 800 lines can cost thousands of extra tokens daily across a team.
Is CLAUDE.md best practices 2026 worth it in 2026?
Absolutely. A well-structured CLAUDE.md reduces hallucinations, speeds up development, and saves tokens. It's one of the highest-ROI practices for teams using Claude Code.
Keep Reading
- LLM Token Optimization in 2026 — model routing, caching, MCP audit
- Claude Code Complete Setup Guide — install, CLAUDE.md, MCP, skills
- Claude Code vs Cursor: Token Cost (2026) — dollar math on identical tasks
- AI Model Sprint — June 2026 — frontier model benchmarks
Pristren builds AI-powered software for teams. Zlyqor is our all-in-one workspace — chat, projects, time tracking, AI meeting summaries, and invoicing.
