Uncle Bob's ub-mode: Clean Code, Now an Agent Skill with Machine-Enforced Gates

Robert "Uncle Bob" Martin — the author of Agile Software Development, Clean Code, and the originator of the SOLID principles — has been posting about AI coding agents in 2026, and this week he shipped something concrete: ub-mode, a 4KB agent skill that encodes his engineering discipline into the agent itself, paired with a suite of deterministic quality-gate tools he built to make the rules enforceable by the machine rather than merely recited by it. "I composed this skill and have had pretty good luck with it. My grokbots use it when writing code," he wrote on October 25. The post pulled ~140K views — and the reason it's worth a full research pass is that it's the clearest public example yet of a specific bet: that the quality of agent-written code is determined less by the model and more by the written discipline the agent follows, and that discipline must be backed by deterministic gates or it degrades under load. This post breaks down the full skill, the four companion tools, the lineage it grows from (poteto's pstack), and what the design choices say about where "clean code" goes when the author is an agent.

What ub-mode Is

Structurally, ub-mode is small and deliberately so: a single SKILL.md (about 4KB, ~150 lines) that installs into any skill-capable agent — the README gives ~/.grok/skills/ub-mode/, ~/.claude/skills/ub-mode/, and ~/.cursor/skills/ub-mode/ as examples — invoked with /ub-mode. Its contract is one sentence: "Every time you are asked to make a change, follow: First Make it Work. Then Make it Right. Follow Practice."

That structure is the first thing to notice. The triad is not new — it's Kent Beck's classic TDD cycle, "make it work, make it right, make it fast," which Bob himself has taught for a decade (his 2014 "Cycles of TDD" post and the Clean Code TDD episodes both carry it). What ub-mode does is swap the third leg: "make it fast" is replaced with "Follow Practice" — keep a log of every action and its reason, guard the context window, clean the worktree, commit often in small ordered commits. For a human developer, "make it fast" was about performance. For an agent, the scarce resources are different — context, tokens, review surface — so the third leg becomes the agent's operating discipline rather than a performance optimization. It's a quiet but telling rewrite of a 20-year-old mantra for a new author.

The skill is also explicitly a reduction of an existing system. The README says it is "loosely based on portions of @poteto's rules (poteto-mode / pstack), reduced and paired with deterministic quality-gate tools." That line matters for understanding what happened in the ecosystem: a large, elaborate skill ecosystem for agent engineering already exists — pstack (maintained by backnotprop, installed via npx skills add backnotprop/pstack) carries a dozen-plus skills: tdd, interrogate, reflect, show-me-your-work, figure-it-out, automate-me, arena, swarm, architect, blast-radius, statechart, unslop, and more, with poteto-mode acting as an orchestrator that reads the principles index before any work and opens a principle's full skill whenever one applies. Bob took that world, reduced it to one file he trusts, and — the key move — attached deterministic tools to the judgment rules. Where pstack is a library of principles and workflows, ub-mode is a discipline with a quality gate at the end of it.

Leg 1 — First Make it Work

Seven sections, each compressing a body of Bob's teaching into a few imperatives. The ones worth quoting, because they read less like "coding style" and more like a decision procedure:

• Laziness Protocol. "One decision lives in one place. Ship the smallest edit that solves the problem." This is Bob's "laziness, impatience, hubris" developer-triangle idea pointed at agents: the smallest correct change is the one an agent can verify most cheaply.
• Foundational Thinking. "Get the data shape right before you write the logic." "If a concurrent writer would matter, do not share state." Data modeling before logic is the highest-leverage senior move in most codebases; stating it as an agent instruction is stating that data-shape design is the step agents are most likely to skip.
• TDD, with the honesty clause. Write the failing test first, see it fail for the reason you expect, make the smallest change that passes. And: "If an honest test is impractical, do not write a bad one." That last line is doing enormous work — it's the explicit refusal to let the agent satisfy the ritual (a test exists) while failing the intent (a test proves something).
• Redesign From First Principles. "Do not bolt a new requirement onto the old design. Ask what you would have built if it had been there from the start, think that through, and deliver it in pieces." This is the anti-aggregation rule: agents naturally accrete, because adding is cheaper than restructuring in a single pass; the skill forces the re-derivation.
• Attack the Premise. The most distinctive section. "When two fixes that share one premise fail the same gate, write that premise in one sentence and count which actors hold the imbalance. Remove the assignment. Do not start another fix until you have done that." This is Bob's famous debugging move — stop fixing symptoms and interrogate the shared assumption — turned into a hard gate: no third fix attempt without a written premise and a named reassignment of responsibility. For agents, who loop on the same failing patch with eerie persistence (the Claude Code team literally observed a PR cycling 50 times between agent-author and agent-reviewer), this is a convergence breaker written into the workflow.
• Subtract Before You Add. "Take complexity out before you add anything." The default agent behavior is additive — more code, more files, more abstraction. The skill inverts the order of operations.
• Build the Lever. "If the work is not obvious at a glance, build the tool that does it. Do one unit by hand, then make the tool match that unit." The automate-a-second-time rule, framed for agents that can write the tool themselves.

Then the architecture section, which is where the skill gets closest to a verifiable checklist: model the domain so illegal states are unrepresentable and maintain a glossary of domain terms; boundary discipline — check data where it enters, trust it inside, keep business logic in pure functions; type-system discipline — make illegal values un-writable, parse outside data once at the boundary, do not silence the compiler; idempotence — running twice, or after a crash halfway, ends in the same state; and separate before serializing shared state — if components don't need the same mutable thing, give each its own; if they do, enforce one writer in the structure. Every item is a property a machine can in principle check — which is exactly the point of the companion tools.

Leg 2 — Then Make it Right: Where the Gates Live

This leg is where ub-mode stops being "principles in prose" and becomes a pipeline. The prose rules (fix root causes — "a guard that only hides the crash is not a fix"; sequence work into verifiable units; test behavior, not implementation — "if the test would still pass when every function returned nothing, throw it out"; refactor by pinning behavior, changing structure, proving behavior didn't change) are familiar from a decade of Bob's teaching. The four tool invocations are new, and they're the architectural core of the whole project:

The CRAP score is the metric worth understanding, because it's the gate the whole skill turns on. CRAP (Change Risk Anti-Patterns) is a per-function risk score that originated around Michael Feathers' Working Effectively with Legacy Code work and was formalized by Bob Evans' crap4j. The formula Bob's crapper actually runs — the one shared with crap4clj, crap4java, and crap4go — is CRAP = c² × (1 − p)³ + c, where c is cyclomatic complexity and p is the fraction of the function's paths covered by tests. The uncovered penalty scales with the square of complexity: a function with complexity 10 and no tests scores 110, while the same function fully tested scores 10. That's not a coincidence — the metric encodes the insight that complexity is tolerable when it's exercised by tests, and dangerous when it isn't. (Crapper's own risk bands: 1–5 low, 5–30 worth a look, 30+ complex and under-tested; its built-in --threshold defaults to 30.) Note that ub-mode's skill rule is stricter than the tool's default — it pushes every function to CRAP < 10, which means every function must be both simple and tested in a specific, measurable way. Complexity alone and coverage alone are both gameable; their product is much harder to game.

Mutation testing (the mutator) is the deepest gate. Coverage says "this line ran." Mutation testing says "does a test actually notice if this line breaks?" — it injects small faults (flip a comparison, drop a return, change a constant) and asks whether the test suite kills them. Surviving mutants are the precise location where a test suite is theater: lines covered, behavior unasserted. For agent-written code — where the failure mode is precisely "plausible tests that assert nothing" (agents are fluent in the grammar of tests, not their semantics) — mutation testing is the one metric that can't be flattered by fluency. Bob's instruction sequence is exacting: "Cover the uncovered. Kill the survivors. Delete dead code."

Read together, the four tools turn the prose principles into a falsifiable regime: CRAP gates function shape and test adequacy, dryer gates structure, mutator gates test meaning, and uml-viewer makes the dependency architecture visible for the boundary-discipline and architecture rules. The skill's judgment rules tell the agent what to aim for; the tools tell it whether it got there without asking anyone's opinion.

Leg 3 — Follow Practice: The Agent-Native Rules

The final leg is the shortest and the most original, because all four rules are about the agent as a process, not the code as a product:

• Keep a Log. "Keep a log of every action you take and the reason you took it. Report that log upon completion." This converts the agent's decision history into a reviewable artifact — the log is what a human reviewer actually reads instead of 3,000 lines of diff. It's also the seed of the self-evaluation loop: a log of actions-plus-reasons is an audit trail the reviewer (human or agent) can grade against the principles above.
• Guard the Context Window. "Keep the main thread small. Send the bulk elsewhere, and keep the summary." This is the agent-specific version of "don't let the working set grow unbounded" — delegate the heavy lifting to subagents, keep only summaries in the main context. It's the same discipline as subagent architecture in Claude Code and OpenClaw-style systems, stated as a personal practice rule.
• Worktree Cleanup. Find what's safe to remove, confirm nothing in use needs it, reclaim disk; uncommitted work waits for a decision. Agents that spawn worktrees (the standard pattern for parallel agent work) accumulate them; this is the hygiene rule that keeps the machine usable.
• Commit and Push. "Commit often, in small ordered commits. Each commit says why, what changed, and how you proved it. Push to the main line at the end." The "how you proved it" clause is the one that makes commits verification artifacts — each commit is a claim with its evidence, which is exactly the shape the Claude Code team's review pipeline expects.

Why This Is the Right Shape for Agent Engineering

Set the individual rules aside and ub-mode is a design document for a recurring problem: how do you make a probabilistic system follow a disciplined process? The answer it encodes has four parts, and each one is a response to a documented failure mode of agent coding:

1. Principles must be procedural or they don't survive generation

LLMs can recite "write clean code" and then produce a 400-line god function. The skill's rules are written as decision procedures with checkable outcomes — "see it fail for the reason you expect," "if the test would still pass when every function returned nothing, throw it out," "do not start another fix until you have done that." Imperatives tied to observable evidence are what models can actually comply with; adjectives are what models paraphrase away. The reduction from pstack's sprawling principle library to one 4KB file is itself a claim: the smaller the surface, the higher the compliance rate.

2. Deterministic gates are what make prose enforceable

This is the move that distinguishes ub-mode from every "AI coding rules" blog post. A principle without a gate is a suggestion an agent may ignore under context pressure; a principle with a gate (CRAP < 10, duplication < 0.8, mutants killed) is a test the agent has to pass. The tools are also the reviewer's job description: instead of a human auditing whether "the code is clean," a human audits whether the gates passed and whether the log's reasons were honest. That's the same architecture as the Claude Code review post — small trusted machinery, auditable outputs, human attention reserved for judgment — applied to the author side instead of the review side. Bob's tools are, in effect, pre-PR verification as a personal package.

3. The convergence breaker is a debugging strategy

"Attack the Premise" is the most agent-specific rule in the file, and the most valuable. The documented failure mode of agent debug loops is the agent re-patching the same symptom with variations until it gives up or burns the budget — the 50-cycle PR in the Claude Code post is the extreme case. ub-mode's rule — when two fixes sharing a premise fail the same gate, stop, write the premise, remove the assignment, no further fix attempts until then — is a hard circuit breaker that forces a phase change from patching to re-derivation. It treats the shared assumption, not the code, as the unit of debugging. That's senior-debugging practice, encoded where an agent will actually read it.

4. The log converts the agent's work into a reviewable object

Every action, with its reason, reported at completion. This is the piece most skill files skip, and it's the one that makes the whole thing work in a team: the reviewer's job stops being "read the diff" and becomes "check the log's claims against the gate results." It also sets up the self-improvement loop — a corpus of (action, reason, outcome) triples is exactly the material an eval can score, which is how the Claude Code team builds their incident-collection benchmark. Bob, who wrote the book on making the implicit explicit, is making the agent's reasoning explicit by default.

The Honest Limits

• It's four commits old. The repo was created October 25, 2026 — the day of the X post — with four commits. "Pretty good luck" is n = Bob's own grokbots on his own workloads. No benchmarks, no third-party evaluations, no public dataset of gate pass rates. The companion tools (crapper, dryer, mutator, uml-viewer) are similarly young, and each one has to actually work across languages at the claimed thresholds before the gates are more than aspirational.
• The reduction is lossy by design. ub-mode is "loosely based on" pstack, reduced. What's dropped (interrogation workflows, architecture arenas, statechart formalism, the principle-library's depth) is also where pstack's power lives for certain kinds of work. A one-file skill is more compliant; it's also a narrower instrument. The right read: ub-mode is a discipline, pstack is an arsenal, and most teams will want the discipline always on and the arsenal for the hard tasks.
• Gates measure proxies. CRAP < 10 and mutation survival are excellent proxies, but they're still proxies — a function can pass every gate and still implement the wrong behavior, because none of the four tools checks that the spec is right. (This is the same spec-vs-reality gap Anthropic's formal-verification post names, at a much smaller scale.) The log helps — it's where the "is this the right thing" reasoning lives — but the log is prose, and prose is gameable.
• Follow-the-process rules assume a long task. The triad, the logging, the commit discipline — these pay off on multi-step work. For a one-line fix, the overhead of the full cycle is real; the skill's own Laziness Protocol ("ship the smallest edit") is in tension with its own ceremony, and in practice the agent has to judge which register it's in. Bob's "pretty good luck" phrasing suggests he's felt that friction too.

Bottom Line

Uncle Bob Martin is, of course, capable of writing a rules file. The interesting fact isn't the writing — it's the package. For the first time, the clean-code canon has shipped as an installable agent skill with its own deterministic quality gates: a 4KB SKILL.md that turns three decades of craft teaching into decision procedures with observable outcomes, four companion tools (CRAP < 10, duplication < 0.8, mutant-kill-or-die, dependency visualization) that make the rules falsifiable instead of ornamental, and a third leg — "Follow Practice" — that rewrites the classic TDD triad for the agent's actual scarce resources: context, tokens, and reviewable evidence. The design is a compact answer to the question that eats agent-engineering teams alive: how do you get a probabilistic system to hold a standard when the standard is "good engineering"? Write it as procedures, gate it with machines, log the reasoning, and review the log instead of the diff. It's four commits old and "pretty good luck" is a small sample, but the architecture — discipline as config, quality as gates, reasoning as an auditable artifact — is the same shape the Claude Code review post showed working at the other end of the pipeline. Bob's clean code was always about making the invisible legible. ub-mode makes the agent's invisible legible, and it makes the legible checkable. That's not a meme. That's a method — and it installs with one copy-paste.

References

• Uncle Bob Martin — X post announcing ub-mode (Oct 25, 2026) [x.com]
• unclebob/ub-mode — SKILL.md (full text) and README [GitHub]
• unclebob/crapper — CRAP scores for Clojure, Java, Go, TypeScript, Rust, and Python (formula: CRAP = c² × (1 − coverage)³ + c) [GitHub]
• unclebob/dryer — structural duplication detection [GitHub]
• unclebob/mutator — mutation testing for agents [GitHub]
• unclebob/uml-viewer — components, coverage, CRAP, mutation, dependency visualization [GitHub]
• backnotprop/pstack — the poteto-mode principle library ub-mode reduces from [GitHub]
• Flavio Copes — What is poteto-mode in pstack? [flaviocopes.com]
• Uncle Bob — The Cycles of TDD (make it work, make it right, make it fast) [blog.cleancoder.com]
• CRAP metric background (Evans & Feathers; Crap4j FAQ) [crap4j.org]

Skill text, thresholds (CRAP < 10, duplication ≥ 0.8, mutation-kill), installation targets, the CRAP formula (CRAP = c² × (1 − coverage)³ + c), and the pstack lineage verified against the ub-mode repository (SKILL.md + README, 4 commits, created Oct 25, 2026) and the crapper repository README as of October 27, 2026. Bob's "pretty good luck" is self-reported experience with his own grokbots; the project is two days old at publication with no third-party evaluations.