Claude Code as your 'idea file': the Karpathy-style CLAUDE.md pattern

Andrej Karpathy just shared his LLM wiki as an 'idea file' — a living document where he dumps thoughts, patterns, and observations about working with LLMs.

Claude Code has a built-in version of this. It's called CLAUDE.md.

Here's how to set it up as a proper idea file for your codebase.

What is an idea file?

Karpathy's concept: a running log of observations, hypotheses, and patterns you accumulate while working with a tool. Not documentation. Not a changelog. A thinking partner document.

For Claude Code, this translates to: a CLAUDE.md that captures not just project facts, but your evolving understanding of how Claude performs best in your specific codebase.

The basic setup

# Create CLAUDE.md in your project root
touch CLAUDE.md

Most developers write CLAUDE.md as static documentation:

# Project
This is a Node.js API. Use Express. Tests with Jest.

That's fine. But it's not an idea file.

The idea file version

# CLAUDE.md — living idea file

## Project facts
- Node.js + Express API
- PostgreSQL with Knex
- Jest for tests, Supertest for integration

## Patterns that work
- Claude performs better when I give it the full error stack, not just the message
- Asking Claude to 'think step by step before writing code' reduces hallucinated API calls by ~80%
- For DB migrations, always show Claude the existing migration files first

## Patterns that fail
- Don't ask Claude to refactor AND add tests in one prompt — split them
- Claude tends to over-engineer auth middleware — tell it to keep it simple

## Current hypotheses (testing)
- Does giving Claude git log context improve commit message quality? (testing this week)
- Is it faster to give Claude the full schema or just the relevant tables?

## Observations log
- 2026-04-01: Claude correctly caught a race condition in the webhook handler that I missed
- 2026-03-28: Claude suggested extracting a service layer I'd been avoiding — was right

This is the Karpathy approach applied to Claude Code: accumulate observations over time.

Why this changes your workflow

Static CLAUDE.md tells Claude about your project.

Idea-file CLAUDE.md tells Claude how to work with you specifically on this project.

The difference:

• Static: "We use PostgreSQL"
• Idea file: "When querying PostgreSQL, show me the query plan before writing the ORM call — I've caught 3 N+1 issues this way"

The session note pattern

At the end of each Claude Code session, add a note:

# Add to CLAUDE.md automatically at session end
echo "\n## Session $(date +%Y-%m-%d)" >> CLAUDE.md
echo "- [what worked today]" >> CLAUDE.md
echo "- [what to try next time]" >> CLAUDE.md

Or just do it manually. 30 seconds. Compounds fast.

The hypothesis testing loop

This is where it gets powerful. Treat Claude like an experiment:

## Active hypotheses
- H1: Giving Claude the test file before the source file → fewer hallucinated imports (testing)
- H2: 'Rubber duck first' prompts (explain the bug before asking Claude to fix it) → faster resolution
- H3: Breaking changes in the schema should be shown as diffs, not full schema

When you have results:

## Confirmed patterns
- ✅ H1 CONFIRMED: Show tests first — Claude writes implementation to match, zero import errors in last 5 sessions
- ❌ H2 REJECTED: Rubber duck prompts add time without accuracy gain for simple bugs

Now your CLAUDE.md is a knowledge compounding system, not a static README.

Rate limits break this loop

The biggest friction with the idea-file pattern: you're mid-session, Claude is in flow, and you hit a rate limit.

Context dumps. You lose the thread. Your observations don't compound.

Fix: set ANTHROPIC_BASE_URL to simplylouie.com/developers — it proxies Claude at ✌️$2/month with rate limits removed. Your sessions run until you're done, not until Anthropic's counter resets.

export ANTHROPIC_BASE_URL=https://simplylouie.com/api/proxy
claude  # now runs without rate limit interruptions

The compounding effect

After 30 days of the idea-file pattern:

• You have a CLAUDE.md that genuinely captures how Claude works best with your brain
• Future sessions start with accumulated wisdom, not a blank slate
• You can share the CLAUDE.md with teammates — they inherit your learnings

Karpathy's insight: the value isn't the individual notes. It's the accumulation.

Same thing applies to Claude Code. Start the idea file today. It's worth nothing on day 1 and invaluable on day 30.

---

What patterns have you added to your CLAUDE.md? Drop them in the comments — building a community knowledge base here.