"Can we build it? Yes we can!" — the whole philosophy of this project in one line: no wasted materials, no demolition without a permit, always up to code, and the full blueprint gets built — not just the parts that feel simple.
Drop CLAUDE.md into the root of your project:
curl -O https://raw.githubusercontent.com/breim/bob-the-constructor-md/main/CLAUDE.mdOr with wget:
wget https://raw.githubusercontent.com/breim/bob-the-constructor-md/main/CLAUDE.mdA mirrored copy is kept as AGENTS.md for tools that read that convention instead (e.g. OpenAI Codex CLI, Cursor):
curl -O https://raw.githubusercontent.com/breim/bob-the-constructor-md/main/AGENTS.mdBoth files are kept in sync except for rule 9 (Claude CLI Available via Bash), which only applies to Claude Code and is dropped from AGENTS.md.
CLAUDE.md currently ships 10 rules:
- Think Before Coding (Check The Blueprint First) — surface assumptions and tradeoffs instead of guessing.
- Simplicity First (No Wasted Materials) — minimum code per feature, nothing speculative.
- Surgical Changes (No Demolition Without a Permit) — touch only what the task requires.
- Goal-Driven Execution — turn tasks into verifiable success criteria.
- Specs Are The Request (The Blueprint Is The Job) — a spec is a contract; every item gets built or explicitly flagged.
- Write in English — all code, comments, and docs, regardless of the language the user writes in.
- Avoid Code Comments — self-explanatory code over comments; only explain the non-obvious why.
- Commits — Conventional Commits, no
Co-Authored-Bytrailers. - Claude CLI Available via Bash — use it for scriptable, non-interactive sub-tasks. (
CLAUDE.mdonly — dropped fromAGENTS.md, since it's Claude-specific.) - Code Quality Metrics — keep complexity, module size, dependency direction, and test coverage on the healthy end.
This CLAUDE.md was based on the behavioral guidelines published by Andrej Karpathy's skill set, mirrored at:
The original is a great baseline for keeping coding agents disciplined: think before coding, keep edits surgical, avoid speculative work, and verify against explicit success criteria.
The original guidelines bias heavily toward "do less." That works well for small, focused tasks (one bug, one function, one refactor), but it broke down in a specific scenario:
When I passed a
.mdfile containing a multi-feature spec, the agent would silently drop features, treating them as "speculative" or "beyond what was asked" — even though the spec was the ask.
Rules like "No features beyond what was asked", "No 'flexibility' or 'configurability' that wasn't requested", and "Every changed line should trace directly to the user's request" were being applied to individual bullets inside the spec, instead of to the spec as a whole. The agent ended up using "Simplicity First" as justification to cut scope.
Compared to the original, this file has six more sections than the 4 it started with. The first three changes below are the original fix; the rest were added later as practical guardrails.
- Reworded "If you write 200 lines and it could be 50, rewrite it" → "Minimize code per feature, not feature count. If a single feature takes 200 lines and could be 50, rewrite it."
- Reason: the original phrasing let the agent reduce feature count under the banner of "simplicity."
- Added an explicit boundary at the end of the section:
"Simplicity First governs HOW you implement each requested item, never WHETHER to implement it. Cutting scope is not simplification."
This is the main fix. It establishes that any spec / requirements doc / feature list / .md describing what to build is a contract, not a suggestion. Specifically:
- Every feature, bullet, or numbered item in the spec must be implemented.
- Silent drops, deferrals, merges, or "phasing" of features are not allowed. If something seems unnecessary, the agent must surface it and ask before skipping.
- "Simplicity First" applies to the implementation of each item, not to which items get implemented.
- Ambiguity on an item triggers a question, not an omission.
Before declaring a multi-feature task done, the agent must enumerate every item from the spec and its status:
- [Feature 1] → done
- [Feature 2] → done
- [Feature 3] → partial — [what's missing and why]
- [Feature 4] → skipped — [reason, surfaced earlier]
This forces a re-read of the spec before closing the task — which is exactly the step the agent was skipping before. Informally: "Can we build it? Yes, all of it."
All written output — code, comments, docs, commit messages, PR descriptions — must be in English, regardless of the language the user writes in.
Codifies a clean-code bias: don't restate what the code does, only comment on the non-obvious why.
Conventional Commits format, imperative mood, no Co-Authored-By trailers.
Use the Claude CLI for scriptable, headless sub-tasks via non-interactive flags — never launch a blocking interactive session from a tool call.
Five proxies for maintainability: cyclomatic complexity, module size, dependency structure, test coverage, and a mutation-testing mindset.
Sourced from Martin Fowler's talk "How AI will change software engineering" — these five signals are adapted from how he frames code health there.
1. Think Before Coding(Check The Blueprint First) — surfacing assumptions and tradeoffs is still valuable.3. Surgical Changes(No Demolition Without a Permit) — stops drive-by refactors, very useful.4. Goal-Driven Execution— verifiable success criteria are still the north star.
The original philosophy is still intact. The changes are scoped to one failure mode: specs being treated as suggestions instead of contracts.
After the changes, when I pass a .md with N features, the agent:
- Treats the entire list as the request.
- Asks before skipping anything.
- Reports per-feature status before claiming the task is done.
If features still get cut after this, the agent has to do it explicitly — not silently under the cover of "simplicity."
Dedicated to my friend @weedo-dev — this project started a while back with him in mind.