ub-mode: Uncle Bob's 130-Line Rulebook for Coding Agents

A single Markdown file tells an AI when to stop, what to prove, and how to know a fix is real. The rules are familiar. The gates are the story.

9 min read • View on GitHub • More from unclebob

An editorial illustration of a heavy iron bookbinder's press on a workbench, compressing a tall stack of thick hardcover books into a single sheet of paper. A small mechanical hand lifts the sheet to the light while a chisel, calipers, and a loupe rest nearby. It depicts decades of craft philosophy squeezed into one page that a machine now reads.
The whole article in one image: a lifetime of craft argument compressed into a single page, held up by a machine.

I composed this skill and have had pretty good luck with it. My grokbots use it when writing code.

Robert C. Martin (Uncle Bob), Author of ub-mode · ub-mode | AI Primer
Key Takeaways

The Line That Does the Work

The sharpest sentence in ub-mode is not about architecture or naming. It is about honesty. "If the test would still pass when every function returned nothing, throw it out."

That single line is mutation testing stated as something a person can apply before any tool runs. Coverage counts whether a line executed. It does not count whether the test would notice if the line did nothing useful. An agent optimizing for a coverage number will call code without asserting anything, and that is exactly the failure mode this rule names. Anyone who has watched an AI generate a passing test suite that proves nothing recognizes the problem instantly.

A Rulebook, Not a Program

Here is what the thing actually is. ub-mode is one Markdown file. It carries YAML frontmatter with a name and a description, and it lives in an agent's skills directory. You invoke it with /ub-mode. There is no build step, no dependency, no CI, and nothing to compile. Installation is a file copy.

The content is a distilled descendant of poteto-mode and pstack. The README says it is "loosely based on portions of @poteto's rules, reduced." Robert C. Martin spent a career arguing for TDD, small functions, and clean boundaries. Here those arguments are addressed to a reader with no career and no ego.

That is the medium's point. This is a policy file, not a style guide. It carries almost no rationale, because an LLM does not need to be persuaded. It needs to be told.

A WSJ hedcut-style editorial portrait of Robert C. Martin (Uncle Bob), rendered in black ink on a pure white background. It accompanies his attributed statement about composing the ub-mode skill for his own coding bots.

Work First, Right Second

Every change runs through the same three phases in order. First Make it Work: write the failing test first, make the smallest edit, model the domain. Then Make it Right: refactor, and test behavior rather than implementation. Then Practice: keep a log, commit in small ordered steps, guard the context window.

The sequence is the design. You do not clean up code you have not proven works, and you do not prove behavior on code you are still restructuring. The document is prose written as control flow, and the ordering is the thing to watch move.

The three phases as control flow: a change moves right through the gates, loops back when a gate fails, and halts entirely when two fixes sharing one premise fail the same gate.

The Gates

Phase 2 is where the skill stops trusting the agent's judgment. Three named tools turn the rules into numbers a machine can check.

Crapper combines cyclomatic complexity with coverage into a CRAP score, and the rule is to keep it under 10. Dryer flags duplication at 0.8 similarity or above. Mutator runs mutation testing and treats any surviving mutant as a failure. The pairing is the pattern: a human-readable rule plus a deterministic gate means the agent cannot satisfy the rule by adding a branch without a test, or a test that never exercises the branch. It has to produce evidence a tool can verify.

A close-up editorial illustration of a stamped metal part clamped on an inspection bench. The part is hollow, its interior mechanism missing and rendered as clean white where the working parts should be. A green inspection tag hangs from it and a dial gauge beside it reads PASS, while a single gloved hand holds a caliper to the empty cavity. It depicts the mutation-testing honesty check made physical: a hollow part that still passes inspection.
A hollow part that still passes inspection is exactly a test that passes when every function returns nothing. The gate exists to catch this.
ToolMetricThresholdAction
CrapperCyclomatic complexity plus coverageCRAP under 10Refactor the function
DryerStructural duplication0.8 similarity or aboveEliminate the duplicate
MutatorMutation testingZero survivorsStrengthen the test
uml-viewerComponents and dependenciesNot a gateInspect the architecture

The Escape Hatches

Then the document does something a naive rule set would not. It tells the agent when to ignore the metric. "If an honest test is impractical, do not write a bad one." "Consider whether case statements are worth reducing." "If the code is already clear and local, leave it."

These lines exist because a hard threshold invites pathological compliance. "Keep CRAP under 10" can be satisfied by splitting a function into meaningless fragments. "Raise coverage" can be satisfied with assertion-free tests. The escape hatches push the agent back toward the intent behind the number.

They also reintroduce judgment. A rule with an "if it is impractical" clause is only as reliable as the model interpreting it, and the repo offers no evidence the model respects it. That is the honest cost of trying to encode taste instead of just encoding a number.

Reduced From Something Larger

The README is explicit that ub-mode is a reduction. What survives a squeeze to fit a context window says what the author thinks matters most: the ordering, the root-cause rule, the behavior test, and the gates. Everything else was cut.

What it contributesWhat it does not do
ub-modeA sequenced workflow an agent can follow, plus named gatesEnforce anything by itself; no CI, no hooks
poteto-mode / pstackThe larger rule set ub-mode is reduced fromNot superseded by ub-mode; no verified adoption comparison
Linters, coverage, mutation frameworksMachine-checkable measurementsDo not tell an agent how to sequence a change or keep commits small
A full engineering platformTurnkey enforcementNot what this repo is; it ships a SKILL.md, not executables

What the Rules Do Not Prove

There are no tests for the rules themselves. No changelog. No examples of the skill in action. No license in the available metadata, which is a real adoption constraint for anyone who wants to copy or redistribute it.

The central question is whether the skill measurably changes agent output. The repo does not say, and neither should this article pretend otherwise. A 130-line policy file is a hypothesis about how to make an agent behave. It is not evidence that the hypothesis holds.