Blue Octopus AI Hygiene: A Drop-in CLAUDE.md for Anyone Letting an Agent Touch Their Code

In April, a single file hit number one on GitHub trending. Not a framework. Not a model. Not a startup. A CLAUDE.md — one markdown file, 60 lines, four rules. As of this morning it has 126,585 stars and 12,871 forks.

The author distilled the file from public observations Andrej Karpathy had been making about how AI coding assistants fail. Karpathy was the founding director of OpenAI, the head of AI at Tesla, and the guy who taught a generation of researchers how transformers actually work. When he says LLMs make the same four mistakes over and over, people listen.

The four mistakes, in his words: they "make wrong assumptions on your behalf and just run along with them," they "really like to overcomplicate code and APIs, bloat abstractions," they "still sometimes change/remove comments and code they don't sufficiently understand as side effects," and they pursue tasks without verifiable success criteria.

The file that hit #1 turned those observations into four rules: Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution. Drop the file at the root of your project and Claude (or Codex, or Cursor, or any agent that reads CLAUDE.md) reads it before doing any work. The behavior changes immediately — fewer rewrites, fewer scope creeps, fewer "I assumed you wanted X" surprises.

We've been running this internally on every project since the file appeared. We added two more rules from our own production scars. The result is what we now drop on every Blue Octopus client engagement and what ships on every demo box we deliver.

Free download below. No email gate. Steal it.

Why six rules and not four

Karpathy's four catch the universal LLM coding mistakes. They're load-bearing. We didn't change them.

But we kept hitting two failure modes that the original four didn't catch.

The first one is documentation. Chamath Palihapitiya posted this in late April and it stuck with us:

"The missing layer in successful software development usually isn't writing code faster but, rather, documenting the reasoning and shared context behind the decisions you made so everyone (including agents) can follow along. Oftentimes, architectural choices live in slack."

If your tribal knowledge — we tried that approach in Q2 and it broke under load, we settled on this database because of a constraint nobody documented, the reason we use this weird pattern is because of a vendor bug from 2022 — lives in a Slack channel, the AI agent can't see it. So when it touches the relevant code, it re-proposes the rejected approach. You correct it. Six months later, a different agent does the same thing. You correct it again.

The fix: move the why into the repo. Not as comments restating what the code does (the code already tells you that). As one-line notes when the why is non-obvious — a hidden constraint, a workaround, a behavior that would surprise a reader. Or in a long-lived strategy doc, an ADR, a decisions/ directory. Anywhere that travels with the code.

That's Rule 5: Document the Why, Not the What.

The second one is verification. We had a bug in our own ADS-B tracking software a few weeks ago. Shipped a release with WebSocket broadcasts to live-update the dashboard. All tests passed. Handshake tests confirmed the connection. Deployed to production.

The dashboard was dark. The WebSocket connected fine, sent the first frame, and stalled. The handshake tests never waited for frame N+1. The unit tests never crossed two tick boundaries. CI was green. Production was broken.

Twenty seconds of opening the dashboard and watching a frame come through would have caught it. We hadn't done that step. We trusted the tests.

That's Rule 6: Verify End-to-End, Not Just Unit-Tested. Tests are necessary, not sufficient. Before claiming "done," prove the feature works on the actual surface the user will touch — open the browser, hit the API, watch the job run. Type checking and unit tests verify code correctness. They don't verify feature correctness.

The drop-in

Copy everything between the fences into a CLAUDE.md at the root of your project. That's it. The next agent that opens the project reads it before doing any work.

# CLAUDE.md

Behavioral guidelines for AI agents (Claude Code, Codex, Cursor, etc.) working in this repo.
Six rules, biased toward caution over speed. Override per-task as needed.

## 1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

- State assumptions explicitly. If uncertain, ask.
- Multiple interpretations exist? Present them. Don't pick silently.
- Simpler approach exists? Say so. Push back when warranted.
- Confused? Stop. Name what's unclear. Ask.

## 2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- 200 lines that could be 50? Rewrite.

Test: would a senior engineer call this overcomplicated? If yes, simplify.

## 3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- Notice unrelated dead code? Mention it. Don't delete it.

When your changes create orphans:
- Remove imports/variables/functions YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.

Test: every changed line should trace directly to the user's request.

## 4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass."
- "Fix the bug" → "Write a test that reproduces it, then make it pass."
- "Refactor X" → "Ensure tests pass before and after."

For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]

Strong success criteria let the agent loop independently. Weak criteria ("make it work") require constant clarification.

## 5. Document the Why, Not the What

Comments and docs explain decisions, not behavior. Well-named code already tells you what it does.

- Don't write comments that restate what the code obviously does.
- Don't write multi-paragraph docstrings unless asked.
- DO write a one-line comment when the WHY is non-obvious — a hidden constraint, a workaround, a behavior that would surprise a reader.
- Don't reference the current task, fix, or callers ("used by X", "added for the Y flow") — those belong in the PR description and rot as the codebase evolves.
- When you make an architectural decision, write it down somewhere durable (an ADR file, a `decisions/` directory, a long-lived strategy doc) — not in a comment that the next agent will lose context for.

The reason: AI agents work without your meeting context. Tribal knowledge needs to live in the repo, or the agent will re-propose the same broken approach in a year.

## 6. Verify End-to-End, Not Just Unit-Tested

Tests are necessary, not sufficient. Before claiming "done," prove the feature works on the actual surface a user will touch.

- For UI changes: open the browser, click the thing, see the result. Take a screenshot.
- For API changes: hit the endpoint with curl, see the response.
- For background jobs: trigger the job, watch it run end-to-end.
- For data pipeline changes: run a real frame, watch the data flow.

Type checking and unit tests verify code correctness, not feature correctness. If you can't test the actual surface, say so explicitly rather than claiming success.

The reason: agents tend to mark work "done" when their last test passed. Real users hit code paths tests don't cover. The 30 seconds it takes to verify end-to-end catches the dark-deployment class of bugs that pass CI and break in production.

How you know it's working

Three things shift in your AI-coded diffs:

Diffs get smaller. Lines that don't trace to the request stop appearing. The agent stops "improving" adjacent code it shouldn't touch.

Rewrites for overcomplication go down. The agent ships 50 lines instead of 200, then asks if you want the additional surface area before adding it.

Clarifying questions arrive before implementation, not after. This is the one that's hardest to measure but most valuable. Instead of building the wrong thing then asking "did you want X or Y?", the agent asks before writing code.

The cost: the agent feels slightly slower because it's pausing to ask instead of charging ahead. The benefit: you stop having the conversation where you say "no, that's not what I asked for, please rewrite it" three times in a row.

Where to put it

Three places, in order of impact:

1. At the root of every project an AI agent will touch. That's the literal use case. Drop the CLAUDE.md block above as CLAUDE.md in the repo root. Done.

2. Layered with project-specific context. If your project already has a CLAUDE.md, these six rules go underneath the project-specific instructions — they're the universal layer. Project context says "this repo is a Next.js storefront, the database is Postgres, here's how the build works." Hygiene rules say "and don't break Karpathy's four laws + our two."

3. On a fresh demo box for a client. When we ship our ZGX Nano on-prem AI demo platform to a client, the box arrives with this CLAUDE.md already in place. They walk up to the box, ask it to do something, and the agent reads the hygiene rules before touching anything.

The honest part

These six rules don't make AI agents safe to ship code unsupervised. They reduce the rate of common mistakes. They don't eliminate them.

You still need a human to read the diff. You still need tests. You still need the verification step the rules call for. The rules just bias the agent toward producing diffs that are easier to read, smaller in scope, and more likely to do what you actually asked.

If you're using an AI agent to write code and you're not doing this, you're paying full freight for the bad behaviors the rules counteract. Drop the file in. Watch the next diff. See the difference.

Attribution

The first four rules are forked from forrestchang/andrej-karpathy-skills — the #1 trending repo we mentioned. That repo distills Karpathy's public observations on LLM coding pitfalls. Rules 5 and 6 are original Blue Octopus contributions based on production work we've shipped.

The full strategy doc — including the mapping from each rule to our internal feedback memory system, plus how we ship it across every Blue Octopus engagement — is published in our intelligence-hub repo under CC BY 4.0. Copy it. Modify it. Ship it. Attribution appreciated, not required.

---

Related reading:

• Why Your AI Agent's Biggest Problem Isn't the Model — It's the Context — the architectural complement to these behavioral rules
• The Agent Complexity Trap: Why Your Business Needs Level 2, Not Level 5 — what to not let your AI agent do, even with good hygiene rules
• A Working Approach to AI Memory — how the feedback rules referenced in Rules 5 and 6 actually work