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.

I composed this skill and have had pretty good luck with it. My grokbots use it when writing code.
- ub-mode compresses decades of craft discipline into a single Markdown file that an AI agent reads before every code change.
- Every human-readable rule is paired with a deterministic gate the agent cannot argue past, like a CRAP score under 10 or zero surviving mutants.
- The escape hatches are the most thoughtful part: they tell the agent when not to obey a metric literally, to avoid meaningless function splits and assertion-free tests.
- The repo ships no tests for its own rules and no evidence the skill changes agent output, which leaves the central question open.
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.
- Files in the repo: 2 (README.md and SKILL.md)
- Phases: 3 (Make it Work, Make it Right, Practice)
- External tools: 4 (crapper, dryer, mutator, uml-viewer)
- Build steps, dependencies, tests of its own: none
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 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.
| Tool | Metric | Threshold | Action |
|---|---|---|---|
| Crapper | Cyclomatic complexity plus coverage | CRAP under 10 | Refactor the function |
| Dryer | Structural duplication | 0.8 similarity or above | Eliminate the duplicate |
| Mutator | Mutation testing | Zero survivors | Strengthen the test |
| uml-viewer | Components and dependencies | Not a gate | Inspect 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 contributes | What it does not do | |
|---|---|---|
| ub-mode | A sequenced workflow an agent can follow, plus named gates | Enforce anything by itself; no CI, no hooks |
| poteto-mode / pstack | The larger rule set ub-mode is reduced from | Not superseded by ub-mode; no verified adoption comparison |
| Linters, coverage, mutation frameworks | Machine-checkable measurements | Do not tell an agent how to sequence a change or keep commits small |
| A full engineering platform | Turnkey enforcement | Not 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.
- Does an agent following ub-mode actually write different code than one that is not?
- Do the metric thresholds of 10 and 0.8 correspond to anything, or are they arbitrary?
- Does any model reliably respect an escape-hatch clause like "if an honest test is impractical"?
- Will the companion tools ship a license, tests, and a changelog?





