This 4-Rule Markdown File Has 91,000 GitHub Stars. It Humbled Me.

No model. No framework. No dependencies. Just one text file that broke the internet — and exposed what we’ve all been doing wrong with AI coding tools.

I almost didn’t click on it.

Frinds Link — https://medium.com/stackademic/this-4-rule-markdown-file-has-91-000-github-stars-it-humbled-me-95a3417cfebc?sk=dca7de2fa0e0e0a49072a4328f922696

Another LinkedIn post. Another “this repo blew up overnight” screenshot. I’ve seen enough of those to know the pattern: someone discovers a wrapper around ChatGPT, calls it a revolution, gets 200 reposts from people who haven’t read past the title.

Then I checked the actual repo.

91,000 stars. Trending #1 on GitHub. No Python. No TypeScript. No model weights. Not even a package.json.

Just one file. CLAUDE.md. Four rules inside it. Plain text.

And here’s the part that genuinely bothered me: I recognized every single rule. Not because they were brilliant. Because every senior engineer I’ve ever worked with has said some version of them out loud — usually while debugging a mess that an AI agent made.

That’s when I understood why it went viral. And why it should bother all of us.

The File That Started It

The backstory matters here.

In January 2026, Andrej Karpathy — Stanford PhD, early OpenAI, the person who built Tesla’s Autopilot vision system from scratch — posted on X that he’d flipped his coding workflow from 80% manual to 80% AI-driven in roughly two months.

That alone wasn’t the story. What caught people’s attention was the complaints buried in his thread. Specific, technical, repeatable complaints about how Claude Code was failing him.

A developer named Forrest Chang read those complaints and did something deceptively simple: he turned them into a CLAUDE.md file and pushed it to GitHub.

It hit 60,000 stars before most people had even heard of CLAUDE.md as a concept. Then it kept going.

So what are these four rules? I’ll get to them. But first you need to understand why they exist — because that context changes everything.

Why Claude Forgets You Every Single Morning

Here’s something most developers using Claude Code don’t fully internalize: the model has no memory between sessions.

Not “limited memory.” Zero memory. Claude Code wakes up every conversation knowing nothing about your project, your stack, your conventions, or the mistakes it made yesterday. Its weights are frozen at inference time. It’s a stateless system wearing the costume of a persistent collaborator.

This creates a very specific kind of pain. You spend a session correcting Claude — “we use pnpm, not npm" — "our test command is make test-integration, not pytest" — "we don't use default exports here." And then the next day, same conversation, same corrections, all over again.

This is where CLAUDE.md comes in.

Claude Code reads this file at the start of every single session and injects it into the system prompt. It’s not magic — it’s just a mechanism to turn your institutional knowledge into persistent context. Think of it as the onboarding document you’d hand a brilliant-but-amnesiac senior engineer on day one.

There are three places Claude reads it from, merged in order:

• Global (~/.claude/CLAUDE.md) — applies to every project on your machine
• Project root (./CLAUDE.md) — specific to the current repo, commit this to git
• Subdirectory (./subdir/CLAUDE.md) — module-level rules, loaded only when Claude enters that folder

There’s also CLAUDE.local.md for personal overrides you don't want your teammates to see. Add it to .gitignore.

The Four Rules That Humbled the Industry

Here’s what Karpathy observed — and what Chang turned into the viral file. These aren’t clever. They’re embarrassingly obvious. That’s exactly the point.

Rule 1: Stop making silent assumptions.

When Claude encounters ambiguity, it picks an interpretation and runs with it. It doesn’t surface tradeoffs. It doesn’t ask. It builds 200 lines on top of an assumption it never told you it made. By the time you see the output, you’re debugging a decision that was made invisibly in line two.

The rule: Ask before assuming. Surface the ambiguity explicitly.

Rule 2: Stop over-engineering.

You ask for a function that parses a config file. Claude writes an abstract factory pattern with a plugin architecture, three interfaces, and a dependency injection container — for something that will run once in a CI script.

The rule: Write the minimum code that solves the actual problem. No abstraction layers for single-use code. No clever patterns that make future maintenance harder.

Rule 3: Stop causing collateral damage.

This is the one that’s burned the most developers. You ask Claude to fix a bug in auth.py. It fixes the bug. It also quietly reformats comments in utils.py, renames a variable in config.py, and adjusts some imports in models.py — files you never mentioned, in ways that weren't asked for.

Now your diff is a mess. Your PR reviewer is confused. And if something breaks, you don’t know where to look.

The rule: Only touch files and functions directly related to the task. If something adjacent looks wrong, flag it — don’t silently fix it.

Rule 4: Stay honest about what you don’t know.

Models have a well-documented tendency to confabulate — to produce confident, plausible-sounding output that’s simply wrong. They’ll cite an API that doesn’t exist, implement a pattern that won’t compile, or describe a library feature that was deprecated two versions ago.

The rule: Say “I’m not sure” when you’re not sure. Don’t invent. Flag uncertainty explicitly.

Why These Rules Are Actually About Psychology, Not Prompting

Here’s the thing that took me a while to see.

These four rules aren’t really about Claude. They’re about the implicit contract between a developer and an AI tool — and what happens when that contract is violated repeatedly without the developer realizing it.

When an AI assistant makes silent assumptions, you lose trust in its output. You start double-checking everything. The cognitive load goes up. The time savings disappear.

When it over-engineers, you spend more time understanding what it built than you would have spent just building it yourself.

When it causes collateral damage, you stop giving it access to your full codebase. You start passing it isolated snippets instead. Now you’ve turned a powerful agent back into a glorified autocomplete.

When it confabulates, you can’t use it for anything you haven’t already verified — which means you can’t use it for the things you actually need help with.

The viral CLAUDE.md went viral because it named these failure modes clearly, in one place, in a format that directly fixes them. That's the whole secret.

How to Write a CLAUDE.md That Actually Changes Claude’s Behavior

The official Anthropic docs suggest running /init to generate a starter file, then deleting most of what it produces. /init scans your codebase and creates a thorough description — but most of that description is stuff Claude can already infer from your package.json, directory structure, and file contents. You're burning token budget on redundant context.

Keep your file under 300 lines. Research on frontier LLMs suggests they reliably follow around 150–200 instructions per prompt. Claude Code’s own system prompt already uses roughly 50 of those slots. Past the limit, Claude starts quietly dropping your rules — and not the ones you’d choose.

A useful CLAUDE.md answers three questions and nothing else:

What is this project? One sentence. “FastAPI backend for a SaaS billing system using Stripe and PostgreSQL.” That’s it. Not the history, not the vision doc, not the architectural decision record.

How do you work on it? Exact commands, not principles. Not “run the tests before committing” but make test-integration && pnpm lint:fix. Claude uses these verbatim. Imprecise instructions produce imprecise behavior.

What will Claude get wrong without this file? This is where all the value is. Go through your git history. Find the corrections you’ve made more than once. Those are your rules. “We don’t use default exports.” “API responses always use envelope format: {data: ..., error: ...}." "Never modify src/legacy/ without asking first." If you'd never need to say it out loud to a new team member, cut it.

The Number That Puts This in Context

OpenAI’s AGENTS.md — a parallel standard for configuring AI agents across codebases — was released in August 2025 and has since been adopted by over 60,000 open-source projects. The Linux Foundation now governs it under the Agentic AI Foundation umbrella.

The broader trend is clear: developers aren’t just using AI tools. They’re learning to configure them. The gap between developers who invest 30 minutes in a thoughtful CLAUDE.md and those who don't is widening faster than most people realize.

The ones who treat AI agents like raw prompts they fire at randomly are spending hours correcting the same mistakes. The ones who treat CLAUDE.md as infrastructure — something you design deliberately and update as your project evolves — are shipping faster and dealing with less mess.

What I Changed After Reading the Viral File

I pulled up my own CLAUDE.md. I had 47 lines. After reading Karpathy's four rules carefully, I realized I had covered two of them. Partially.

The two I was missing — silent assumptions and collateral damage — were exactly the failure modes that had been annoying me most in the past month. I’d just been absorbing the friction without naming it.

I added six lines. Specific, concrete, non-negotiable rules around asking before assuming and touching only explicitly named files.

The next session was noticeably different. Not dramatically. Not magically. Just — quieter. Fewer corrections. Less second-guessing. The diff was clean.

Six lines.

That’s what 91,000 stars are about.

The Template

Here’s a minimal starting point. Modify aggressively based on your actual corrections, not what you think you should document.

# Project Context FastAPI service for [your purpose]. PostgreSQL database. Redis cache.

**# Commands

• Test: make test
• Lint: ruff check . && ruff format .
• Run locally: uvicorn main:app — reload**

**# Conventions

• No default exports
• All API responses use {“data”: …, “error”: null} envelope
• Test files live in tests/, not test/
• Never modify src/legacy/ without explicitly asking**

**# Behavior Rules

• Ask before assuming when requirements are ambiguous
• Write minimum code to solve the stated problem — no preemptive abstraction
• Only modify files and functions directly involved in the current task
• Say “I’m not sure” when uncertain rather than confabulating**

Cut anything you wouldn’t need to say to a senior engineer who already knows your stack. Keep anything you’ve had to say more than once.

That’s it. That’s the whole thing.

My Thought

The reason a four-rule markdown file hit 91,000 stars isn’t that the rules are novel. It’s that we’ve all been absorbing the cost of not having them, and nobody had bothered to write them down in one place and ship it.

The best tools in engineering are often like this. Not inventions. Articulations. Someone names the thing everyone was already experiencing, packages it cleanly, and suddenly everyone can act on it.

If you use Claude Code and you don’t have a CLAUDE.md, you're paying a daily tax in corrections and frustration that could be eliminated in an afternoon.

If you have one but haven’t updated it since you created it, it’s probably not reflecting the project you’re actually working on anymore.

And if, like me, you thought you had it covered — go check which two rules you’re missing.