A solo founder's CLAUDE.md does a different job. Here are the three rules to lead with.
Most CLAUDE.md guides are written for teams. They assume there is a senior engineer who will catch drift, a PR review that will block sloppy work, and a post-mortem culture that will turn incidents into rules. A solo founder has none of that. The CLAUDE.md is doing all three jobs at once.
That changes which rules carry weight. When we grade solo-founder files in the analyzer at ccmd.dev, the three most-failed Karpathy rules are also the three a one-person shop most needs to pass: #5, #11, and #12. The other nine are nice to have. These three are load-bearing.
1. The three rules that carry the file
Each one is checked by a single regex in the open analyzer source. The phrase you write into the file is the phrase that needs to match. We list both below so you can grade your own file without pasting.
Rule #5 — Avoid Silent Assumptions
Replaces the colleague who would have said 'wait, are you sure?'. The analyzer test at src/lib/analyzer.ts:78 matches /ask (if|when|the)|do not guess|confirm before|surface assumption/. A solo founder needs an explicit clause that tells the agent to ask for the failing test, the prod log line, or the schema when it is not in context. Without it, the agent invents the function signature and you find out at 11 p.m. when staging breaks.
Rule #11 — Failure Mode Coverage
Replaces the post-mortem doc that nobody is going to write. The analyzer test at src/lib/analyzer.ts:114 matches /past failure|previous mistake|do not.*again|we got burned|never again|incident/. The rule passes when at least one named past failure is encoded in the file. Two or three is better. The format that works: one line per incident, with the date, the symptom, and the fix. Skip the prose.
Rule #12 — Self-Improvement Loop
Replaces the senior who would have noticed the file is out of date. The analyzer test at src/lib/analyzer.ts:120 matches /add to this file|update claude\.md|log it here|self.?improve/. The rule passes when the file explicitly delegates its own maintenance to the agent. A solo founder is not going to remember to update CLAUDE.md after every bug, so this clause is the thing that keeps the file load-bearing instead of decorative.
2. A minimal solo-founder template
612 tokens. Passes 10 of 12 on the rubric. Notice what is missing: no review etiquette, no commit conventions, no "always think carefully", no team-onboarding context, no list of personas, no principles paragraph. The file is the constraints that live outside your head. Everything else is decoration.
Steal it, fork it, replace the failure-mode entries with your own. The exact words on the failure-mode and self-improvement clauses matter: they are what the rubric regex matches against. If you rewrite them, paste the result into ccmd.dev to confirm #11 and #12 still pass.
3. What to cut from a forked team template
The single biggest source of bloat we see on solo CLAUDE.md files is a fork of a team template. Half of what is in there does not apply to one person. The shortlist:
| Feature | team-template fork | solo founder file |
|---|---|---|
| PR review etiquette | two paragraphs on diff hygiene | cut entirely — you do not review your own PR |
| Commit conventions you do not enforce | Conventional Commits, scopes, footers | cut — write commits however you write them |
| Personas / 'you are an expert X engineer' | two-line role-play preamble | cut — the agent already knows it is an engineer |
| Stack paragraph | 30-word run-on with deploy details | keep, but split to one short sentence |
| Failure modes section | usually missing | two or three real incidents with dates |
| Self-improvement clause | usually missing | explicit append-on-correction instruction |
| Ask-before-guessing clause | vague 'think carefully' | name the artifacts (test, log, schema) |
4. What the audit looks like, before and after
Same project, two CLAUDE.md files, both pasted into the analyzer. The team-fork file fails three of the rubric rules that matter most for solo work and also trips two token-bloat findings. The solo template passes 10 of 12 and zero findings fire.
5. The token math nobody warned you about
The CLAUDE.md fires every turn. A 30-turn session at the published Opus 4.7 input rate gives you a defensible per-session number on whatever file you wrote. The numbers below are the constants the analyzer uses.
$0.12 per session on the solo template; $0.60 per session on a 4,000-token team fork. Across a daily long session for a month that is the difference between $3.60 and $18. The number is small in isolation. It explains why you hit the weekly limit on a Wednesday afternoon when you thought you had headroom.
“every single API call to Claude sends the whole context, including prompts, meaning that all this extra text in CLAUDE.md is sent over and over”
caymanjim, Hacker News thread 47581701
6. When to re-grade the file
Not on a schedule. The trigger is the moment the agent did the wrong thing and you had to fix it. The fix is now a failure mode worth writing down. Three places this shows up for a solo founder:
- The agent invented a function signature or column name. Add a one-line failure mode and an explicit ask-before-guessing constraint pointing at the artifact it needed (the schema file, the OpenAPI spec).
- A migration, env-var change, or deploy quirk broke prod. Add the symptom and the fix as a single failure-mode line with the date.
- The agent ignored a rule you thought was clear. The rule was probably vague or aspirational. Paste the file into the analyzer; the vague/aspirational findings tell you exactly which line.
Want a 15-minute pass on your CLAUDE.md?
Bring the file. We grade it on the call and leave you with a shortlist of cuts and the failure-mode entries to add. Free.
Frequently asked questions
What should a solo founder's CLAUDE.md actually contain?
Stack (one short paragraph, named tools only), an 'ask before you guess' clause, a 'Failure modes' section with two or three real past incidents and dates, a 'update this file when wrong' clause that delegates self-improvement to the agent, and a small 'Don't' list. That is the whole file. Most solo founders' CLAUDE.md files are bloated because they were forked from a team template. The team rules about review etiquette and PR ceremony do not apply to one person.
Why are Karpathy rules #5, #11, and #12 the load-bearing ones for solo founders?
A team CLAUDE.md offloads correction to other humans. The PR review catches drift; the on-call rotation catches incidents; the senior engineer corrects vague language. A solo founder has none of that. Rule #5 (Avoid Silent Assumptions) replaces the colleague who would have said 'wait, are you sure?'. Rule #11 (Failure Mode Coverage) replaces the post-mortem doc that nobody is going to write. Rule #12 (Self-Improvement Loop) replaces the senior who would have noticed the file is out of date. Skip these three and your CLAUDE.md is decoration.
How long should a solo founder's CLAUDE.md be?
Under 800 tokens is a useful ceiling. The math: every CLAUDE.md line ships on every turn. A 30-turn session at Opus 4.7 input pricing means 30 × tokens × $5/M. An 800-token file is about $0.12 per session before Claude reads a line of your code. A 4,000-token forked-from-a-team-template file is $0.60 of that same overhead. Multiply by daily sessions and the Wednesday weekly-limit hit is suddenly explained. The token budget is real and it compounds.
What should I cut from a team-flavored CLAUDE.md?
Review etiquette (you are not reviewing your own PR), commit conventions you do not enforce, 'always pair on X' style ceremonies, generic 'be helpful' framing, the entire 'about the team' block, lengthy onboarding context (the agent is not a new hire), and any 'in our culture we...' phrasing. Keep the constraints that exist outside your head: API contracts, deployment quirks, the four bugs you have already hit twice. Cut everything else.
How do I actually grade my CLAUDE.md against the Karpathy 12?
Paste it into the textarea on ccmd.dev. The analyzer runs the same twelve regex tests defined in src/lib/analyzer.ts (lines 49-122). Each test is one or two pattern matches against the file text. The output tells you which rules passed, which failed, and the specific phrase that would make a failing rule pass. The analyzer runs entirely in your browser. No upload, no signup.
Will the analyzer work on .cursorrules or AGENTS.md too?
Yes. The same rubric scores all four agent-config formats (CLAUDE.md, AGENTS.md, .cursorrules, .grokrules). Detection at src/lib/analyzer.ts:41 reads the first 300 characters of your paste and picks the right label. The Karpathy 12-rule logic does not care about the filename, only the content. A solo founder running Cursor and Claude Code on the same project usually wants the same rules in both files; the analyzer makes that easy to keep in sync.
How often should a solo founder re-grade the file?
After every session-altering bug or surprise. The trigger is not 'on a schedule', it is 'the agent did the wrong thing and I had to fix it'. The fix you made is now a Failure mode worth writing down. The whole point of rule #12 (Self-Improvement Loop) is to keep the file load-bearing instead of letting it drift into a relic. Five minutes a week of pasting and grading is usually enough.
What is the single highest-impact edit for a typical solo founder file?
Strip any timestamp, 'today is YYYY-MM-DD', or 'this session' line from the top 20 lines of the file. The analyzer's cache_bust check at src/lib/analyzer.ts:194 catches it. Anthropic's prompt cache only hits on byte-identical prefixes, so one volatile string near the top mutates the cached prefix every session and re-bills the full file at full input cost. On a 4,000-token CLAUDE.md that single line can move per-session cost by roughly 10x.
Related: the 12-rule rubric in full, the seven checks the audit runs, or paste your file on the analyzer.
Comments (••)
Leave a comment to see what others are saying.Public and anonymous. No signup.