Anyone Can Write Good Code: Breaking Down and Testing Uncle Bob’s Clean Code ub-mode for AI Agents

If we turn back the clock over twenty years to the period when object-oriented programming and modern software architecture were rapidly evolving, software engineering scholar Robert C. Martin (commonly known as Uncle Bob) was one of the leading figures in the industry. As early as 2001, he was one of the core authors of the Agile Manifesto; he later systematized and popularized the SOLID principles and published his classic book Clean Code in 2008. For years, his standards for identifying code smells and his engineering practices have been an important benchmark for code quality in software development.

I still remember sitting at my own desk back in the day, carefully reading Uncle Bob’s Clean Code page by page. When I saw that on October 26, 2026 (00:04 Beijing time) he publicly released a new project called ub-mode on GitHub, I pulled the yellowed old copy off my bookshelf — the inside pages still bearing the notes I had underlined word by word. As of October 27, the repository had gained over 1,200 stars in less than two days.

Nearly twenty years later, this veteran software engineer of over five decades has released ub-mode, whose core still carries forward the engineering philosophy he advocated in the book: first make it work, then make it right. The difference is that these guidelines are no longer aimed at human engineers — they have been transformed into constraint rules for AI coding agents. The entire project builds a complete three-tier governance structure: first, establishing data models and TDD constraints during the feature implementation phase to prevent state chaos; next, introducing three command-line tools during refactoring to create quantitative quality gates; and finally, enforcing rigorous engineering habits for the agent in the workspace.

Against the backdrop of today’s popular Vibe Coding — relying on natural-language prompts to have large models generate code, and not digging into internal structure as long as the features run — this software engineering scholar offers a very different approach. ub-mode references and refines some of the rules from developer @poteto’s poteto-mode / pstack. The entire repository consists of just two files, centered on a 152-line SKILL.md file; per the README.md instructions, you simply place it in the skills directory of Claude Code, Codex, or Grok, and invoke it via /ub-mode.

Its distinguishing feature is that it not only specifies, in imperative form, the thinking order and architectural boundaries the AI should follow when modifying code, but SKILL.md also requires the large model to run three cross-language (supporting Clojure, Java, Go, TypeScript/JS, Rust, Python) command-line tools (crapper, dryer, mutator) before delivering code, producing evidence from three categories of checks: cyclomatic complexity, structural duplication, and mutation testing. README.md additionally recommends a visualization tool for architecture and metrics called uml-viewer.

Although I’ve been away from hands-on coding for a few years, I remain very interested in understanding Uncle Bob’s Clean Code rules for various agents. In today’s era of “everyone can build products,” large models have made “anyone can generate code” a reality. But when actually building products, code that runs is not the same as code that meets quality standards. As features keep accumulating, code often becomes structurally chaotic and prone to regression bugs. In the era of large models, the key to “anyone can write good code” lies in establishing clear engineering rules and verification mechanisms for AI. With the help of multiple agent tools, this article cross-references the documentation and source code of ub-mode and its four companion repositories — not only fully breaking down the engineering rules, checking principles, and implementation boundaries set for agents in the Skill, but also testing this toolchain step by step on a real open-source project, recording specific performance and improving the open-source project’s code based on the results.

If you are a professional programmer — whether writing code for your company’s production systems or delivering code to clients as a one-person company (OPC) — I recommend reading the detailed Skill breakdown carefully. If you are not a professional programmer but are delivering products for yourself or a small audience, I recommend jumping straight to the project testing section to learn how to use this Skill to improve the robustness and maintainability of your project’s code.

Phase One: First Make it Work

Many developers encounter a common problem when using coding agents: early in a task, generation is fast, but as requirements accumulate, the model tends to keep appending conditional checks on top of existing branches, leading to chaotic state management — fixing one bug often triggers more unknown errors. To prevent this kind of degradation, ub-mode establishes upfront defensive disciplines in Phase One covering data modeling, system boundaries, and test-first practices, requiring the model to define data structures before generating business logic and to write tests first.

Laziness Protocol & Foundational Thinking

The very first rule in ub-mode is the “Laziness Protocol” (minimum-change and anti-redundancy constraints). Its core includes two requirements:

• One decision lives in one place — the judgment rule for the same logic must be defined in a single location throughout the project; all other callers reuse that definition, avoiding duplicate code scattered across multiple files;

• Ship the smallest edit that solves the problem — preventing unnecessary extra modifications.

Immediately following is Foundational Thinking, which clarifies the development order:

• Before writing any control flow or branching logic, first define the correct data shape;

• Prioritize building foundational infrastructure and underlying design that simplifies subsequent development;

• In scenarios with concurrent writes, sharing mutable state across components is prohibited.

In the architectural guidelines — Model the Domain and Type System Discipline — the rules further list four constraints:

• Design the domain model as a structure that makes illegal states impossible, while maintaining a unified domain glossary; if existing code is already clear and localized, don’t change it casually;

• Make the illegal value impossible to write at the type level;

• Parse outside data once, where it comes in, at the system boundary;

• Do not silence the compiler or suppress type-check warnings.

To intuitively understand “making illegal values impossible to write at the type level,” let’s compare using a TypeScript order status definition common in everyday business (illustrative):

// Anti-pattern: the combination of isPaid: true with a missing transactionId passes type checking
interface Order {
  id: string;
  isPaid: boolean;
  paidAt?: Date;
  transactionId?: string;
}

When tightened according to ub-mode’s type discipline, the data structure should first be defined as a discriminated union before generating any logic:

// Positive example: the type checker rejects a "paid" state that is missing the transaction ID or payment timestamp
type OrderState =
  | { status: "pending" }
  | { status: "paid"; paidAt: Date; transactionId: string };

When the data structure is defined this way in Phase One, under normal type checking, the compiler will reject combinations like “paid but missing transaction ID” at compile time. Of course, external input still needs runtime validation at the system boundary, and using type assertions or any in code would bypass these checks — which is precisely why the rules also require “parsing external data once at the entry point” and “not silencing compiler errors or warnings.”

Boundary Discipline, Idempotency & State Isolation

In the architectural guidelines, Uncle Bob specifies three requirements for system input validation, data flow, and concurrent state isolation:

• Boundary Discipline: The system performs full validation only when external data crosses the boundary; once inside the internal domain, data is trusted. All core business logic must be implemented as pure functions (functions where the same input always produces the same output, with no external side effects).

• Make Operations Idempotent: Whether an operation is executed repeatedly or restarted after an interruption, the final state the system reaches must remain consistent.

• Separate Before Serializing Shared State: If multiple callers don’t need to modify the same object, each should hold its own independent copy. If mutable state must be shared, the data structure and flow design must enforce a One Writer mechanism.

TDD, Execution & Engineering Levers

In the concrete coding execution process, ub-mode’s TDD guidelines define the standard execution loop:

• Before modifying business logic, you must first write a test that fails;

• Confirm that the test genuinely fails due to the expected missing logic;

• Write the minimum amount of code necessary to make that test pass;

• If a scenario truly cannot be tested meaningfully under the current architecture, the rules explicitly forbid writing meaningless tests just to pad coverage (If an honest test is impractical, do not write a bad one).

For introducing new features or debugging complex defects, the remaining clauses provide engineering-level action guidelines:

• Redesign From First Principles: Prohibited from piling new logic onto a stale, fragile architecture (Do not bolt a new requirement onto the old design). Instead, reason about how the design would look if this requirement had existed from the project’s inception, establish a clear plan, then break it into small units for delivery.

• Subtract Before You Add: Before introducing new abstractions or dependencies into the system, first clean up existing redundant complexity.

• Outcome-Oriented Execution: Always target a final, automatically verifiable system state. Temporary intermediate states during refactoring are allowed as long as the plan is clear and changes are revertible.

• Attack the Premise: When two consecutive fixes based on the same assumption have both failed, you must first distill the underlying assumption into a clear sentence, identify and remove unreasonable module responsibilities. No blind attempts at the next fix are allowed before this preliminary analysis is complete.

• Build the Lever: When a task lacks a clear convention, first manually implement one complete standard unit, then write scripts or tools to automate the rest.

Phase Two: Then Make it Right

Getting features working is only the starting point. Without strict constraints, large models tend to generate code that appears functional but is internally fragile. In Phase Two, ub-mode first establishes three code and test review rules, then requires running three independent command-line checking tools: crapper, dryer, and mutator (README.md additionally recommends the visualization tool uml-viewer).

These three tools form a progressively deepening chain of defense for engineering quality. The outermost layer, dryer, scans for structural duplication in source code, preventing the model from copy-pasting similar logic just to satisfy feature requirements. The middle layer, crapper, goes inside functions to calculate branch decision points, combining with test coverage to assess cyclomatic complexity risk — ensuring that logic branches don’t balloon and that tests are in place. The deepest layer, mutator, directly stress-tests the test cases themselves, injecting defects to verify whether assertions are meaningful — preventing “fake tests with inflated line coverage but trivial assertions.” Through this quantitative, inside-out closed loop, the system can establish objective trust in code and test quality without relying on manual line-by-line review.

Root Cause Investigation, Verifiable Units & Behavior-Oriented Testing

When fixing bugs and reviewing test quality, Phase Two opens with three engineering guidelines:

• Fix Root Causes: First stabilize the reproduction of the defect, then locate the root cause of the anomaly. The rules state: “A guard that only hides the crash is not a fix” — adding null checks alone to mask errors is prohibited.

• Sequence work into verifiable units: Break development tasks into extremely small units that can each be independently tested with automated tests, verifying each before moving on.

• Test Behavior, Not Implementation: Tests must fully simulate the external caller’s perspective when exercising interfaces, and assert the observable results from the caller’s point of view. If a test would still pass when every function body was emptied and returned nothing, the test is invalid and must be deleted outright (If the test would still pass when every function returned nothing, throw it out).

To verify code quality with quantitative data, SKILL.md requires invoking the following three checking tools.

Check 1: Crapper (Each Function’s CRAP Score Must Be Below 10)

unclebob/crapper is a cross-language (Clojure, Java, Go, TypeScript/JS, Rust, Python) tool that jointly calculates complexity and coverage. It uses the CRAP (Change Risk Anti-Patterns) formula from software metrics to score each function:

CRAP = CC² × (1 − coverage)³ + CC

Where CC is the function’s Cyclomatic Complexity (counting branch decision points inside the function, including if, for, while, switch/match branches, catch/except, ternary expressions, &&, ||, plus TypeScript’s ?? and ?.), and coverage is the function’s test coverage (a decimal between 0 and 1).

According to crapper’s documentation, scores of 1–5 indicate low risk, 5–30 warrants attention, and above 30 indicates complex, undertested code. Under ub-mode’s rules, each function’s score must be kept below CRAP 10 by splitting functions, adding tests, or both (Reduce each function under CRAP 10), while also reviewing whether branch statements can be simplified.

Doing the math: if a function’s cyclomatic complexity reaches 10, even at 100% coverage (where (1 − coverage)³ = 0), its CRAP score would be exactly 10 — still failing the < 10 requirement. This means a function with cyclomatic complexity of 10 cannot pass by adding tests alone; it must be split (though note that cyclomatic complexity only counts branches — long sequential code can still score relatively low). Running ./crapper invokes the coverage engine for the corresponding language, outputs a table in the terminal sorted by score from high to low, and writes results to .metrics/crap.edn.

For example, when running crapper on the actual project, the terminal output a function-level cyclomatic complexity and CRAP score table:

Check 2: Dryer (Eliminate Structural Duplication Above 0.8 Similarity)

When generating code, large models tend to reuse existing logic with only minor variable name changes. unclebob/dryer is a cross-language scanning tool designed to detect this kind of structural duplication. Note that dryer only compares code blocks within the same programming language (by default, it skips functions with fewer than 4 lines or fewer than 20 normalized syntax nodes).

It computes the Jaccard similarity of two code blocks’ normalized Abstract Syntax Tree (AST) structure fingerprints — the number of shared structure fingerprints divided by the total number of unique structure fingerprints in either block:

score = number of structural fingerprints shared by both blocks ÷ total number of unique structural fingerprints across either block

During structural normalization, dryer retains called function names, method names, operators, and the nesting shape of the syntax tree, but strips out local variable names, field names, literals, and Clojure keywords like :kind. Using the two Clojure functions from unclebob/dryer’s official documentation as an example:

(defn alpha [xs]
  (let [ys (filter odd? xs)]
    (map inc ys)))

(defn beta [items]
  (let [kept (filter even? items)]
    (map dec kept)))

Although these two functions differ in their names (alpha vs. beta), parameter names (xs vs. items), local variables (ys vs. kept), and the predicates/mapping functions passed as higher-order function arguments, the retained filter and map call heads and the underlying syntax tree fingerprint sets are identical, producing a structural similarity score of 1.0. (Note: these example functions are only 3 lines long, so under dryer’s default --min-lines 4 parameter they would be skipped; you need to lower the line and node thresholds for them to be reported.)

Running ./dryer reports structurally similar candidate files and line ranges. For example, the official documentation shows a report format like:

DUPLICATE score=0.89
  src/billing/invoice.clj:3-13
  src/billing/receipt.clj:3-14

Under ub-mode’s rules, it is explicitly required to run the dryer tool to eliminate all structural duplications with a similarity of 0.8 or above. When running dryer --threshold 0.8 on the actual project, the terminal output the following duplicate structure location report:

Check 3: Mutator (Mutation Testing for Surviving Mutants and Dead Code)

Even if code coverage reaches 100%, it does not prove that the tests genuinely verify the business logic. unclebob/mutator is the companion cross-language automated mutation testing tool.

Mutation testing is an engineering method for evaluating the effectiveness of an automated test suite. The tool automatically replaces an operator or constant somewhere in the source code (for example, replacing greater-than with less-than, or plus with minus), creating a defect-injected copy of the code called a mutant. The core logic is: if the source code is injected with a defect and all unit tests still pass without triggering assertion failures, the test coverage has a blind spot — the mutant is classified as survived. If the unit tests fail and catch the error, the test case successfully blocked the mutant — it was killed.

Its working mechanism is: automatically identify selected operators or constants in the source code and replace them (each replacement produces one mutant), for example replacing + with -, > with >=, == with !=, && with ||, true with false, or removing optional chaining calls in TypeScript (replacing a?.() with a()). Mutator then creates parallel working directories under target/mutation-workers based on the number of CPU cores (modified files and their relative imports are copied; all other files are symlinked), and runs the project’s unit tests once for each mutant. Additionally, mutator supports incremental runs — subsequent executions only re-run previously survived mutants and functions that have changed.

The evaluation criterion is: if unit tests fail or time out after the source code is replaced, the mutant is classified as Killed. If unit tests still all pass after the source code is modified, the mutant is classified as Survived. Once surviving mutants are detected, the ./mutator process returns a non-zero exit code 3.

We can illustrate the practical value with a free-shipping boundary example: suppose the business rule is “orders of 100 yuan or more get free shipping,” and the implementation reads amount >= 100. If the test cases only cover 50 yuan and 150 yuan, both tests pass and the line coverage for that line of code is statistically 100%. But when mutator automatically replaces >= with >, the tests for 50 yuan and 150 yuan still pass — the mutant has survived. This clearly indicates that the test suite is missing the critical boundary case of “exactly 100 yuan.” To kill this mutant, a test assertion for “exactly 100 yuan” must be added to the test suite (asserting that 100 yuan qualifies for free shipping). Once that test is added, when mutator again replaces >= with >, the 100-yuan test case will fail — the mutant is successfully killed.

When analyzing mutator’s results, two engineering boundaries need to be understood. First, according to mutator’s official documentation, compilation errors caused by mutation injection also count as successfully killed, so mutant elimination does not fully equate to business assertions catching the error. Second, surviving mutants usually indicate missing tests, but some are equivalent mutants (where the operator was changed but the system’s externally observable behavior remains unchanged).

Based on mutator’s output report, ub-mode’s SKILL.md gives three explicit handling requirements:

• Cover the uncovered: Write tests for uncovered code;

• Kill the survivors: Add boundary assertions to block surviving mutants;

• Delete dead code: Clean up and remove unused code in the project that is never called.

The subsequent Refactoring guidelines further clarify: before refactoring, existing external system behavior must first be solidified through comprehensive automated tests; then the internal implementation structure is adjusted; and after refactoring is complete, verify that external behavior has not changed in any unexpected way. When running mutator on the actual project, the terminal output the following mutation blocking report:

Companion Visualization: UML-Viewer (Architecture Health & Dependency Direction View)

In addition to the three checking tools written into SKILL.md, ub-mode’s README.md also recommends a companion repository: unclebob/uml-viewer (not mentioned in SKILL.md). It overlays structural diagrams generated from source code scanning and architecture configuration with metrics from the .metrics/ directory generated by crapper and mutator (it does not read dryer’s results).

In uml-viewer’s view, the fill color of each package and class card is determined by the module’s CRAP score (mean plus standard deviation, μ + σ) and mutation testing kill rate. Each metric is converted to a level from 1 to 10 (10 is best), then averaged. If a module is missing data, it displays as level 1 in red. If the user defines :levels in the configuration to delineate architecture layers, reverse dependency arrows pointing from inner layers to outer layers are drawn in red (bolded when selected). Without :levels configured, they are not automatically highlighted. Clicking a method name on a class card opens the source code and navigates to that function’s definition. After launch, the desktop application displays a real-time architecture overview window as shown below:

Phase Three: Engineering Practice

After completing code and test reviews, ub-mode defines four engineering practice rules for the agent’s daily operations in the local workspace:

• Keep a Log: Record every specific operation performed and the reason for it in detail, and report a summary of the log to the user at the end of the task.

• Guard the Context Window: Keep the main conversation thread lean; divert large volumes of logs or intermediate output to external files or subtasks, preventing terminal output from rapidly consuming the context quota.

• Worktree Cleanup: Identify temporary directories or Git Worktrees that can be safely cleaned up, reclaiming disk space after confirming no background tasks depend on them. For uncommitted local changes, you must pause operations and hand them over for human confirmation — overwriting or cleaning them up on your own is prohibited.

• Commit and Push: Maintain small, orderly commits. Each Git commit must clearly explain the motivation (Why), the specific changes (What changed), and the evidence verifying correctness (How you proved it). Although the original rule states “push to the main line at the end,” in team settings this should be coordinated with existing branch protection strategies and Pull Request workflows.

Real-Project Testing: How to Drive an Agent Through This Rule System

After understanding ub-mode’s thinking order and code discipline, the most critical engineering question is: in a real development environment, how exactly does a human drive an agent to put this system into practice?

In practice, implementing this system typically falls into two scenarios: a brand-new project that hasn’t started yet, or an existing project with legacy code.

For a new project that hasn’t started yet, injecting SKILL.md as upfront coding guidelines to the agent is the ideal application of these rules. Without constraints, when developing new features, agents tend to follow the path of least resistance — mixing data structure definitions, network requests, data validation, error handling, and business calculations all into a single function in a single file, planting high cyclomatic complexity and tight coupling risks right from the project’s start. If the rules are loaded from day one, the agent will be bound by defensive disciplines when writing the very first line of code: write failing unit tests first, provide a minimum implementation, use the type system to lock down illegal states at the system boundary, and decompose business logic into small, side-effect-free pure functions — avoiding monolithic functions with high cyclomatic complexity from the source. Moving forward, configuring crapper, dryer, and mutator into an automated pipeline before each feature commit will keep the new project consistently healthy at a low technical-debt level.

For an existing project with legacy code, mechanically running commands outside the actual development workflow doesn’t fit daily engineering habits. In real scenarios, the human drives the agent through conversation, completing the full governance loop of “install rules, deploy gates, full health check, quantitative refactoring.” To test how this process performs in real engineering, I used Claude Code to run the complete workflow on my own open-source project oh-my-x (a browser extension built with TypeScript and the WXT framework). The entire process consists of four sequential steps:

1) Install the Skill: First, load ub-mode’s behavioral rules into the agent, establishing the defensive thinking order and commit discipline. In Claude Code, directly send the installation instruction:

https://github.com/unclebob/ub-mode please install this skill

2) Have the agent install and lay out the quantitative quality gate toolchain: After loading the rules, the metrics tools need to be configured for the project. Simply issue the installation instruction to the agent:

help me install the tools I need

The agent will automatically create a tools/ directory at the project root and download and clone dryer, crapper, mutator, and the visualization tool uml-viewer from Uncle Bob’s repositories into adjacent directories. A few key parameters to note: crapper’s default threshold is 30; to strictly enforce the < 10 rule, you must pass --threshold 9.99. Dryer’s default threshold is 0.95; it is recommended to set it to the rule-required --threshold 0.8. Mutator requires --test-command to be bound to the project’s unit test command (e.g., Vitest) to avoid blind full-project scanning.

3) Drive the agent to conduct an engineering health check: After the tools are installed, ask the agent how to apply the health check and optimization in the current project:

how should I apply this skill to optimize the project code next?

The agent will provide a specific optimization roadmap based on the project’s current state, sequentially invoking the underlying toolchain to scan the core code, identifying modules with structural duplication, cyclomatic complexity exceeding thresholds, or lacking test coverage.

4) Issue refactoring instructions with constraints to the agent, completing the closed loop from detection to fix: After the tools detect cyclomatic complexity exceeding thresholds or code duplication, the agent will propose targeted suggestions. In the test scenario, the agent suggested first completing the test suite. Then I asked the agent what to do next according to the Skill:

according to the skill’s rules, what should I do next

Having the agent continue the refactoring per the rules yielded step-by-step repaired code and test results:

By driving the agent to investigate and refactor step by step according to the rules, the existing project completed the closed loop from problem identification to quality convergence. In the test, addressing the weaknesses identified by the tools was done in two steps: first, for the surviving mutants found by mutator (mainly concentrated at boundary conditions like >= vs. >, and null value handling), business assertions for critical boundary values were added to the unit test suite; then, for the monolithic functions with high cyclomatic complexity reported by crapper, reasonable splitting was performed, extracting tangled conditional branches into independent pure functions. After completing these changes, running the metrics tools again showed all function scores dropped below the CRAP 10 safe threshold, all surviving mutants were precisely intercepted by test cases, and the mutator process returned a normal zero exit code. At this point, while maintaining consistent external behavior, the code achieved measurable, verifiable quality improvements.

Conclusion

From Uncle Bob publishing Clean Code in 2008 to writing this 152-line ub-mode for large models in 2026, while the tools for generating code have changed with the evolution of technology, the underlying standards for evaluating software quality have never wavered.

Large language models have lowered the marginal cost of generating code, but they have not reduced the complexity of maintaining systems. The flexibility of Vibe Coding belongs to the early prototyping and exploration stage. When a system carries real business at high concurrency, what determines product stability is still rigorous data modeling, the logical isolation of pure functions, and the engineering foundation built by automated tests and metrics tools.

Uncle Bob’s rules and toolchain essentially transform the quality discipline accumulated over decades of software engineering into constraint rules that AI agents can execute and verify. This discipline manifests not only in the code artifacts — establishing quantitative quality gates through objective metrics like cyclomatic complexity, duplication, and mutation testing — but also in operational practices — regulating the agent’s behavioral boundaries through context window management, maintaining operation logs, and disciplined small-step commits. In the past, writing high-quality code required engineers to undergo years of practical experience and training. In the era of large models, this threshold has been redefined: even if a developer doesn’t hand-write low-level refactoring line by line, as long as they know how to configure the right engineering rules and quantitative tools for their agent, and uphold the principle of “first make it work, then make it right,” they can have AI consistently deliver architecturally sound, long-term maintainable, production-grade code. “Anyone can write good code” now has a clear technical foundation.

I recommend saving the rules breakdown, metrics tool mechanisms, and practical parameters covered in this article for future reference. Whether you’re leading development in a team or building products as a one-person company (OPC), when you find AI-generated business logic becoming hard to maintain, or unit tests passing but missing boundary scenarios, consider referencing this guideline — configure it into your Claude Code, Cursor, Codex, or other agents to recalibrate the boundaries of code quality and interaction practices.

Long Hai | Former big-tech programmer — Project Manager — Product Manager, currently in OPC practice (unemployed) | Aiming to be the man who finds pain points best on X | Built several small products | Remember to follow me https://x.com/longhaiqwe123 | Contact info on my profile