The nice thing about lambdas is that they optimize for writing code. When coding, it’s quite convenient to stay within a function’s boundaries and just flesh out detailed steps as lambdas that are then being passed to map/filter/reduce-like operations.

The bad thing about lambdas is that they optimize for writing code. They do so at the expense of reading code, which is arguably a much more frequent activity.

So let’s start from a specific lambda example and then refactor our way towards better abstractions.

Name the nameless

Quick, what is the following code doing?

rolls.stream()
    .map(roll -> roll + 2)
    .filter(roll -> roll >= 15)
    .sum();

It’s a mere 3 lines of code, and the mechanics of each one is trivial. Yet the purpose, intent, and business rules remain opaque. It could be anything.

The lack of explicit domain concepts is a warning sign. Instead, we should raise the abstraction level by naming those lambdas to reveal the code’s intent:

rolls.stream()
    .map(AttackRoll::applyStrengthModifier)
    .filter(AttackRoll::isSuccessfulHit)
    .sum();

The preceding code is no longer a stream of seemingly random operations. Instead it communicates the concepts and rules from the domain. (In this case: Dungeons & Dragons).

The new methods — applyStrengthModifier and isSuccessfulHit — are trivial one-liners. You implement them according to the idioms and features in your programming language of choice. For Java, I’d go with either private static methods or, if I notice groups of related abstractions, a private class. In Python or Clojure, we get away with even less syntactic noise: just use private module-level functions.

Subscribe now

Balance the trade-offs

A fair objection at this point is that the proposed approach leads to more lines of code. That’s true, but not necessarily a problem:

• Abstractions can be simple. Ridiculously simple.

• Abstractions don’t have to be re-used to motivate their existence.

• Lines of code are not a finite resource. Some abstractions might lead to more code. That’s a trade-off.

My short test for any abstraction is: if it elevates the level of the code, then it has earned its rights.

Granted, the recommendation to avoid lambdas didn’t come easily. I’m a Lisp hacker by birth. (No, not really, but I always wanted to write that sentence.) But I did spend the past 20 years doing functional programming, and have watched my style gradually migrate away from lambdas.

Naming functions — even those trivial one-liners — makes a large difference when returning to code you wrote months or years earlier.

Abstract the pipeline steps

I usually take this abstraction a step further when the programming language allows it. Java doesn’t fall naturally into that category, so let me switch to a simple Clojure example.

Here’s the same problem in Clojure:

(->> rolls
     (map (partial + 2))
     (filter #(>= % 15))
     (reduce +))

If you haven’t seen Clojure before, then the threading macro ->> probably looks odd. It’s just a convenient way of passing the result of one function as the input to the next.

And just like in the Java example, refactoring away the lambdas clarifies the intent:

(->> rolls
     (map apply-strength-modifier)
     (filter successful-hit?)
     (reduce +))

But we can take it one step further, and also name the pipeline elements. This makes all the difference:

(->> rolls
     with-strength-modifier
     successful-hits
     ->damage)

With that, the code now reads like a story, telling the rules of the domain. We’ve come a long way with simple steps. Anonymous functions are anonymous thoughts.

Optimize for reconstruction work

By naming lambdas, we raise the abstraction level and add information that wasn’t previously visible. This is important since much code needs to be prepared to evolve.

When picking up a new coding task, that work often happens within the context of an existing codebase. This is where proper abstractions pay off by limiting the necessary reconstruction work. And the closer our abstractions reflect the problem domain, the easier that will be.

That’s also true for coding agents as captured in the CLEAR principles for AI-first codebases. We will all do a better job when the code’s purpose is expressed structurally. Small abstractions add up, so make them a habit.

As developers, we’re used to being accountable for all code we write. Coding agents do not change that. But we need to use our time effectively, and I simply found that trying to grasp all code in detail is no longer efficient; if we approach agentic coding the way we tackle manual coding, we’ll spend the majority of our time deconstructing meaning from code. It’s wasteful and cognitively effortful.

That obviously doesn’t mean that I no longer care about readability, code structure, or architecture. Quite the contrary. This whole blog is about maintainable code. Rather, I leverage automation and strict processes to relieve me of the code-reading burden without incurring unacceptable risks.

Human inspection is driven by uncertainty

A question like ”do we still need to read all AI generated code” is pointless in isolation. The answer depends on the task, and more specifically on the uncertainty inherent in each type of task. That is, how much of the intended solution’s behavior and structure is already understood and represented in the existing system.

That task uncertainty drives both the relative autonomy I grant a coding agent, and the effort I spend reviewing the resulting code.

Consider a bug fix. Here it’s usually enough to inspect the evidence for the fix. Reproduce the problem, fix it, and have the new tests pass. Since the majority of bugs are local and contextual, bug fixes rarely require novel designs or architectural changes. They are naturally constrained.

Contrast those bug-fixing tasks with the first iteration on a new feature or capability. The existing structure and patterns in a codebase are important context that guides coding agents. When doing novel work, establishing those structures is key. This requires more detailed involvement. However, it doesn’t require that I read all code. Let’s explore the process.

Tests as human/agent abstraction boundaries

Understanding code we didn’t write ourselves is one of the hardest parts of software engineering. If we approach agentic coding the way we tackle manual coding, we’ll spend the majority of our time trying to deconstruct meaning from code. We’d effectively turn ourselves into legacy code maintainers. That’s a mentally draining place to be and is unlikely to speed up anything.

So instead I’ve come to accept that I’ll no longer know every line of code. I never read all AI-generated code. But, and this is important, make the code you do read count.

The pattern that worked for me is to focus my manual review efforts on tests. I typically instruct my agent — after the planning stage — to generate the end-to-end (e2e) tests first. I then review, and iterate on those tests together with the agent.

Subscribe now

A strong test suite serves as a boundary between the code I do inspect and the code I give the AI autonomy to develop.

Starting with e2e tests solves the validation problem: how do I ensure that the AI generates the right code?

With the e2e tests nailed down, I typically let the agent proceed and write the code that makes them pass. I rarely spend much time looking at the actual implementation.

The possible exception is novel features that don’t yet have an architectural home. Software development never was, and still isn’t, a streamlined, simplistic transformation. In such cases, I do perform spot inspections of the code. But again, I don’t focus on details, but rather on the overall structure and patterns to lay a strong foundation for the next iterations that can be more autonomous.

Turn review findings into future guards

Now, before we proceed to discuss code quality, let me emphasize that I do spend a lot of time iterating on those tests. AI-generated application code is rarely optimal out of the box. But it’s usually decent. The test code? Not so much. So it pays off to run those extra test refactorings.

My focus for the e2e test design is to optimize for ease of inspection.

The iterations and refactorings I do are typically:

• Bringing the tests and code closer to the domain.

• Looking for gaps and omissions, including negative tests and error reporting.

• Introducing additional abstractions to document the intent.

That is, context that helps future iterations.

I do resist the temptation to change the code myself. Instead, I instruct my agent to change it and, once I’m satisfied, I instruct the agent to capture the transformation as a forward-looking SKILL. That way, my review findings turn into future guards and guidance.

Enforce what you don’t inspect

So, how can I guarantee that the uninspected application code remains maintainable and easy to change?

You occasionally hear that code is all about outcomes: what business value does a piece of code enable? That’s partly true, but also a massive bit of an over-simplification.

Code isn’t just produced and then lying dormant as an immutable artifact. Successful features attract change: improvements, extensions, and additional capabilities. Typically the most business-critical code experiences the largest volume of changes. Making those changes easy is what good software design is all about.

In sharp contrast to early hype, AI didn’t make software maintenance go away. Rather, AI amplified the need for maintainable code. As our research discovered, a coding agent is even more picky about code quality than we humans. The bar is higher. So how do I ensure that my code is maintainable if I don’t review it? The solution is a multi-layered safety net.

Over the past six months, I’ve built up a collection of SKILLs that capture my preferred coding style, design principles, and application-specific rules for architecture, etc. Those SKILLs grew gradually as feedback to flaws in AI-produced code.

Still, code quality cannot be left to chance, hoping that Claude or Codex are having a good day. Consequently, I use deterministic tools as part of my workflow. Some of these tools are commercial (e.g. vulnerability scanners, and the CodeHealth MCP), others like linters are free. I then complement those tools with custom-built domain-specific checks to enforce architectural rules and even to catch some of the most common e2e sins.

The point is that these rules and constraints need to be enforced. Deterministically.

The hardest thing to refactor is our habits

Given that I had typed out code by hand for almost 40 years, becoming comfortable with not reading code was a large mental shift when going agentic.

Almost a year into my agentic journey, I’m now quite confident that I don’t need to know every line of code. I get that confidence by knowing that the system behaves as intended, remains maintainable, and lives within the established boundaries.

I also made peace with the fact that agentic code might not look exactly the way I would have written it myself. Familiarity is a poor argument for resisting change.

In this article, I’d like to go beyond the usual suspects and highlight books that influenced how I think about code.

This selection is from books written pre-2015. Why stop there? Simply because a decade is the time I need to truly see the impact a specific book had on me.

The litmus test is: did the book a) change my coding style, and b) was it a sustainable change that made a positive difference?

My take on the classics

It wouldn’t be fair to just skim past the common recommendations. So let me fall into my own trap with a brief take on those.

First, Refactoring, Domain-Driven Design, and the Pragmatic Programmer are all classics for a reason. Amazing books, and mandatory reads.

Working Effectively with Legacy Code deserves all its praise, and of course everyone (yes, really) should check out the Mythical Man-Month.

Clean Code is another standard recommendation, but that one wasn't for me. There are useful design principles in there worth studying, but the book as a whole is too narrow and a bit too dogmatic for my taste. Your mileage might vary. I'd point to Modern Software Engineering by David Farley instead. (See — There are exceptions to all rules. Even my "pre-2015" rule.)

With that said, it’s time for my own list. What do we find when we look beyond these classics?

Beyond the usual suspects: Adam’s Top 5 Programming Books

• Smalltalk Best Practice Patterns. True, Kent Beck is better known for his later work, which is excellent too. But Smalltalk Best Practice Patterns is particularly strong on coding style. I learned a lot by just reading the code examples. Small tweaks to names and abstractions add up. No one captures that better than Kent.

• Structure and Interpretation of Computer Programs (SICP) by Gerald Jay Sussman and Hal Abelson. SICP is my all-time favourite programming book. It’s also where I learned about the power of wishful thinking when coding. SICP uses wishful thinking as a design tool: write code as if the abstraction already existed. Pretend. Then, once the ideal abstraction has taken shape, you go ahead and implement those functions. This meta-level is what made SICP so valuable. Ultimately, it’s a book that teaches how to think about code and problem solving. I’m tempted to even say that SICP is more a work of art than a pure coding book, but I won’t go there. A beautiful book.

• Paradigms of Artificial Intelligence Programming by Peter Norvig. Learning the AI described in this book probably won’t land you a job today. But reading the code examples will transform how you think about source code. The book shines when it comes to code comments, a topic that I’ve never seen demonstrated well in other sources. Here we get to see how comments become valuable as a narrative that explains both intent and reasoning. Brilliant, just brilliant.

• Facts and Fallacies of Software Engineering by Robert L. Glass. In essence, this is a book about an industry that refuses to learn. That was true 25 years ago when this book was published, and it’s probably twice as true today. (Just think about all the AI adoption metrics being rolled out — back to productivity mistaken for lines of code produced, only more elaborate. And expensive). What I like about this book is that Glass doesn’t present anything new. Quite the opposite, actually. Rather, it’s about research lessons that we all should know, but tend to forget. Ever had to do an estimate, or plan according to a requirements spec? Or maybe you thought that enough eyeballs make all bugs shallow? Then this book is for you. A great work by a fantastic author.

• Thinking Forth by Leo Brodie. I used to have this habit where I learned various programming languages. To challenge my perspective, I chose languages from families and paradigms that were fundamentally different from what I already knew. Occasionally, I stumbled upon greatness. Thinking Forth presents programming as a creative process, and it delivers those lessons in an entertaining and pedagogical way. The book is particularly strong on software analysis and design, but it’s the execution and technical writing that brought the book to my top five. This is the book for anyone writing about software — Leo’s way is the way to do it.

Since the ranking is zero-indexed, there’s one more book in the top 5:

• The Nature of Code: Simulating Natural Systems with Processing by Daniel Shiffman. This book is a beautiful introduction to simulations of natural systems. We get concise prose, clear illustrations, and carefully chosen systems with a guided tour through the math. All done in the Processing language, which is fun and easy to pick up. The reason I like this book so much is probably due to timing. In 2013, I was on the verge of abandoning software development. I was fed up. (That’s a story for another time.) Instead, I planned to go into cognitive psychology full-time as a researcher. This book brought back the joy in programming for me. Sometimes, a good book is the book that motivated you.

Honorable mentions

Picking a top five was hard. There are so many other enjoyable books, and on a different day, the list above might have included any of the ones below:

• The Art of the Metaobject Protocol by Kiczales, Rivieres and Bobrow. This one is for those times when you need to bend your mind in interesting ways...

• ...and Let Over Lambda by Doug Hoyte is perfect for those three people in the world who find The Art of the Metaobject Protocol underwhelming. One of the most impressive books I’ve read.

• The Design of Design by Frederick P. Brooks. It never received the attention that The Mythical Man-Month got, yet The Design of Design shares many of its qualities. It’s a book that grows, and there’s a wealth of insights on offer.

• The Little Schemer by Friedman and Felleisen. This book won’t teach you Scheme. Rather, it teaches something more valuable: it teaches how to think recursively. Working through the book even made me comfortable with the Y-combinator in lambda calculus. (At least for some time).

• Multi-Paradigm Design for C++ by James O. Coplien. Twenty years after reading this, the core techniques are still with me. These are commonality analysis, where the purpose is to identify families of systems, and variability analysis, which focuses on capturing the domain parameters that vary. In essence: the foundation of great software design.

Alright, I’ll try to stop here. Otherwise I get tempted to also throw in The Timeless Way of Building, Programming Erlang, The Art of UNIX Programming, and, and, and... No — promise: I stop right here. Let me just offer some parting words.

The books in this post might use a specific programming language. But it would be a mistake to think that they are about that language. Their lessons are wider, much wider. They demonstrate better ways to think about software.

So when reading these books, we shouldn’t focus on the specifics. It’s all about the general lessons. And those transcend the Lisp, C++, Smalltalk, or Forth used in coding examples. To me, that’s the hallmark of truly great books.

Let’s assume we (or BigTech) succeed: tomorrow’s coding agents perform at the level of today’s best software engineers. My argument is that this still wouldn’t be enough.

AI Raises the Quality Bar

A popular claim these days is that coding agents already write better code than many programmers. That’s probably true. And the bar keeps getting pushed.

So why would a coding agent performing at the level of a human expert still be inadequate?

The reason is that AI itself changes the quality threshold required to keep systems stable.

The most obvious change is that tomorrow’s systems will be much more complex than today’s. We just need to look back at our history. Each major productivity increase in software history has made us take on larger and more complex problems. Improved capabilities let us automate tasks we couldn’t automate before. Lehman’s laws of software evolution captured that force decades ago: useful software keeps changing, growing, and accumulating complexity unless we actively fight it.

Another change is that an agent is orders of magnitude faster than a human in terms of raw code generation. That speed causes problems already today. And still: future systems are likely to evolve at a pace that is significantly higher than today where we still have plenty of constraints and manual checkpoints in our delivery pipelines.

Combine these two evolutionary pressure points, and you get codebases that few — if any — of today’s experts could stay on top of.

Subscribe now

Scale Changes the Problem

These pressure points also explain why human expert level is the wrong bar.

The first challenge is that defect opportunities scale with code volume and change volume. It’s a safe bet to claim that future systems will have that relationship, too. Larger modules, larger changes, and higher code churn have been linked to fault risk for decades.

Without a corresponding breakthrough in verification and validation techniques, a more ambitious and larger system developed at that breakneck speed by a future human-expert-level AI would be a fertile breeding ground for bugs and quality risks. We’d get to truly experience what it means to be wrong at scale.

Second, coding agents are based on a stochastic core. At their very heart, LLMs are prediction machines. Even if we manage to reduce their defect rate to something like the magical six sigma, lessons from industrial production still tell us that the potential for error will always be there.

A tiny failure rate is manageable at human throughput. But generate enough code, and rare errors stop being rare at the system level. A one-in-a-million mistake sounds impressive...until you start making millions of decisions. All the time. That’s one consequence of scale.

So today’s bar is too low for tomorrow’s AI. AI changes the scale of the problem.

Embrace Imperfection

If human-expert code is insufficient, then quality, correctness, and fit need to be addressed with a different approach, too.

One possible response is to aim for superhuman code quality. Personally, I don’t think that’s a realistic path. Where would we even get the training data and feedback signal? Synthetic data, but from what and whom? The hardest software decisions are contextual, and rarely come labeled and packaged as reusable training examples. And yes, AGI has been “just a few years away” for the better part of fifty years. I wouldn’t hold my breath.

More importantly, human-level coding may not even be the problem we need to solve.

Today, my approach to taming agents has been to accept their unreliability. I suspect that direction holds the keys to the future of software quality, too.

So, perhaps, instead of aiming to generate perfect code, we’d need to double down on creating environments where unreliable agents reliably produce acceptable outcomes. The future might belong to those organizations that embrace that imperfection today.

Each time we write code, we face a multitude of micro-decisions. How do we label functions, classes, variables, etc. to get the most out of the code as a communication medium? That is, communication that sharpens our thoughts in the moment, as well as code that supports our future selves and any agent trying to make sense of what’s already there.

As such, naming in software goes way beyond any aesthetics. Good naming minimizes reconstruction work. For both humans and machines.

In this article, I share the style and habits that I’ve picked up. It’s a style that evolved over the years, and shaped by viewing software through the lens of cognitive psychology to support the way we think, reason, and solve problems.

Why naming matters

Names are cognitive compression mechanisms. Design elements with strong names stretch the amount of information you can hold in your head at once.

Further, when reading unfamiliar code, we try to infer the purpose by building up mental representations. This process is largely driven by the names of classes and functions. The stronger the names, the easier the process.

And this translates into time savings, too. For example: clearer identifier names cut debugging times by 19% alone.

AI-assisted development benefits too. A recent study investigated the structural elements that contribute to LLM code understanding. Improving identifier names consistently yielded the largest returns.

Optimize function names for calling context

Most naming advice focuses on the declaration site. However, we read call sites far more often than declarations.

Consequently, we should communicate context via names. Let the names combine to build sentences in the calling context:

notify_all(registered_clients, about=the_new_version)

Turning our function calls into sentences has cognitive reasoning benefits: that one sentence serves as a chunk. It becomes an abstraction that allows us to squeeze much more information into our cognitive working memory. That way, reasoning improves.

Derive names via wishful thinking

Now, let me share a trick that has helped me get this naming right over the years: the beauty of Wishful Thinking. Wishful Thinking in this context is a design tool that I learned about from the uber-classic Structure and Interpretation of Computer Programs. The idea is to write code as if the abstraction already existed. Pretend. Then, once the ideal sentence has taken shape, you go ahead and implement those functions. Naming comes first.

The reward is code that reads close to natural language without becoming verbose. That helps bridging the gap between the problem we’re trying to solve and the solution we express.

Subscribe now

Let domain types liberate your parameter names

A function name is incomplete without its arguments. Yet too much code misses that opportunity.

A common reason for that is the code smell primitive obsession: representing domain concepts using primitive types. Consider:

public ActionResult ListRss(int languageId) {
...
}
public ActionResult NewsItem(int newsItemId) {
...

While an RSS feed and a News item are clearly separate domain concepts, the code models both as raw integers. Besides weakening the type system, that code also fails to clarify context and intent. What roles does the news item play? Was it clicked by a reader, or selected to feature on a front page?

Introducing proper domain types lets us solve both problems. When the types capture the domain, they also liberate the variable names. Those names can now be repurposed to communicate context:

public ActionResult ListRss(Language preferredRssFeedLanguage) {
...
}
public ActionResult NewsItem(NewsItem clickedArticle) {
...
}

The types tell us what the arguments are. That frees the parameter names to tell us why they’re there.

Scope determines length

We get told that we should let our variables explain exactly what they do. This naturally leads to longer names. However, like all programming “rules”, the soundness of that advice depends on context. Names don’t carry meaning in isolation. They expand on their surrounding context.

So, variable naming should reflect scope. The smaller the scope, the shorter the variable name. (and vice versa).

As an example, consider the following:

for i, article in enumerate(front_page_articles):
    publish(article)

An i might be perfectly fine in that short, tight loop or in a lambda function. The whole block serves as one logical element, one chunk.

It also follows from the same principle that a one letter name is detrimental in a larger scope such as an instance variable or, shudder, a public API. There you really want to spell it out since the context cannot communicate the purpose of an i variable.

Naming conventions that detract

At this point, it’s time to look at what not to do.

Drop the I

Every now and then I travel outside my functional programming circle, and have to code in an object-oriented language. My object-oriented code follows the same style as presented here. This causes me to break one of the common “best” practices: the I-prefix added to interface names.

That is, I’d create a ChatConnection interface rather than an IChatConnection.

The fact that something is an interface is probably the least interesting aspect about that abstraction. I’d even argue that it’s a leaky name. Any user that gets hold of a reference to an instance of that type shouldn’t have to care how it’s implemented. Is it a concrete class? An abstract one? Or really an interface? Who cares? I don’t. So drop that cognitive distractor, the I-prefix.

Get rid of the getters

...and the setters.

We’ve probably all seen plenty of code along the lines of getCustomer(id), or setCustomerName(name).

Those prefixes, get and set, rarely add value. Rather, they detract by leading us down the dangerous path of asking rather than telling. (See the Tell, don’t Ask principle). The names are procedural in their nature, and attract such code:

customer = get_customer(customer_id)
set_customer_status(customer, SUSPENDED)

The preceding logic is better modelled as:

suspend(a_customer)

And even if we stick to query-like functions, pure renaming makes the code read better:

buyer = customer_for(customer_id)

Disagree? Well, I said it’s an opinionated guide. There’s also a psychology lesson here, so let me throw in the mere-exposure principle. The mere-exposure principle says that repeated exposure tends to increase our preference for something. We like what we’re familiar with.

My advice is to continuously question our practices. Are they based on familiarity or reason?

Avoid the dumpster

One of the most common naming issues I tend to see are generic placeholder names like Utils, Misc, or Helper.

Names aren’t just passive labels. Just like the getters and setters, these names influence future behavior and perspective. A vague and imprecise name — like Utils — will attract code of those same qualities.

Each time we feel tempted to create a utility class, it’s an admission that we’re prepared to give up on our design. Resist the temptation, and iterate once more. Somewhere, there’s a domain concept looking to get out and get a proper name.

Good names reduce reconstruction work

This article reflects stuff I’ve learned over my three decades in software. The goal has always been to let the code communicate as effectively as possible.

That way, we guide future code readers, whether they are fellow humans or, increasingly common, coding agents. Both benefit from explicit intent and rich context. So, give your naming the focus it deserves.

A boolean parameter looks harmless. It is just one extra argument, and inside the method it’s just one more branch. Yet that small boolean often hides a larger design problem: it forces the caller to select behavior.

That is the smell known as control coupling, first identified by Larry Constantine in the classic Structured Design from 1979.

Control coupling means one module controls the internal execution flow of another. Consider this example:

public String incidentUpdate(Incident incident, 
                             boolean executiveAudience) {
    String severity = severityLabel(incident.severityLevel());
    String incidentReference = incident.incidentId() +
                               "@" + incident.service();
    String impactBand = impactBand(incident.impactedUsers());

    if (executiveAudience) {
        return "EXEC SUMMARY | incident=" + incidentReference
                + " | severity=" + severity
                + " | impact_band=" + impactBand
                + " | impacted_users=" + incident.impactedUsers()
                + " | owner=" + 
                      mitigationOwner(incident.mitigationOwner());
    }

    return "Engineering update for incident " + incidentReference
            + " in " + incident.region()
            + " is currently " + severity + ", impacting about " + incident.impactedUsers() + " users. "
            + "Impact band is " + impactBand + ". "
            + "Mitigation owner is " 
            + mitigationOwner(incident.mitigationOwner()) + ".";
}

When a method takes a flag like executiveAudience, it couples the caller to the callee’s control flow in a way that is both brittle and easy to underestimate. This causes problems for both callers and the implementing class:

• Implicit knowledge: The client must know that true means “use the executive version” and false means “use the engineering version”. That’s a weak API with hard-to-decode knowledge that does not belong at the call site.

• Low cohesion: Mostly, control coupling is just the messenger telling us that we are packing multiple concerns into a single method. This in turn leads to code that’s harder to reason about and fragile to change.

The cohesion problem is obvious in the preceding incidentUpdate method. Its name suggests composing an incident update, but that’s not what it does. It composes one of two different kinds of updates, each with its own policy and audience. Once those two responsibilities are forced into the same function, the caller has to participate in choosing between them.

Subscribe now

The solution is to make that choice explicit. We do that by turning to another classic design pattern -- Strategy.

The core intent of Strategy is to encapsulate interchangeable behavior behind a common contract so the choice can vary independently from the code that uses it. You see, a boolean flag is often a compressed strategy. Instead of compressing behavior into a boolean, we now name it and make the variation point explicit.

We transform the original code by first encapsulating each choice in distinct classes:

// This is the API for our specific Strategy classes:
public interface IncidentAudience {
    String composeUpdateFor(Incident incident, 
                            IncidentNarrative narrative);
}

// All knowledge on how to compose for Executives goes here:
private static final class ExecutiveAudienceUpdate implements IncidentAudience {
    @Override
    public String composeUpdateFor(Incident incident, 
                                   IncidentNarrative narrative) {
        return "EXEC SUMMARY | incident=" + narrative.incidentReference()
                + " | severity=" + narrative.severity()
                + " | impact_band=" + narrative.impactBand()
                + " | impacted_users=" + incident.impactedUsers()
                + " | owner=" + narrative.mitigationOwner();
    }
}

// ...and this class encapsulates knowledge of how to 
// communicate with Engineers:
private static final class EngineeringAudienceUpdate implements IncidentAudience {
    @Override
    public String composeUpdateFor(Incident incident, 
                                   IncidentNarrative narrative) {
        return "Engineering update for incident " 
                + narrative.incidentReference()
                + " in " + incident.region()
                + " is currently " + narrative.severity() 
                + ", impacting about " 
                + incident.impactedUsers() + " users. "
                + "Impact band is " + narrative.impactBand() + ". "
                + "Mitigation owner is " 
                + narrative.mitigationOwner() + ".";
    }
}

// Now we create the strategy objects.
// We expose the existing audience objects as a 
// convenience for callers.
// That gives us a simple first refactoring step.
// This is a safe step as long as the strategy objects are stateless:
public static final IncidentAudience EXECUTIVE_AUDIENCE = new ExecutiveAudienceUpdate();
public static final IncidentAudience ENGINEERING_AUDIENCE = new EngineeringAudienceUpdate();

Yes, there is a bit more code than before. So what do we gain?

The real payoff appears in the original function, which can now simply delegate to the selected audience:

// The original method is now significantly simpler 
// as it only delegates to the strategies that 
// encapsulate the concept that varies.
public String incidentUpdate(Incident incident, 
                             IncidentAudience receiver) {
    IncidentNarrative narrative = narrativeFor(incident);
    return receiver.composeUpdateFor(incident, narrative);
}

In the original version, the method itself selected behavior internally based on a flag. The refactoring shifts that responsibility to the caller, who now selects an IncidentAudience. The branch disappears because the design now models the distinction directly.

The improvement is immediate at the call site:

• Before: incidentUpdate(incident, true).

• After: incidentUpdate(incident, EXECUTIVE_AUDIENCE).

The first forces the reader to remember what true means. The second communicates policy and explicit intent.

Bonus: Simplifying the Contract

There is a broader lesson hidden in this refactoring.

As part of the refactoring, we did the following move to introduce a simple domain type:

private static IncidentNarrative narrativeFor(Incident incident) {
    return new IncidentNarrative(
            severityLabel(incident.severityLevel()),
            incident.incidentId() + "@" + incident.service(),
            impactBand(incident.impactedUsers()),
            mitigationOwner(incident.mitigationOwner())
    );
}

private record IncidentNarrative(
        String severity,
        String incidentReference,
        String impactBand,
        String mitigationOwner
) {}

Let’s compare how this type impacts the code:

// We went from this original code:
public String incidentUpdate(Incident incident, 
                             boolean executiveAudience) {
        String severity = severityLabel(incident.severityLevel());
        String incidentReference = incident.incidentId() + 
                                   "@" + incident.service();
        String impactBand = impactBand(incident.impactedUsers());
        // -- implementation --
}
// ...to this more expressive version that introduces 
// a basic domain type:
public String incidentUpdate(Incident incident, 
                             IncidentAudience receiver) {
    IncidentNarrative narrative = narrativeFor(incident);
    return receiver.composeUpdateFor(incident, narrative);
}

Introducing the domain type IncidentNarrative is a move in the right direction because it makes the strategy contract clearer. Each audience now receives the source incident plus a small domain object containing the shared interpreted facts. That keeps the strategies focused on message shape rather than repeated preparation work. It sharpens the boundary of the new design.

Of course, our string-heavy data record may not win any beauty contests. But it is still a clear improvement over the original.

We could obviously have introduced domain primitives for the other concepts like severity and owner, too. But I’d rarely do that in the initial refactoring iteration, and I want these articles to highlight the often imperfect intermediate steps of reshaping existing code.

Perfection is the enemy of getting things done. Especially in software design. The important part is to move the code in a direction where the next change becomes easier to reason about than the previous one. And this refactoring did just that.

Why this helps human review

Flag arguments force the reader to mentally split a method into hidden modes, causing friction that accumulates across a codebase.

Strategies replace that hidden mode switch with named behavior that tells us directly what the code does.

The additional introduction of a domain type helps for the same reason. It turns a cluster of derived values into one named domain concept, which reduces the amount of detail a reviewer must juggle while reading the implementation.

Why this matters in AI-first development

Boolean flags are cheap for humans to write and expensive for models to interpret.

A boolean flag carries little semantic information on its own. The model has to scan additional code and context to infer what behavior the argument selects. That is a weak interface.

By contrast, named strategy objects like EXECUTIVE_AUDIENCE and ENGINEERING_AUDIENCE expose meaning directly at the call site. The model can immediately see which policy is being used. That improves local reasoning, narrows edit scope, and makes automated refactoring safer.

The same applies to the introduction of the domain type. It’s a refactoring that not only encapsulates data, but also raises the semantic abstraction level by aligning behavior with the domain concept it belongs to. That delivers explicit intent by explaining the code’s purpose structurally.

As is often the case with strong refactorings, our code ended up supporting the Open-Closed Principle. If we need a new audience later, we add a new IncidentAudience implementation rather than reopening a long method and editing its internals. That matters to an AI for the same reason it matters to humans: extension becomes more local and less risky.

The power of programming languages: implementation choices

The refactoring in this chapter uses small classes to model the strategies. But that is not the only way to implement the idea.

In functional programming languages, where functions are first-class citizens, strategies are created with even less ceremony. This means a call site can stay explicit while remaining very small. Here’s how it would look in Clojure:

;; Use partial function application to pre-bind the incident to the update:
(def update-on-incident-for (partial incident-update incident))

;; Now we can produce updates with a minimum of syntactic ceremony:
(update-on-incident-for executive-audience)
(update-on-incident-for engineering-audience)

In Java, C#, or C++, we can use a similar lightweight variant by representing each strategy as a method reference instead of a dedicated class. That saves some implementation classes. The tradeoff is mostly one of readability and expressiveness: method references are lighter, but named classes can carry domain meaning more clearly when the policies deserve first-class names.

Recommendation: use lightweight method references for internal strategy objects that aren’t exposed via the class’s public API. Prefer a proper class hierarchy for public APIs, avoiding any syntactic noise.

This implementation variant leads us to an important point: a design pattern doesn’t prescribe a specific class hierarchy or implementation technique. The preceding strategy implementations all stick to the original design idea. Rather, the important part of a pattern is its intent and trade-offs. Use the implementation form that is best suited to what the problem calls for.

One more step toward AI-readable code

This refactoring demonstrates several of the CLEAR principles in practice.

• Replacing the boolean flag with explicit strategies improves Local Reasoning by making behavior visible at the call site.

• Discovering and naming the concepts that vary strengthens Conceptual Alignment.

• Exposing behavior structurally improves Explicit Intent.

• Decoupling the specific from the general helps Reduce the Edit Surface for future extensions.

Like the other refactorings in this series, the goal is to make the code more explicit about the problem it solves. That benefits both humans and machines.

I wanted to capture those principles in a more memorable format. So, let me introduce CLEAR: a small set of design principles for AI-readable codebases.

Isn’t SOLID enough?

Yes, I know. We already have SOLID. But SOLID was created in a different era, with a different optimization target.

AI-assisted development introduces a new bottleneck: reconstruction work.

Think of a service. It can follow SOLID perfectly while still scattering one feature across ten files and three abstraction layers. A human can eventually piece that structure together. An agent has to infer it from local context. The less obvious our software design, the more fragile the task. At best, we “only” waste tokens. More often, we stare at the resulting merge nightmare and need to weed out bugs and mistakes. That’s exhausting.

Agents infer structure by search, tool use, and guesswork statistical probabilities. That means code can follow SOLID and still be difficult for an agent to reason about if intent, ownership, and change boundaries remain implicit.

CLEAR focuses on that problem.

Where do the principles come from?

The principles come from my experience of building both new AI-native products as well as extending older, more mature, codebases. Using 100% agentic coding.

On my company blog, I’ve pointed out the need to safeguard AI-generated code. We need to erect similar guardrails for design and architecture.

However, the guardrails for design and architecture have to be mouldable and adaptable to the problem domain and its context. When it comes to architecture and design, there are thousands of potential solutions for each problem. Good design constrains the solution while balancing the trade offs.

In fact, great software design is itself part of the safeguard system.

Hence principles rather than rules.

The Five CLEAR Principles

C — Conceptual alignment

Align behavior with the domain concepts it belongs to.

L — Local reasoning

Enable reasoning from local context for humans and agents.

E — Explicit intent

Explain the code’s purpose structurally.

A — Avoid search luck

Similar problems should be expressed using consistent structures, patterns, and extension points.

R — Reduce the edit surface

Design to contain change by making boundaries explicit.

These five principles define AI-readable code:

AI-readable code makes software safer for agents to evolve and cheaper for humans to verify.

A Common Language for Evolvable Systems

The unifying goal behind these principles is to limit the blast radius during software evolution. Each principle tackles a different part of that challenge.

Conceptual alignment and Explicit Intent align the code with the problem domain, making responsibilities visible in the structure itself. Local Reasoning asks how much context agents need to understand for a change. Avoid Search Luck is about guiding via consistent architecture and design patterns, whereas a principle to Reduce the Edit Surface focuses on limiting risk and verification effort by containing the resulting code changes.

So far, my articles focused on the first three, the CLE. My next posts will explore the AR part. Since aligning behavior with the problem domain is one of the hardest design challenges, I’ll revisit the C with deeper guidance and examples, too.

My ambition is to evolve and clarify these principles by demonstrating how they let us achieve better agentic coding outcomes. I do so by leaning into research on AI, LLMs, and software in general. We work in an opinionated field, and I always found that it pays off to go for proven fundamentals.

So this is not novelty for its own sake. It’s about prior work that becomes more important in an agentic context. Upcoming articles revisit classics like Tell Don’t Ask, the Law of Demeter, DDD, and Parnas’s Information Hiding through that lens. Along the way, we’ll also discard a few popular ideas that have run their course.

The CLEAR ideas were important back in the days of human programmers, too. Now that agents accelerate the pace of coding, the principles become vital. Software design is more important than ever. And any code that requires reconstruction work (and luck) to modify becomes progressively harder to evolve.

CLEAR is an evolving attempt at capturing guidelines for that reality.

Examples: CLEAR in practice

Let me end by paying homage to Linus’s immortal words: “Talk is cheap. Show me the code.”

As pointed out, the ideas behind CLEAR are present in many classic design principles. The following articles explore specific design examples through an agentic lens:

• Conceptual Alignment: Make the Domain Explicit: From Procedural Mess to Local Reasoning

• Local Reasoning: Reveal Intent in Complex Conditions

• Explicit Intent: Hidden Design Decisions: Refactoring Control Coupling

• Avoid Search Luck: Upcoming article on why agents fail when similar problems are solved inconsistently across a codebase.

• Reduce the Edit Surface: Upcoming article on designing systems where change stays local and verification manageable.

A good example of that pressure is merge conflicts. Merge conflicts seem to have their heyday now. And teams are experiencing them at agentic speed.

Merge conflicts as a socio-technical signal

The reaction so far seems to be to double down on better PR tools. Stacked PRs, multi-queue systems for PRs, intelligent conflict resolution, and much, much more. It’s all interesting, but also clear that we’re patching symptoms, rather than fixing the root cause.

So, let me go out on a limb and claim that recurring merge conflicts are a sign of socio-technical problems. And it doesn’t matter that the social agent is an, well, agent.

Yes, the people organization plays a large part, too. Team boundaries, branching strategy (the less, the better...), and ownership all contribute. But the root cause is often technical. When that’s the case, no matter how you re-org, the fundamental problems stick. No org chart can dig you out of an architectural blob.

The secret to parallelizing work

As Fred Brooks pointed out in The Mythical Man-Month, software work stops scaling linearly once tasks depend on each other. Specifically, coordination work grows quadratically: the number of communication paths becomes n(n-1)/2, where n is the number of people involved. Work will stall, be it via merge conflicts, review bottlenecks, or — common in the past — “sync” meetings.

That works in reverse, too. Development work can - and should - be parallelized when it represents independent tasks with similar relevance and urgency. However, to be effectively parallelizable, those tasks typically have to be independent at the level of the problem domain.

Subscribe now

How software architecture supports development work

And that’s where architecture comes in: that independence has to exist in the code, too. This means aligning the code with concepts from the problem domain: separate features, workflows, or product capabilities also need separate homes in the solution design. Otherwise, chances are that two seemingly independent tasks end up touching the same part of the code.

Recurring merge conflicts are the canary telling you that there is a misalignment between a) the work you do, and b) the type of work your architecture supports.

We only need to look at the leaked Claude Code repo to see the problem. Look at virtually any interesting part, and you’ll see how behavior seemed to converge in the same places.

The preceding extractToolStats() is a perfect example of architectural convergence. Git analytics, diff calculations, telemetry, UX timing analysis, and more, all accumulate in the same orchestration flow.

This means unrelated changes inevitably collide in the same function, simply because the poor modularity gives many reasons for agents to touch not only the same file, but even the same function. Under those conditions, it’s no wonder that we run into merge conflicts.

An old problem in agentic clothes

Fair enough, this type of misalignment is not a new problem, either. If you scaled up a human team on top of the same architecture, you would run into the same coordination pain, as experienced by countless projects ignorant of Brooks’s Law. The difference is speed. When it comes to merge conflicts, GenAI truly delivered on the 10x promise.

That is also where behavioral code analysis becomes interesting. If the same areas of the codebase keep attracting parallel work, recurring merge conflicts are a signal. They tell you where the boundaries in the code no longer support the work being done. The structure of the codebase might still look sound at a quick glance, but your change patterns tell a different story.

Shine a light on coordination costs in the code

Behavioral code analysis to the rescue; it reveals where parallel work repeatedly converges.

• Hotspots show where the system attracts change pressure.

• Coordination analysis reveals where many contributors compete for the same areas.

• Change coupling exposes architectural boundaries that fail to support independent evolution.

Together, those analyses make coordination costs in code visible.

Acting on behavioral data

A behavioral code analysis won’t tell you what to do. It’s evidence and priorities, leaving the resolution to you. Depending on what the analysis reveals, those next steps might be more or less painful.

Examples include:

• Heavy author congestion in a hotspot: Frequently, the root cause is technical. Lack of modularity, low local cohesion, with too many business responsibilities squeezed into the same module. When that’s the case, break the hotspot apart along domain boundaries.

• Change coupling in a local cluster: A typical sign of low package cohesion. Here, the solution might be to combine code spaced out in various files into the same unit and/or package.

• Change coupling across distinct architectural elements: This is a bad one. It usually indicates erroneous architectural boundaries, with the most common cause being a technical separation of concerns (thin: MVC or MVP style patterns), rather than a system where the building blocks communicate domain concepts.

Granted, none of those fixes are quick. But absolutely necessary. Otherwise we’ll keep grasping for tools that can relieve symptoms while the disease keeps spreading. When that happens, those parallel agents are no longer delivering value faster. Instead, there’s a serial bottleneck in the system, and it becomes the limiting factor.

References

The behavioral code analysis techniques are captured and described in:

• Software Design X-Rays: Fix Technical Debt with Behavioral Code Analysis

• Your Code as a Crime Scene

This article explores SDD through the lens of someone who lived through modelling days past. I acknowledge that “this time it might be different”, so I’ll focus my concerns on the flawed idea that implementation is the mere execution of a known scope. Rather, implementation is an essential part of the discovery process itself. And the further we remove ourselves from it, the harder it becomes.

Quick recap: what is SDD?

The idea with SDD is to capture the intended behavior in a structured specification. We then let a coding agent execute the resulting tasks and generate design docs, etc., in the process.

Yet, as Birgitta Böckeler points out, SDD seems to come in several forms. It can be anything from a relatively lightweight way to drive agents to a strong form where the spec itself is the ground truth. It’s the latter I’m concerned with.

The risk is that SDD becomes the latest iteration of an age-old manager dream: have your skilled seniors specify what to build, then pass it on to the seemingly simpler “implementation” while pretending that step is predictable and somehow less important. In the 1990s, “implementation” meant a team of coders kept in the dark. Today, it’s obviously agents.

The process didn’t work well back then. As both the pace and expectations on a software delivery are orders of magnitude higher now, I’m sceptical about how well SDD will work this time around. Not due to waterfall thinking — many SDD practitioners evolve their systems iteratively — but rather due to the nature of problem solving.

The pull: a need for predictability

Software development is at a crossroads. The best possible outcome of the agentic revolution is that we raise the bar for software engineering. We know what’s good for us: strong automated test suites, continuous delivery, small increments, modular architectures, and top-notch code quality.

We also know that GenAI is stochastic. But so too is a group of humans collaborating on software. And if history taught us anything, the solution isn’t just better input but also faster feedback loops. Let me elaborate by travelling back in time to the model wars.

The Emperor’s new executable clothes

SDD is strongly reminiscent of the Model-Driven Architecture, Executable UML, and the glorious Rational Unified Process (RUP) of decades (fortunately) long gone.

Early in my career, I used these technologies at two different companies. In the first one, we had an effective design review process. As a developer, I’d basically sketch out the software design as a UML class diagram, complement it with some sequence diagrams for the dynamics, and did a walkthrough for my peers.

Yes, the process was slow. But what we designed usually worked as a direction on what to implement. The real advantage, though, was that the resulting UML diagrams served well for onboarding and extensions. It was easy enough to get the high-level view of the solution, which helped when later drilling into the code.

Subscribe now

So far so good. Then came the tool vendors. I mean, if you’ve already sketched out your design, why not take it full circle and generate all code from that sketch? After all, code is just an implementation detail, right? All that was needed was to extend UML with an “action language” to capture those “details”.

How well did it work in practice? Oh, the first victim was the documented design. The executable diagrams turned so bloated and verbose that they became literally incomprehensible. After all, the new audience was a compiler, not humans.

Changes and extensions got painful. You see, all those power tools we’ve gotten used to — build pipelines, command line utilities, IDEs, linters, etc. — didn’t exist in the vendors’ design tools. Imagine coding in a Microsoft Word document. That’s how it felt.

The cognitive perils of a strong spec

Tooling was only part of the model-driven fiasco. A stronger problem was the process mindset at that time. Agile was brand new, and few people were familiar with the movement outside narrow programmer circles. Virtually every company I worked with operated in waterfall mode.

However, back then, the expectations on a software delivery were quite different. Today, with daily deployments being the standard, we just cannot afford to be slow in acting on feedback.

Human problem solving is inherently iterative and driven by reflection in action. We learn by doing. Express an idea in code, test it out, observe, and learn. The cycle expands our understanding of the problem we’re trying to solve. That improved understanding is then translated into modifications to the program, which we in turn observe and learn from. Rinse and repeat. We just cannot short-circuit that.

No, I don’t mean that we shouldn’t think things through early on. We should. And we should write stuff down to make it more concrete and invite a conversation. That helps thinking, too. But we need to treat that document as an imperfect starting point rather than the finished product.

The most underestimated aspect of code: requirements explosion

The main challenge starts if we work from a spec as if the problem was already understood. The reason is the concept of requirements explosion. The term was first coined by Robert Glass. Glass argues that “for every 10-percent increase in problem complexity, there is a 100-percent increase in the software solution’s complexity.”

In other words, each requirement in the spec will lead to tens of implicit design requirements that need to be resolved. We cannot leave that as guesswork for an agent to figure out.

To make SDD work, we would have to provide directives that let agents resolve a large share of all those implicit requirements.

So, couldn’t we complement our spec with a detailed solution model? We could. But it would lead us on a march with three major obstacles:

1. Free text lacks precision. Yes, we can explain constraints, etc., in text, but that becomes verbose and hard to check. Even structured prose and checklists leave room for ambiguity. That’s why we have programming languages. Those are excellent at capturing precise rules intended for machines.

2. We cannot know the solution requirements up-front. Remember: we learn by doing. And if we don’t and rather have agents make those decisions for us, it becomes orders of magnitude harder to derive and capture the solution requirements. Think reverse engineering a legacy codebase. That’s the position we’d be in. Constantly.

3. Extending requirements specs with implementation details and contracts blurs the model: This is what hit hardest back in the MDA/UML days: the model starts to become the implementation and loses its value as an overview, a different level of abstraction. Code just needs another level of precision.

The moment a model becomes the implementation, it ceases to be a good model.

The other road ahead

SDD is something I’ll continue to observe but sit out on for now. However, that doesn’t mean I don’t value structure and a certain predictability. It just means we should look for those qualities elsewhere.

Predictable progress rests on domain expertise, intention-revealing software design, automated safeguards for our code and its behavior, and rapid visual feedback, all amplified by a highly skilled team. Those capabilities are harder to grow than a spec. But they are also far more valuable. With or without SDD.

This is also why long procedural methods make coding life harder for agents. It’s not necessarily length per se, but rather that the longer the method, the more likely that it mixes multiple actions and responsibilities into one weakly described unit. That will confuse any agent.

However, detecting and recognizing a problem is only the start. The harder part is to act on it, and reshape the design in an agent-friendly way. As is often the case with software design, there’s an infinite number of potential paths. The proper choice depends on the problem at hand.

So far, we have looked at simplifying selection logic and transforming long IF-chains into rule pipelines. Now we’re going to expand our refactoring arsenal by taking on the problem of code that squeezes multiple side effects and business rules into the same long function.

Here’s our starting point: (Take a deep breath — it’s a long one)

public void handleCase(
  BackofficeCase backofficeCase, 
  SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();

    if (normalizedTaskType.equals("refund")) {
        sideEffectPort.appendAudit("case:refund:" + backofficeCase.accountId());

        if (backofficeCase.amountCents() <= 0) {
            sideEffectPort.appendAudit("refund:ignored_non_positive_amount");
            return;
        }

        if (backofficeCase.vip() && backofficeCase.amountCents() <= 20_000) {
            sideEffectPort.issueRefund(
                 backofficeCase.accountId(),
                 backofficeCase.amountCents());
            sideEffectPort.sendEmail(
                 backofficeCase.email(), 
                 "refund-approved-fast-track");
            sideEffectPort.appendAudit("refund:vip_fast_track");
        } else if (backofficeCase.hasOpenDispute()) {
            sideEffectPort.sendEmail(
                backofficeCase.email(), 
                "refund-needs-manual-review");
            sideEffectPort.appendAudit(
                "refund:manual_review_dispute");
        } else {
            sideEffectPort.issueRefund(
                backofficeCase.accountId(), 
                backofficeCase.amountCents());
            sideEffectPort.sendEmail(
                backofficeCase.email(), 
                "refund-approved-standard");
            sideEffectPort.appendAudit("refund:standard");
        }
        return;
    }

    if (normalizedTaskType.equals("welcome")) {
        // ...lots of code for the welcome flow...
        return;
    }

    if (normalizedTaskType.equals("ban")) {
        // ...lots of code for the ban flow...
        return;
    }

    if (normalizedTaskType.equals("export")) {
        // ...lots of code for the export flow...
        return;
    }

    sideEffectPort.appendAudit(
       "case:unknown:" + backofficeCase.caseType());
}

That’s a lot. The preceding code seems to handle different kinds of backoffice work. We see that a refund case issues money back and sends an approval email, whereas the welcome case would send onboarding material, and so on. The method is non-trivial.

Part of the challenge is that the outcomes of the distinct steps aren’t uniform values. Rather, they represent workflows and tasks that need to be performed.

Subscribe now

This is where the design pattern Command becomes useful. Instead of letting the method contain every possible choice, we encapsulate each business rule as a distinct executable unit.

The first step is to move the logic for each task into domain-named command objects:

private static final BackOfficeTask PROCESS_REFUND = new ProcessRefund();
private static final BackOfficeTask SEND_WELCOME_PACKAGE = new SendWelcomePackage();
private static final BackOfficeTask EVALUATE_ACCOUNT_BAN = new EvaluateAccountBan();
private static final BackOfficeTask EXPORT_ACCOUNT_DATA = new ExportAccountData();
private static final BackOfficeTask HANDLE_UNKNOWN = new HandleUnknown();

private static final List<BackOfficeTask> DOMAIN_COMMANDS = List.of(
        PROCESS_REFUND,
        SEND_WELCOME_PACKAGE,
        EVALUATE_ACCOUNT_BAN,
        EXPORT_ACCOUNT_DATA
);

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();
    commandFor(normalizedTaskType).execute(backofficeCase, sideEffectPort);
}

We’ll go over the details and mechanism soon, but note how the offending handleCase method went from potentially hundreds of lines to just two lines of code. What happened?

Well, we introduced a small command model around the existing logic:

• BackOfficeTask is a shared abstraction for executable pieces of backoffice work. A pure interface.

• ProcessRefund, SendWelcomePackage, EvaluateAccountBan, and ExportAccountData are concrete tasks, each owning one business rule family.

Their implementation is straightforward:

private interface BackOfficeTask {
    // purpose: selection -- is this the task to execute for the given input?
    boolean supports(String normalizedTaskType);

    // purpose: behavior -- encapsulates the logic and actions for a specific task.
    void execute(BackofficeCase backofficeCase, SideEffectPort sideEffectPort);
}

private static final class ProcessRefund implements BackOfficeTask {
    @Override
    public boolean supports(String normalizedTaskType) {
        return normalizedTaskType.equals("refund");
    }

    @Override
    public void execute(BackofficeCase backofficeCase, 
                        SideEffectPort sideEffectPort) {
        sideEffectPort.appendAudit(
            "case:refund:" + backofficeCase.accountId());
        // existing refund logic preserved here
    }
}

Like any design pattern, there aren’t any fixed rules or structure for what the implementation shall look like. Rather, we need to adapt the pattern to our context.

In this case, we do a simple linear search of the supporting command to match a given input task:

private static final List<BackOfficeTask> DOMAIN_COMMANDS = List.of(
        PROCESS_REFUND,
        SEND_WELCOME_PACKAGE,
        EVALUATE_ACCOUNT_BAN,
        EXPORT_ACCOUNT_DATA
);

private static BackOfficeTask commandFor(String normalizedTaskType) {
        for (BackOfficeTask command : DOMAIN_COMMANDS) {
            if (command.supports(normalizedTaskType)) {
                return command;
            }
        }
        return HANDLE_UNKNOWN;
    }

DOMAIN_COMMANDS is a list of known tasks, and commandFor(...) is the selector that finds the matching task for the current case type. This structure is a form of responsibility chain where each command decides if it applies. (It’s also an example on combining multiple patterns in one solution).

The HANDLE_UNKNOWN command acts as a safe default. It represents a variation of the Null Object pattern, ensuring that the system always has a valid command to execute, even when no specific case matches.

he original handleCase(...) method is now an orchestrator, delegating the actual work to the selected task instead of containing every branch itself:

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType()
                                               .trim()
                                               .toLowerCase();
    commandFor(normalizedTaskType).execute(
       backofficeCase, sideEffectPort);
}

That is the first benefit. Whereas the original method was organized around branching, our refactored version is organized around domain tasks.

Note A natural next refactoring would be to remove the string-based selection entirely. We’ll do just that at the end of the article. For now, let’s bear this pain together.

Why this helps human review

The long-method version forces the reader to keep several different concerns active at once.

While reading handleCase, you are not just tracking which branch applies. You are also tracking what kind of business action each branch performs and which side effects belong together. That is a bad fit for human working memory. Further, code that lacks cohesion also increases the risk for unexpected feature interactions: one branch changes a shared state, triggering downstream failures.

Distinct commands reduce that cognitive load by turning the large procedural mess into named chunks. The resulting command objects become cognitive units for reasoning. The reviewer can understand the dispatcher as one concern and each business rule as another. Future extensions are now likely to be additions rather than complex edits of a large block of code.

Why this matters in AI-first development

In the original method, the model has to infer that a cluster of statements represents a refund decision, a welcome flow, etc. The refactored code stops making the model reverse-engineer intent from branch shape by giving the code an explicit semantic structure. Those building blocks are now explicit domain actions.

The structure reduces ambiguity and guides both planning and modification. If an agent needs to change export behavior, ExportAccountData is the obvious unit to inspect. If it needs to reason about refund policy, ProcessRefund is the unit. The edit surface becomes narrower, and the risk of collateral changes drops.

Bringing the solution structure closer to the problem domain serves the translation from prompt to desired outcome.

This is the core idea behind refactoring towards AI-friendly code: make meaning explicit before asking the model to work with it.

Design guardrails

Use this refactoring pattern when a method coordinates several distinct actions with different side effects and/or workflows:

• Preserve business logic while moving code into commands.

• Keep the public API unchanged during the initial transformation.

• Name concrete commands by domain purpose, not architectural suffixes.

• Let each task encapsulate its side effects.

From domain actions to stronger API: evolving the design

Often, introducing explicit commands reveals further possibilities to simplify. As an example, take another look at our refactored code:

public void handleCase(BackofficeCase backofficeCase, 
                       SideEffectPort sideEffectPort) {
    String normalizedTaskType = backofficeCase.caseType().trim().toLowerCase();
    commandFor(normalizedTaskType).execute(backofficeCase, sideEffectPort);
}

Right now, the commands are an implementation detail inside that class. That’s usually a good start, allowing us to optimize for local reasoning.

However, I often find the commands themselves might be part of a stronger API. So what if we start to expose these objects directly to the calling client?

// refactoring note: we now accept a Task rather than a stringly typed 'case'
public void handleCase(BackOfficeTask taskToPerform, 
                       SideEffectPort sideEffectPort) {
    taskToPerform.execute(sideEffectPort);
}

In the preceding code we did just that: we shifted the API to accept a generic BackOfficeTask rather than having to create it ourselves. A nice side effect is that we get rid of the nasty task normalization with its complex and accidental string manipulations. (That is, getting rid of backofficeCase.caseType().trim().toLowerCase() — What’s not to like about that?)

The reason this usually works well as the next refactoring step, is because at the call site, context tends to be obvious; we know if we want a refund, send a welcome package, or export data. So why not take advantage of that contextual knowledge in the API responsbile for the corresponding actions?

As an added benefit, that improved API would also align with the Open-Closed Principle, meaning new clients can extend the program with new types of tasks without modifying the code processing them. Coding agents generally perform well in code with clear intent and a consistent structure that naturally communicates its extension points. The more explicit the structure, the less reconstruction work to perform.

And now you’re reading this article. So a fair question is: is there a real person with their own experience and views behind it? Assuming the answer is “yes”, why would that matter?

What follows is my list of ingredients for Code for Humans and Machines. It explains how I work with AI as well as the consequences of outsourcing writing to it. Ultimately, it ties into the purpose of writing, which should go deeper than content production.

Does it matter if content is AI-generated?

Yes.

AI-written content has a peculiar flavour. LLMs employ several advanced stylistic devices. These give AI content its tell-tale signs, serving as mental cues to immediately scroll past. It’s not about quality per se. More like: If it was effortless to produce, it simply carries less value.

That reaction is not just me. Research shows that we rate identical works as more valuable when we think a human, rather than an AI, created them: Humans versus AI: whether and why we prefer human-created compared to AI-created artwork.

Feelings aside, my main problem with AI-generated content is that it is so bland. Yes, individual sentences can be expressive, even snappy. But the overall effect is repetition, verbosity, and a lack of sharpness. Impressive in the small, exhausting at length.

Losing the benefits

Consuming LLM content is one thing. It poses an even larger challenge for the writer.

For decades, I’ve used writing to explore and understand various topics. Writing is an active process, and the very act of expressing an idea in text is itself a valuable way to learn.

I often start writing about topics I’d like to think I already master. Still, I frequently discover a gap in my understanding or an edge case I hadn’t considered. Writing is learning. LLMs take away that component.

That, too, is backed by research: writing is not just a way to report thought, but a way to develop it.

Subscribe now

How much AI do I use?

There’s a crucial difference here: I do use AI a lot, but not to generate articles.

Iterating on sample code

Most of my articles contain code samples. Historically, those samples have been time-consuming. Not only do I have to find relevant examples; the code also needs to exhibit a specific design problem. Coming up with artificial code examples is hard enough. Coming up with examples that are “bad” in a specific way is next-level hard.

AI largely automates that process. I can iterate on sample code, instruct the agent to make it more or less complex, and even ask it to amplify some code smell for illustrative purposes. I love that.

Research assistance

I’ve always made it a point to base my recommendations on research. The real, peer-reviewed kind.

In the past, a lot of that work was repetitive searches on Google Scholar and university databases, trying to identify relevant papers. After skimming too many not-quite-what-I-need papers, reviewer fatigue would kick in.

An agent is, of course, a superb support for these types of tasks. I use AI a lot to narrow down my search. I probably spend the same amount of time in total, but now the bulk of that time is spent reading and understanding relevant material.

Review and feedback loop

This is where AI shines. It’s good at identifying inconsistencies, and offers a rapid feedback loop.

90% of my writing is rewriting. The first draft is usually quick, but I do multiple iterations where I tweak, clarify, and try to improve the flow and structure. Continuous feedback is useful.

Unblocking writer’s block

I have a tendency to get stuck on certain parts of a text. I know what my message should be, but I cannot get into the proper writing flow. Here, AI is wonderful: I type down a stream of consciousness and ask the AI to refine it.

Ultimately, I tend to throw most of that generated text away. Occasionally, I keep parts that I tweak. But getting a starting point — even if imperfect — helps more often than not.

Indirect influence

AI impacts my work in other ways, too. I mentioned earlier how LLMs mimic advanced stylistic writing patterns. Think of lines like “It’s not only an X. It’s a Y,” or the classic em dash.

I actively minimize my use of these tricks. The LLM tendency to overuse the em dash in particular is a tragedy — I employed it heavily in my pre-GenAI writing.

Why I write

Writing with AI support is a more enjoyable process. However, writing that is meant to be read is still 95% human effort. Any attempt to short-circuit that process comes with a cost: bland text and a lost learning opportunity. It’s self-defeating.

At the end of the day, the personal question each writer has to ask is:

Why do I write?

They usually start small: one &&, a few ||,then one more clause to patch an edge case. Soon they have grown into little puzzles, but not for our amusement.

Every time someone reads such code, they have to reconstruct the intent from raw logic instead of seeing the business rule directly. What should be obvious becomes something you have to figure out.

Take this condition:

String tail = originalName.substring(i).toLowerCase();
if (tail.startsWith("admin") || tail.startsWith("owner") || tail.startsWith("root")) {
    return true;
}

Looking at that code, we can of course derive its meaning. But only after mentally parsing each clause, hold the alternatives in working memory, and then reconstruct the intent. We probably did not read it and think:

so simple — this checks for reserved role names

That reconstruction friction is exactly what good refactoring should remove. Starting from code like:

Read more

But there is a cost we are still underestimating. Agentic coding is mentally expensive.

I can usually sustain the pace for a couple of hours. Then I need a break. The pace is simply too intense. And based on conversations with other engineers, I do not think I am alone in that.

That is the trade I want to unpack here. Agents help us stay with the problem longer, but they also compress too many meaningful decisions into too little time.

The timeline collapse

Software development was always about making decisions. A typical product requirement quickly explodes into hidden design work that end users never see. Architecture, naming, boundaries, behavior, edge cases, test design, failure modes.

In the old days, say pre-2025, work unfolded at human speed, which meant the decisions were naturally spaced out. Today, agents compress the timeline. We have to deal with complexity and decisions that used to be spread over days in a single coding session.

But there’s more. Agentic coding raises the engineering bar, and we just cannot afford to slip. Like skipping e2e tests, ignoring problematic dependencies, or rebuilding library functionality we should have reused.

So we’re now a) facing more complex work, with b) a compressed timeline of decisions. No wonder agentic coding is draining.

Decision density and mental energy

What we are experiencing as modern developers is not new. It just shows up in a new context.

Psychology has studied the mental cost of decision making for decades. One of the most well-known concepts is decision fatigue. Decision fatigue says that the quality of our decisions deteriorates after a long session of continuous choices.

One of the most cited examples comes from judicial decisions. Danziger et al. looked at thousands of rulings and found that favorable decisions dropped as judges moved through a work session. Interestingly, the decision quality then recovered after breaks.

The Danziger study shows what depletion looks like in practice. Other studies suggest the mechanism: making choices is itself mentally expensive. Agents accelerate the arrival rate of those decisions.

Manual coding had a built-in pacing mechanism. That was our implicit recovery break. And it’s now gone.

Why this is hard on the brain

This lines up neatly with cognitive load theory.

Sweller’s classic work on cognitive load focused on problem solving. When too much information has to be held and manipulated at the same time, reasoning suffers. Agents might remove lower-level serial coding work, but they also increase the amount of high-level state you have to evaluate.

Working memory is limited too. You might have heard about the classic “seven plus or minus two” rule. Turns out that was over-optimistic. Modern cognitive scientists paint a more depressing picture: we can, at best, hold 3-4 things in our head at once and still be able to reason effectively.

Now, any non-trivial software task involves plenty of moving parts. Even with agents, we still have to decide which parts matter, how they interact, and whether the design still holds together. It’s a lot more architecture per minute.

Subscribe now

The interruption problem on steroids

We all know that traditional task switching is cognitively expensive. It harms our focus, and hurts performance.

However, what’s less known is that self-interruptions tend to be even more disruptive than external ones.

Coincidentally, agentic coding is like an open invitation for more self-interruption. The agent:

• asks a question,

• produces a diff,

• gets blocked by a missing tool,

• fails a test, or

• suggests a change that looks almost right but touches too much.

Each event pulls you into a new review-verify-steer decision.

The AI productivity paradox

This also helps explain why the productivity story around AI coding tools is more complicated than the marketing slides suggest.

One of my favourite studies gave experienced open-source developers access to AI tools. It was a controlled trial, so half the participants were still coding in the old school way.

At first glance, the study seemed to confirm the usual story: the developers with AI tools felt faster. Indeed, they claimed so themselves, estimating a 20% speedup. Only problem: they were not. They ended up 19% slower than the non-AI group. Adding insult to Big Tech injury, the study also demonstrates that even expert developers overestimate the AI impact on developer productivity.

One plausible contributor is self-interruption. Developers get many natural pause points: waiting, reviewing, correcting, etc. Each of those pulls you into a different task.

How I try to manage it

AI is now an integral part of our work, and we do not want agents to slow down. Speed is kind of their point.

But we do control when and how we actively interact with AI:

• The simplest tip is to keep agent tasks small and iterative enough so that the review fits in your head

• That includes designing for cognitive resourcefulness: automate everything that can be automated. (You don’t want to spend time reviewing coding rules, checking test coverage, etc.)

There are also things that I actively avoid doing:

• Don’t review details, verify them. This was a hard one personally, but we need to accept that we can no longer know every line of code. Again, automation and safeguards are the mechanisms for delivering trust, not manual inspection.

• Avoid parallel work. I typically have one long-running agentic maintenance task that I just babysit, and then one focus task. Never more.

That last point is important given the running-twenty-agents-in-parallel hype. I cannot even think about twenty meaningful things to build, and even less so about the resulting cognitive tax of the likely interruptions. It’s exactly the wrong thing to even consider. At least for humans. (And yes, I understand sub-agents and machine parallelisation. That is not what I’m objecting to. It is the parallelisation of human attention that does not scale).

Finally, and this will bring me enemies from the corporate ladder who think software is built by typing: take breaks from your agents. And take those breaks earlier than you think you need them.

Those breaks are not just recovery. They are also a chance to build the skills the new developer role demands. So use those non-coding hours to deepen your domain expertise. A few ways to do that:

• Train as an end-user. This is the single best way towards becoming a domain expert. Master the problem domain.

• Grab a coffee. Many of the best ideas come away from the laptop. Your brain needs the occasional change of setting. Under the hood, it keeps operating. (The majority of all brain activity is automated and subconscious). When you relax, your brain delivers its insights that were worked on in the background.

• Do exploratory testing. Yes, automation is great, but there’s no limit to the creative ways we humans can break a system. Make it a challenge.

• Understand your product metrics and usage patterns. What features are people using, what are they ignoring, etc. This gives a different perspective on your code. Promise.

• Get involved in sales. This one might not be for everyone, but technical sales is a challenging role that gives you a much deeper understanding of where your product needs to be.

The point is to re-invest the time agents save into activities that deepen your expertise while giving your brain a recovery window.

Agentic coding is still new. But it's becoming increasingly clear that the workflows around agents have to respect human cognitive limits. The future holds more software than ever, and we need to come prepared to build it in a sustainable way.

This pattern addresses that problem by turning branching logic into an explicit pipeline of rules. Instead of hiding decisions in control flow, we make them visible, ordered, and easy to change.

The previous pattern handled selection. This one handles workflows.

Consider the following code:

// NOTE: Simplified example to illustrate the core issue.
// Real-world versions are typically much larger and harder to reason about.

// Admin accounts are usually safe, unless someone tries to sneak weird separators into the raw name.
if (context.accountType().equals("admin") && !hasWeirdSeparators) {
    if (looksLikeImpersonation(normalizedName)) {
        logReview(100);
        return new ReviewResult(
                   "manual", 
                   "Admin-like username requires manual review");
    }
    auditRuleHit("ALLOW_SAFE_ADMIN_USERNAMES", context);
    return new ReviewResult("allow", "Admin username looks safe");
}

// 1. Block quoted fragments that may hide suspicious content
if (originalName.matches(".*\"[^\"]*\".*")) {
    logReview(101);
    notifyReviewQueue(context.userId(), "quoted-fragments");
    return new ReviewResult("manual", "Quoted fragments require manual review");
}

// 2. Block bracketed fragments that may hide tags or role names
if (originalName.matches(".*\\[[^\\]]*\\].*")) {
    logReview(102);
    String reason = originalName.contains("[admin]")
            ? "Bracketed role labels require manual review"
            : "Bracketed fragments require manual review";
    return new ReviewResult("manual", reason);
}

// ...think many more lines with conditionals and blocks...

if (normalizedName.contains("test") && normalizedName.length() < 8) {
    logReview(107);
    flagPattern(context.userId(), "short-test-username");
    return new ReviewResult(
               "manual", 
               "Short usernames containing 'test' require review");
}

return new ReviewResult("allow", "No suspicious username patterns detected");

So what’s the problem here?

The logic we are trying to express is a workflow. But the code does not say that. It hides the workflow inside a sequence of decisions, all compressed into a single method.

That style works right up until someone needs to change it. (And what good is code that an AI — or you — cannot safely change?) The consequence is that you cannot touch one rule without re-reading all the others, because the branching structure hides both order and intent.

The refactoring is simple: stop expressing policy as a branching maze and express it as an explicit decision pipeline.

After:

private static final List<ReviewRule> REVIEW_PIPELINE = List.of(
        ALLOW_SAFE_ADMIN_USERNAMES,
        REQUIRE_MANUAL_REVIEW_FOR_QUOTED_FRAGMENTS,
        REQUIRE_MANUAL_REVIEW_FOR_BRACKETED_FRAGMENTS,
        REQUIRE_MANUAL_REVIEW_FOR_REPEATED_PUNCTUATION_BEFORE_DIGITS,
        REQUIRE_MANUAL_REVIEW_FOR_INVISIBLE_CHARACTERS,
        REQUIRE_MANUAL_REVIEW_FOR_RESERVED_ROLE_NAMES,
        REQUIRE_MANUAL_REVIEW_FOR_LEADING_OR_TRAILING_UNDERSCORE,
        REQUIRE_MANUAL_REVIEW_FOR_SHORT_TEST_USERNAMES
);

public ReviewResult reviewUsername(SignupContext context) {
    for (ReviewRule rule : REVIEW_PIPELINE) {
        Optional<ReviewResult> reviewResult = rule.tryReview(context);
        if (reviewResult.isPresent()) {
            return reviewResult.get();
        }
    }
    return allow("No suspicious username patterns detected");
}

What we have done here is adapt the classic Chain of Responsibility pattern to a refactoring problem. The original formulation comes from the Gang of Four book, where a request is passed along a chain of handlers until one of them decides to handle it (Gamma, Helm, Johnson, and Vlissides, Design Patterns: Elements of Reusable Object-Oriented Software, Addison-Wesley, 1994). Here, we use the same core idea, but in a stripped-down and more explicit form: a linear sequence of small rules.

After this transformation, the logic and behaviour are driven by the table. Each rule in that table is simply a named method reference. Think of them as pointing to small rule methods. Here’s an example:

private static final ReviewRule REQUIRE_MANUAL_REVIEW_FOR_QUOTED_FRAGMENTS =
        Reviewer::requireManualReviewForQuotedFragments;

private static Optional<ReviewResult> requireManualReviewForQuotedFragments(SignupContext context) {
    if (context.originalName().matches(".*\"[^\"]*\".*")) {
        logReview(101);
        notifyReviewQueue(context.userId(), "quoted-fragments");
        return Optional.of(manual("Quoted fragments require manual review"));
    }
    return Optional.empty(); // Optional.empty means: this rule does not apply, pass to next rule
}

Each rule becomes a small, named method that does one thing. It either returns a decision or passes control forward.

Also, the rules might not be just predicates. They also own their side effects. Logging, auditing, and notifications now live next to the decision that triggers them.

Note that we kept the original logic and structure (we only changed the return shape to Optional so the workflow can be driven by the pipeline). There is still cleanup we could do in those rule methods, but we do that stepwise: first make structure and intent explicit, then iterate once everything works. Too-large refactoring steps are a reliable way to sidetrack an agent.

Implementation Tip: Go Functional

If you prefer a more functional style, you can also express the orchestration as a pipeline operation:

public ReviewResult reviewUsername(SignupContext context) {
    return REVIEW_PIPELINE.stream()
            .map(rule -> rule.tryReview(context))
            .flatMap(Optional::stream)
            .findFirst()
            .orElseGet(() -> allow("No suspicious username patterns detected"));
}

In C#, this maps naturally to LINQ; in Python, a generator-based first-match approach gives a similar shape.

I chose the explicit loop and if check in this chapter because it doesn’t require any detailed Java knowledge to follow, and because I prefer the pure simplicity of the more procedural form. Sometimes, a simple if is exactly what the doctor orders.

So the pipeline is not magic. It is just an ordered list of named decisions. The original logic is still there, but now encapsulated in stable and readable identities with their execution order controlled by the pipeline.

The Hard Part: Naming Rules

The challenging part in this refactoring is to identify the rules to extract and name. You might be fortunate to have comments explaining what the following code block does.

The original code has some of that: // 1. Block quoted fragments that may hide suspicious content.

But not everything is commented. Look at the final rule guarded by the if (normalizedName.contains("test") && normalizedName.length() < 8) { clause.

In the latter case, we need to go into detective mode and try to figure out the purpose and intent. (And the magic number 8 is not helping us here). Often, an LLM can help with the task -- language models are surprisingly good at naming things, a skill we humans struggle with.

Why this is better

In the conditional-heavy version, order is implicit in the branch clutter. In the refactored pipeline version, order becomes first-class data. You can point to the pipeline and answer immediately: “what runs first, what runs last, what short-circuits?”

That makes change less speculative. Add a new rule? Insert one pipeline entry and one method. Modify an existing rule? Open one dedicated method and stop there.

If that sounds familiar, it should. This is the same gain we saw in Express Selections as Tables. There, we refactored branching logic into a declarative lookup table. Here, we refactor decision logic into a declarative pipeline. In both cases, behaviour stops being buried inside control flow and starts being expressed as explicit structure.

That means extension becomes simpler and safer. They are now declarative changes. That matters to an AI agent too: the code now advertises where behaviour lives, in what order it runs, and how it can be extended without guesswork.

When to use this pattern

Use responsibility chains when:

• one method contains many policy checks,

• checks are mostly independent decisions,

• rule order matters,

• short-circuit behavior is desired.

Do not force this pattern everywhere. If conditions share heavy mutable state, or if you are selecting behavior families, strategy/polymorphism may be a better fit.

Design guardrails

To keep this refactoring honest:

• Preserve API and behavior.

• Keep the same decision order.

• Keep each rule narrow and intention-revealing.

A good litmus test is this:

If you cannot describe what a rule does in one short sentence, the rule is probably doing too much.

Why this matters in AI-first development

Conditional-heavy code consumes tokens without increasing information density.

LLMs have a limited attention budget. Every extra token competes for that budget, and unstructured control flow forces the model to spend it on reconstruction instead of reasoning. Such code burns more tokens than a Meta employee looking to land on the internal leaderboard.

Responsibility chains reverse that tradeoff. They convert implicit flow into explicit decisions. That reduces ambiguity, narrows edit scope, and makes automated transformations safer. All of that improves machine-readability:

• The orchestrator method is tiny, obvious, and stable.

• Rule intent is encoded in method names, not inferred from nested conditions.

• The agent can focus on one decision at a time instead of reconstructing control flow from a dense branch forest.

In other words: this is not just a stylistic opinion. It is about better geometry for change.

After more than 30 years as a programmer, I no longer code manually. Sometime in October 2025 I went 100% agentic, and I’m not planning on going back.

My agentic shift came after decades spent learning various programming languages, tools, and ecosystems. That’s a massive investment in skills that are now, at least partly, automated.

So what happens next? Will there even be such a thing as a software developer in a few years? Or will our profession go the way of the lamplighters and horse carriages?

This Isn’t the Same Job Anymore

Agentic workflows have moved us way past mere prompting and into something closer to delegation and orchestration. And that gives us a view of what lies ahead.

In the short term, two forces are pulling in opposite directions:

1. Automation reduces the need for manual coding, suggesting fewer software people.

2. Yet expanding system complexity increases the need for more builders.

My bet is on the second force exerting the strongest pull. There has yet to be a technological revolution that did not expand the scope of what we build. AI will not shrink software. The future will see more software than ever, as there’s an infinite — and growing — amount of tasks to automate via code.

The difference compared to earlier seismic shifts is the pace. The industrial revolution took roughly 80 years (1760-1840), giving society time to adapt. This time, we don’t get generations. We get months.

The Illusion of Instant Software

You probably see this in your LinkedIn and X feeds. They are filled with stories like building a Linux clone in Visual Basic by chatting to a Claude Code cluster over voice. While taking a bath. No prior coding experience. No deep technical background. Just a prompt and a generous supply of tokens.

Now, here’s the reality: Building the first prototype of a product or feature was always the easy part.

Roughly 95% of the cost of a software product occurs after the initial version is released. Turning a prototype into a stable, reliable, and evolvable system is where the real work starts. Shipping is optional. Maintaining is not.

Once you have users, you get pressure:

• new features,

• bug fixes,

• scaling concerns,

• integration challenges,

• and a constant need to evolve the system without breaking it.

AI does not remove that complexity. Building successful production software has never been easy, and it won’t suddenly become trivial. Design, architecture, and what to build — the hardest parts — cannot be automated.

The Objection: “AI will handle it eventually”

But wait: did I really say that not everything will be automatable? I did. And that usually gets the same response:

AI is improving rapidly. Soon it will be able to build and maintain complex systems on its own.

Usually stated in a flat, matter-of-fact voice, as if that settles it.

It’s an appealing idea. I also believe it’s flawed—for at least three reasons:

1. We keep raising the bar

If we had stuck to the problems of the 1970s, programming would already be trivial. We didn’t. Instead, we created better tools, languages, and abstractions to take on bigger and more complex problems. AI will likely do the same.

Tomorrow’s systems will be even more ambitious.

2. Many Real-World Systems aren’t AI-Ready

Most real-world systems simply aren’t ready for autonomous agents. Long-lived legacy systems are shaped by years of implicit assumptions and accumulated technical debt while still being business critical.

For an agent to perform well, data quality is key. And in software, code is the data. Most production codebases are inconsistent, under-tested, and full of edge cases that even humans struggle to reason about. Sure, AI is useful on legacy systems, but fully autonomous development remains a pipe dream at best.

3. You can’t bet your career on “soon”

You just shouldn’t bet your career on the hopes and promises of “soon”. Even if full autonomy eventually becomes possible, the real question is: When?

We’ve been hearing that “AGI is around the corner” for years. Maybe it is. Most likely it isn’t. (Coincidentally, the AGI narrative is pushed by people who happen to sell language models...and rely on external funding for them).

Personally, I’m not waiting. I’m preparing for a world where the developer role changes. I’d rather be early than obsolete.

Subscribe now

Coding is Dead

Agents are automating the act of writing code. It’s easy to feel threatened. Uncertainty about one’s professional future is a big drain.

But here’s the good news: Code has no intrinsic value. It never had. (We just built our careers pretending it did.)

Code is a means to an end. What matters is what the code enables—the system, the behavior, the product. And this is where the human developer comes in. Because that human role does not disappear. It shifts.

Developers in 2027: Two Emerging Paths

I see two emerging and complementary developer roles:

First we have the expert generalist builder. In an AI-first workflow, the expert generalist is responsible for:

• deciding what to build

• deciding how to build it (at the system level)

• breaking work into meaningful increments that can be delegated to agents

These responsibilities are not new. They have traditionally been split across:

1. product managers

2. software architects

3. technical leads

What’s changing is that these three specialist roles are collapsing into a single generalist role. No, it won’t be an easy job. Each one of those used to pay well in the past. Now one individual has to master them all. But for one salary.

Alongside that, I also see a second role emerging: the enabler.

The enabler is responsible for the meta-layer of development. The work that makes agentic development effective by:

• optimizing build and deployment pipelines

• capturing constraints and patterns in machine-friendly formats (think: present day SKILLs)

• improving testability and optimizing coverage

• refactoring legacy systems to make them AI-friendly

This role is not about shipping features. It is about enabling agents to build features well. As such, the enabler is a vital support role for the expert generalist.

But what about all our hard-won knowledge?

All your prior knowledge will serve you well in the AI age. Rather, the challenge is to keep on learning. Continuously.

To be an expert generalist, our learning and purpose needs to shift. Details aren’t as important as the larger picture. For example, it might be more important to know the type of problems and systems that are a good fit for the Rust language rather than mastering the borrow checker syntax. The former is a strategic tool, the latter a now automatable task.

Unfortunately, and these are the bad news, the future of development will probably not be for everyone. I met great programmers who code because they love to code. And now those days are gone, with no obvious financial incentive for bringing them back.

But another group of developers are likely to thrive. As much as I loved to code by hand, I enjoy agentic coding even more. To me, code was always about what I could make it do, not syntax, not craft, definitely not the typing. Agents get me there faster.

My main worries early on were around just problem solving: When machines carry out our execution, how can we still stay in the loop to maintain effective mental models of the problem we’re working on? You see, problem solving is not a one-way street. It’s a constant iteration between observing, expressing, and reflecting.

Agentic Coding: Supporting Flow

Surprisingly, I’ve found that agents can support and strengthen that flow. In the past, I could easily get sidetracked by secondary tasks. Like restructuring the emerging code. I had an idea in my head, but now I wasn’t working on it; I was working on supportive and related tasks, but not the core. With agents taking over the details, I find it much, much easier to maintain the high-level thought and iterate on it.

That said, there’s a flip side to it.

Software development is definitely more mentally effortful with agents.

Maintaining a constant focus is draining, and I find that I can usually only sustain that intense high pace for a couple of hours before needing a break. (Thankfully, I can let a long-running agent make progress while I sip coffee).

Final Thought: From Coding to System Design

With AI, the developer’s role shifts from writing code to designing systems that can evolve safely, with agents doing the grunt work. But agents won’t replace human taste when it comes to deciding what to build.

Taste is a human quality. And building the right system is going to be key. Faster coding? Not so much. It’s already a commodity.

Even if code no longer serves as a moat or job security, strong engineering remains a competitive advantage. Teams that succeed in this shift to agentic development will iterate faster and build better systems. This is where systems thinking and domain expertise come in. Knowing what to build and how to build it matters more than execution.

Throughout my decades in various software companies, I’ve seen plenty of promising products fail. Not due to any flawed product ideas, but rather due to buggy, sub-par code preventing organizations to ship when the opportunity was rife.

If there’s one truly good thing coming out of the agentic revolution then it’s this: for many, bad code might become a distant memory of times less enlightened. But mark my words: an AI won’t set you up for that success on its own. Developers who fail to adopt are likely to ship the same sub-par code, only faster. Because the future of software development will not be less engineering. It’s more engineering at a higher level of abstraction.

Take a switch statement where each branch selects a value and returns it:

switch (creature) {
    case DRAGON:
        return new SnackRecommendation("Charcoal-grilled marshmallows");
    case VAMPIRE:
        return new SnackRecommendation("Tomato juice on ice");
    case WIZARD:
        return new SnackRecommendation("Mystic instant noodles");
    default:
        return new SnackRecommendation("Chef special surprise");
}

When selection logic is encoded as branching, we force the reader to simulate the program to discover a simple fact: there is a direct mapping from input X to value Y.

A switch with a few case labels might not be the worst idea, but I’m confident that we’ve all seen switch-cases stretching over tens and hundreds of lines of code. Each time an agent wants to add a new case, it has to modify that function.

A better solution is to state the relationship between input and result value directly. A table does that:

private static final SnackRecommendation RECOMMENDATION_FOR_MYSTERIOUS_GUEST =
        new SnackRecommendation("Chef special surprise");

private static final Map<Creature, SnackRecommendation> RECOMMENDATIONS_BY_CREATURE = Map.of(
  Creature.DRAGON,  new SnackRecommendation("Charcoal-grilled marshmallows"),
  Creature.VAMPIRE, new SnackRecommendation("Tomato juice on ice"),
  Creature.WIZARD,  new SnackRecommendation("Mystic instant noodles")
);

public SnackRecommendation snackFor(Creature aHungryOne) {
    return RECOMMENDATIONS_BY_CREATURE.getOrDefault(
            aHungryOne,
            RECOMMENDATION_FOR_MYSTERIOUS_GUEST
    );
}

This is not a Java-specific trick. In Python, the same idea is usually expressed with a dictionary. In C#, you’d typically use a Dictionary<TKey, TValue>. The syntax differs, but the pattern is the same: move the mapping out of control flow and into a data structure that states the relationship directly.

Refactoring to a table makes the design intent explicit: there is a fixed set of domain values, and each one maps to a recommendation. Better, any changes to the behavior of the code are now purely declarative. You modify the table, but don’t have to change any logic. That’s about as safe as it gets.

This refactoring has several benefits:

• Separates selection data from selection mechanics.

• Removes repetitive branching noise that adds no new meaning.

• Makes missing cases and defaults easier to reason about.

• Gives both humans and agents a single, canonical place to inspect and modify.

• Reduces the amount of code an AI must read before making a safe change.

There is also a more subtle design gain here: once the selection becomes a table, it becomes easier to ask the right domain questions. Should this really be a fallback? Or should the default be an exception as a missing entry would indicate an internal bug? Those questions are much harder to see when the logic is buried in a switch.

When this refactoring applies

Use a table when branches are doing little more than selecting a value.

Typical signs:

• Each branch returns a constant or near-constant value.

• The logic is keyed by a domain concept such as status, type, code, or state.

• There is little or no branch-specific algorithmic behavior.

In contrast, do not force everything into a table. If each branch contains meaningful behavior, side effects, or a non-trivial algorithm, then you probably have a behavioral variation problem rather than a selection problem. In that case, reach for polymorphism, composition, or dedicated strategy objects. (We’ll cover these patterns too later).

A blunt but useful rule is:

If your switch mostly chooses data, use a table. If it mostly performs behavior, use objects or functions.

Why this matters more in the age of AI

Humans are good at glossing over repetitive code. We see a switch, we skim, and we tell ourselves we got the idea. Often we did. Sometimes we did not.

Agents must process the structure more mechanically and literally. A long conditional construct increases the amount of code they need to ingest before they can infer the domain model. That increases token cost and the chance of error. The code becomes mechanically readable but semantically vague.

A table improves that situation because it is closer to the underlying purpose of the program. Instead of reading branches and reconstructing a mapping, the agent sees the mapping directly. This is one of the recurring themes in AI-readable code: refactor toward explicit structure. Make the code say what it is.

Subscribe now

In many cases, the problem is not complexity itself, but where that complexity lives. We tend to express domain concepts through control flow—if statements, switch blocks, nested conditionals—rather than through explicit structure. That makes the code harder to read, harder to change, and harder for AI to work with.

Design Right-Sized Functions

Many a code reviewer has battled over function length. The argument usually alternates between two polar opposites: should we prefer many small methods, or is it better to keep related code in one large chunk?

Ultimately, that question misses the point. It is the wrong question to ask. Rather, we should focus on right-sizing our functions.

Fundamentally, the cost of working with code is dominated by how long it takes to answer questions like:

• What does this code do?

• What will break if I change it?

• Where should I make the change?

Large functions increase that cost because they force us — and our agents — to scan, interpret, and simulate more logic before we can act. Right-sized functions reduce that burden. Not by being small, but by being understandable.

Introduce Functions Your Brain Loves

Human working memory is limited. We do not read code token by token—we read by chunking.

A good function acts as a cognitive unit. It lets us replace a block of logic with a single idea.

Compare:

if (user.isVip() && order.amount() < 20000 && !order.hasDispute()) {
    // ...
}

with:

if (isEligibleForFastTrackRefund(user, order)) {
    // ...
}

It’s a simple example, yet the second version compresses detail into meaning. It allows the reader to move forward without simulating every condition.

That matters even more in an AI-driven workflow. As humans, we are no longer just authors of code. We are:

• orchestrators and technical leaders, guiding agents toward the right implementation,

• and reviewers, validating and correcting what those agents produce.

Both roles depend on quickly understanding intent. Functions that align with how we think make that possible.

Subscribe now

Introduce Functions Your AI Agent Loves

The same properties that help humans understand code also benefit AI systems—but for different reasons.

AI models do not “understand” code the way humans do. They infer meaning from patterns in tokens and depend heavily on what is explicitly expressed in the code.

Research shows that naming plays a critical role. When meaningful identifiers are replaced with arbitrary names, model performance drops significantly. Current models rely heavily on literal features—names, structure, and local context—rather than inferred semantics.

That has practical implications:

• A well-named function communicates intent directly.

• A poorly named function forces the model to reconstruct meaning.

• Larger, unstructured methods increase the amount of code the model must process before making a safe change.

In other words, good function design reduces both cognitive load and token load.

How long should a function be? Findings from research

So, all this talk about right-sized functions. Couldn’t we just come up with a number? Sure. What about 24? That number comes from a 2022 study which examined the evolution of ∼785K Java methods.

24 lines is lower than all corporate coding standards I’ve ever seen. Those tend to settle for variations of the idea that the whole function should fit on screen or, old school, a page of paper. (See the coding rules from NASA’s Jet Propulsion Lab for a good example).

But even a number backed by data is misleading. Code doesn’t magically become unreadable once you add line 25. Size alone is a poor predictor of complexity.

Empirical research consistently shows that maintainability and understandability cannot be reliably inferred from method length. Such models are not very accurate. Instead, factors like naming, cohesion, nesting depth, and domain complexity are all more important.

With coding agents now working directly on our code, hard limits become even less useful. Agents benefit from explicit structure and clear intent, not from arbitrary line counts.

🎗️ There is no fixed number of lines that makes a function “good”.

A long function is not a problem by itself. A function that mixes multiple concerns, hides intent, or resists naming is.

So the goal of refactoring is not shorter functions per se. It is better structure.

When we extract well-named functions with clear purpose, we introduce meaningful chunks into the design. Those chunks make it easier to reason about the system and often reveal better abstractions.

Refactoring is not about slicing code into smaller pieces. It is about discovering the right boundaries.

Making it worse: split at random

Discovering the right boundaries is not as simple as just extracting pieces of code into functions.

Consider this:

// ⚠️ WARNING: do *not* try this at home
void processOrder(Order order) {
    impl1(order);
    impl2(order);
}

void impl1(Order order) {
    // first half of logic
}

void impl2(Order order) {
    // second half of logic
}

This satisfies a line-count rule. It also keeps your company-mandated linting tool happy. What it doesn’t do is improve understanding.

Splitting functions based on arbitrary thresholds makes the design worse. Code that belongs together should stay together. Split by concept, never by lines.

Beyond Method Extraction: define concepts

Now, there’s one more thing to consider. Making a method shorter is not necessarily about splitting it into smaller ones. (In fact, I suspect that this misconception is a common reason for the keyboard wars around function length).

Consider:

String allowedHumidityBand = request.allowedHumidityBand();
String[] humidityParts = allowedHumidityBand.split(”-”);
int minHumidity = Integer.parseInt(humidityParts[0]);
int maxHumidity = Integer.parseInt(humidityParts[1]);

In the preceding code, there seems to be a domain concept involving humidity limits. But that concept is scattered across Strings and ints. The reader has to infer that all of these values are really one thing: a humidity band.

A simple improvement is to define that concept directly:

HumidityBand humidityLimit = parseHumidityBand(request.allowedHumidityBand());

That is a small change, but it matters. Yes, we went from four lines of code to one, but length is secondary. The important part is that the code now aligns with the problem domain. The parsing details are encapsulated, so they no longer distract from the overall purpose of the method. You, and your agent, can now talk about a HumidityBand instead of passing around parsing artifacts and loose integers. That makes the intent clear.

From Hidden Logic to Explicit Structure

Functions are the first unit of structure in a codebase. They define how logic is grouped, how intent is communicated, and how change is localized. If the function boundaries are wrong, everything built on top of them becomes harder to understand and harder to evolve.

That is why function design matters so much. It is where structure begins.

It’s also where this series continues. In the next posts, we’ll take on specific patterns that turn tangled control flow into explicit structure:

• conditionals → named rules

• branching → tables

• logic blobs → composable pipelines

If you enjoy taking messy code apart and rethinking its design, you’ll like what’s coming next. (And yes, we’ll break a few “best practices” along the way).

My next post is one of the most common problems: selection logic hidden inside conditionals. Subscribe if you want those patterns as they’re published, and see you soon!

Subscribe now

In the beginning, there was code. Lots of it. And not all of that code was, shall we say, in the best possible shape. Then came the machines, first learning from that code, and then beginning to write it themselves.

Today, AI is transforming the software industry—and yet, we’re only getting started.

Why code still matters

Great code is no longer just readable. It must be machine-legible and transformable.

If AI cannot understand your code, you need to guide the agents with clear, structured, and concrete examples. This publication explores the principles, techniques, and refactoring patterns that shape how we should design software in the AI age.

Today, anyone can create a non-trivial software product. In fact, you can do so without knowing how to code. AI has come a long way.

However, writing the initial version of a product was never the key challenge. (That’s not to say it’s easy—there are enough infamous examples of systems that never shipped.) Most of the cost comes after the initial version is shipped, assuming you have product–market fit and customers.

The more successful your product, the stronger the pressure for new features and improved capabilities. This is where software design and architecture start to matter.

In 2026, my research colleagues and I published a paper on AI-friendly code. In short, we found that to do a good job, an AI agent demands better code quality than a human would.

Let’s repeat that, since it’s so important:

To minimize defects, keep token costs reasonable, and ensure your AI implements the right thing, you need to care about code quality.

But won’t AI become good enough to work on any code?

AI for coding has evolved at a ridiculous speed, and it’s tempting to believe that the future will be even brighter.

So instead of thinking about software design, perhaps we could all just relax and let time (and Big Tech) do its job?

I’ve been hearing that argument since early 2023. And so far, we’re not there.

It’s not an unsolvable problem, but several forces work against it:

• AI reflects its training data. Coding models are trained on real codebases…and most real codebases are not great.

• LLMs lack an objective measure of what “good” looks like.

• Without clear structure and intent, AI becomes directionless. It can — and will —modify code, but it cannot reliably understand it.

That last point matters more than it might seem. When code does not communicate intent, every change becomes speculative, for humans and machines alike.

Subscribe now

The software engineering renaissance

Fortunately, AI is still immensely useful even in the worst possible spaghetti code. It just needs direction.

And this is where you, the software professional, comes in.

Programming might be dead, but software design is more relevant than ever.

To perform well, agents need structure. That structure comes in the shape of:

• Consistency: predictable structure, obvious places to look

• Documented principles and constraints (like CLEAR)

• Reusable know-how (what we might call “skills” today)

• Alignment between problem and solution domains

• No surprises: because surprises are expensive, for both humans and machines

At this point you might wonder: weren’t these concepts important pre-AI? Absolutely. Great software has always been built on this foundation.

The difference in the AI era is speed: mistakes, ignorance, and shortcuts compound at machine speed. We can no longer get away with sub-standard architectures, nor can we compensate for poor design by throwing more people (or agents) at the problem. Clean code is not enough—we need great software design.

What you’ll find here

This publication is about making code easier to understand, safer to change, and more predictable to evolve by both humans and agents.

Much of that work comes down to structure.

A large part of the problem with poor-quality code is a lack of modularity and a failure to communicate intent. When code hides what it does, everything becomes harder:

• It is difficult to find the right place to make a change

• It is risky to modify behavior without breaking something else

• It is expensive for an AI to even locate the relevant logic

This publication takes on that problem. It’s all about code that machines can safely transform.

Agentic coding is harder, not easier

Sometime in late 2025, I wrote my final lines of code. I wasn’t aware of it at the time, but that day marked a transition after almost four decades of programming. I’ve created and shipped plenty of code since then, but with one key difference: that code wasn’t written by hand. It was written by AI agents that I directed.

Surprisingly, I don’t long for the old days. I find agentic coding more rewarding, and the shift isn’t as large as I would have expected. It still feels like programming, just with larger steps and faster feedback.

That said, I’m grateful for those years of manual coding. Without that experience, I wouldn’t have been able to steer coding agents in the right direction, nor would I have known what and how to correct in the resulting software design (those corrections being agentic too, of course).

Why this publication exists

The short answer is that I simply love to write, and I enjoy developing software. Hopefully that shines through.

So what to I have to share? I’ve spent decades working with software systems across domains, paradigms, and organizations. Over time, certain patterns keep appearing. Some of those patterns transform a solution to make the code easier to work with, while others make the design more fragile.

In the AI era, those patterns matter even more.

In my next posts, I’ll share:

• refactoring patterns that improve structure and intent

• design principles that make code easier to evolve

• and occasional reflections on topics that interest me, for example what the developer role is becoming

Because one thing is clear: The future of software development is not less engineering. It is engineering at a higher level of abstraction.