I Built a Monster CLAUDE.md
One markdown file, dropped at a repo root, turned a confidently-wrong coding agent into one that shipped a quantization method beating a peer-reviewed algorithm — over a single weekend. The secret isn't a smarter model. It's a document that redesigns the agent's constraints and environment: Karpathy's coding rules layered on top of harness engineering.
1. The Failure Mode
Agents don't fail loudly. They pick an interpretation, barrel ahead silently, over-engineer, and quietly “improve” code you never asked them to touch.
2. Karpathy's Rules
A short constraint document that interrupts the agent's default behaviour — think first, stay simple, cut surgically, verify explicitly.
3. Harness Engineering
The scaffolding, constraints, and feedback loops around the agent. The CLAUDE.md is one component; skills, MCP, linters, and GC are the rest.
4. The Payoff
With the environment engineered, the same model became “scary good” — shipping research-grade code fast and with remarkably few bugs.
The one insight to keep
The bottleneck in agent performance is usually not model intelligence — it's environment design. You don't get a better agent by prompting harder; you get one by engineering the constraints and feedback it operates inside.
Why Agents Get It Confidently Wrong
A raw coding agent produces code that looks authoritative and is subtly broken. Karpathy's diagnosis is that the model manages neither its own confusion nor yours: it makes wrong assumptions on your behalf and keeps going without checking. Left unconstrained, three failure modes dominate — and prompt compliance itself degrades as instruction files grow past roughly 200 lines, so the answer is engineering the constraints, not writing longer ones.
Silent Assumptions
Faced with ambiguity, the model quietly picks one interpretation and executes it — never surfacing the fork — so it solves the wrong problem beautifully.
Over-Engineering
It adds error handling for impossible cases, invents abstractions for single-use code, and layers in configurable options nobody requested.
Orthogonal Damage
While doing the task, it “improves” adjacent code — reformatting, renaming, refactoring unbroken components — drift that's individually harmless but collectively untraceable.
Karpathy's Rules: The Constraint Layer
The backbone of the monster CLAUDE.md is Karpathy's now-viral rule set — a document that reads like a code-review checklist and works by interrupting the model's defaults before it acts. Four core rules cut measured error rates from 41% to 11%; a self-verification protocol and further additions push it lower still.
Think Before Coding
Silent, wrong interpretations executed without surfacing the ambiguity.
Forces the fork into the open — the model presents interpretations instead of gambling on one.
Simplicity First
Speculative features, bloated abstractions, single-use code turned into utility modules.
The simplest solution that works is defined as the correct one — removing the model's licence to gold-plate.
Surgical Changes
Scope creep, opportunistic refactors, and style drift in code that was already fine.
Makes the diff auditable — every line has a reason, so reviewers can trust it.
Goal-Driven Execution
“Clean up this component”-style drift and endless clarification loops.
Give it a target (“pass these 3 tests, keep the props interface”) and let it loop toward it autonomously.
Explicit Verification & Self-Check
The three-steps-perfect-then-hallucinate pattern where later work goes unchecked.
The rule set grew from 4 to a ten-rule self-check protocol precisely so the agent closes its own loop; added rules target silent assumptions, over-engineering, and orthogonal damage to cut the residual error further.
The Anatomy of the File
Every part earns its place. Stripped to its skeleton, the constraint layer of the CLAUDE.md looks like this — short, imperative, and structured so the model can't miss it:
Representative structure synthesised from the rule set — the point is the shape: terse, numbered, enforceable, and readable in one pass.
Harness Engineering: The Environment Layer
Rules alone aren't the whole story. The monster CLAUDE.md is one piece of a larger discipline — harness engineering: the full environment of scaffolding, constraints, and feedback loops that surrounds an agent so it can work autonomously and stay on the rails. Your job shifts from writing code to designing the environment, specifying intent, and building the feedback loops.
Three Nested Layers
| Layer | The question it answers | What you actually design |
|---|---|---|
| Prompt | “What should be asked?” | The instruction text sent to the model for a single turn. |
| Context | “What should be shown?” | Every token visible while the model reasons — files, history, tool output. |
| Harness | “How should the whole environment be designed?” | Constraints, feedback loops, and operational systems the agent runs inside. |
Components of a Real Harness
Context Files (CLAUDE.md / AGENTS.md)
The system of record for rules and architectural decisions. A navigational map, not an encyclopedia — organised by directory proximity so it doesn't waste the context window.
MCP Servers
Selective access to external tools and data — issue trackers, browsers, docs — connected only where they earn their token cost.
Skill Files (SKILL.md)
Task-triggered playbooks for recurring work — reviews, deployments, framework patterns — that load only when their description matches. Complementary to CLAUDE.md, which is always on.
Mechanical Enforcement
Custom linters and structural tests that enforce the rules at system level. Their error messages inject the correction straight back into the agent's context — the rule bites even if the model forgot it.
Automated Code Garbage Collection
Background agents that continuously scan for divergence and open refactoring PRs on their own — countering technical debt as the codebase scales.
The Payoff: When the Harness Beats the Model
The headline result: with this environment in place, the agent shipped a quantization method that beats QuaRot — a published, peer-reviewed algorithm — at the bit-widths that actually matter. It took a weekend, not a month, and shipped with remarkably few bugs. And it's not a one-off: across 2026 the same lesson — environment design outperforms raw model swaps — shows up again and again.
| Experiment | What changed | Result |
|---|---|---|
| The monster CLAUDE.md | Rules + harness around an unchanged model | Beat QuaRot in a weekend, few bugs |
| OpenAI Codex | Harness-driven autonomous generation | 1M lines with zero manual code, ~10× faster |
| Hashline | Changed the edit format alone | Performance jumped from 6.7% → 68.3% across models |
| LangChain | Harness improvements, same models | Benchmark rank moved from 30th → 5th |
What to Actually Take Away
Engineer constraints, don't just prompt
A constraint document that interrupts defaults beats a longer, more polite prompt — especially past ~200 lines where compliance decays.
Keep CLAUDE.md a map, not a manual
Terse, numbered, enforceable rules organised by directory proximity. Push deep task knowledge into on-demand SKILL.md files.
Close the loop mechanically
Linters, tests, and self-check rules that feed failures back into context enforce behaviour the prose can only request.
The model is rarely the ceiling
Before reaching for a bigger model, redesign the environment. That's where most of the gain — and the “scary good” feeling — actually lives.