Key Takeaways
- Andre Karpathy's CLAUDE.md patterns cut token waste by 40%+.
- Copy his exact config to slash costs and speed up Claude Code.
The Technique
Andre Karpathy — the former Tesla AI director and OpenAI founding member — has been quietly sharing his CLAUDE.md setup, and developers report it's saving "millions of tokens" per project. The secret? A meticulously crafted project-level instruction file that tells Claude Code exactly how to behave, what to prioritize, and what to ignore.
Instead of letting Claude Code figure out your coding style from scratch every time, Karpathy's approach front-loads all context into a single markdown file. The result: fewer wasted tokens on irrelevant suggestions, less hallucination about project conventions, and dramatically faster iterations.
Why It Works
Claude Code reads CLAUDE.md at the start of every session. Without it, the model has zero project-specific context. It doesn't know your preferred testing framework, your commit message format, your linting rules, or which parts of your codebase are sacred.
Karpathy's insight: most token waste comes from the model re-discovering context it could have been given upfront. Every time Claude Code asks "what test framework do you use?" or suggests a refactor of a critical path module, those are tokens burned — and often, incorrect assumptions.
His CLAUDE.md solves this by encoding:
- Code style rules (naming conventions, file structure)
- Testing preferences (framework, coverage targets, mocking strategy)
- Git workflow (commit message format, branch naming)
- Architecture constraints (don't touch X module, always use Y pattern)
- Common pitfalls (things the team has learned the hard way)
How To Apply It
Here's a condensed version of the Karpathy-inspired CLAUDE.md pattern you can drop into any project:
# CLAUDE.md — Project Guidelines
## Code Style
- TypeScript with strict mode enabled
- Use functional components, no class components
- Prefer `const` over `let`; avoid `var`
- 2-space indentation
- Maximum line length: 100
## Testing
- Framework: Vitest
- Coverage target: 80%+ for new code
- Mock external APIs only; never mock internal modules
- Test files co-located with source: `component.test.tsx`
## Git Workflow
- Commit format: `type(scope): description` (e.g., `feat(auth): add OAuth login`)
- Types: feat, fix, refactor, docs, test, chore
- Squash commits before merging
- Never commit directly to `main` or `develop`
## Architecture
- `/src/lib` — shared utilities (do not modify without approval)
- `/src/features` — feature modules (preferred location for new code)
- `/src/api` — API layer (use existing patterns)
- State management: Zustand stores in `/src/stores`
## Common Pitfalls
- Don't use `any` — prefer `unknown` and type narrowing
- Avoid `useEffect` for data fetching — use React Query
- Never import from barrel files (`index.ts`) in production code
- Always handle loading and error states in new components
Pro tip: Add a section for project-specific domain knowledge. If you're building a financial app, include terms like "settlement date" or "margin call" so Claude Code uses correct terminology in code comments and variable names.
The Token Math
A well-crafted CLAUDE.md is ~500 tokens. In a typical session, Claude Code might waste 2,000–5,000 tokens re-establishing context. Over 100 sessions, that's 200,000–500,000 tokens saved — per developer. For a team of 10, that's millions of tokens.
And the quality improvement is even bigger. Fewer wrong suggestions mean fewer rejected code blocks, less time debugging AI-generated nonsense, and faster shipping.
gentic.news Analysis
This CLAUDE.md trend is part of a broader shift we've covered extensively. In our April 23 article "Claude Code's Secret Efficiency Hack," we noted that context caching and prompt engineering are the two biggest levers for Claude Code performance. Karpathy's approach combines both: a static instruction file that acts as a persistent cache for project knowledge.
Claude Code (mentioned in 639 prior articles on gentic.news) has seen explosive adoption, and tools like CLAUDE.md are becoming the standard way teams manage AI agent behavior. This follows Anthropic's April 21 announcement of a 46:1 context cache ratio for managing 39 projects — suggesting the company is actively optimizing for this use case.
Interestingly, Karpathy's approach mirrors what enterprise teams using Claude Agent (53 articles) have discovered: explicit guardrails and style guides dramatically reduce hallucination rates. The difference is that CLAUDE.md makes this accessible to solo developers and small teams.
If you're still running Claude Code without a CLAUDE.md, you're leaving money on the table. Copy the template above, tweak it for your stack, and watch your token burn rate drop.
