Black Boxes, White Boxes, and the Visibility Spectrum

Feb 28 2026

This essay examines the spectrum of transparency in software systems, from fully open-source code to the deep opacity of LLMs and managed cloud services. Black boxes are powerful cognitive compression tools—hiding complexity behind clean interfaces—but create real challenges when things break and debugging requires visibility you don't have. As developers increasingly depend on AI APIs and serverless platforms, it might help using hybrid architectures that strategically combine opaque and transparent components, keeping core business logic visible while delegating well-bounded problems to black boxes.

AI Design Essay

 Designing for the Unknown

Feb 24 2026

Most software systems aspire to robustness — surviving stress unchanged — but that's just a holding pattern in a world that won't stop moving. Drawing on Taleb's concept of antifragility and Barry O'Reilly's Residuality Theory, this piece argues that we can deliberately engineer systems that improve under stress by combining two ideas from complexity science: Kauffman's Random Boolean Networks (which show that real system topologies are far more manageable than their theoretical state spaces suggest) and Monte Carlo-style thought experiments (tracing hypothetical scenarios through your architecture to find structural brittleness before the world finds it for you). The multiplier effect is key — fixing a structural weakness uncovered by one imagined scenario tends to cover dozens you never thought of. AI coding assistants make this exploration dramatically faster, letting you prototype multiple architectural alternatives in hours instead of weeks, but they don't replace the judgment calls about which scenarios matter and what the results mean. The takeaway: thinking is still the cheapest, highest-leverage activity in software design, and now we have even less excuse not to do more of it.

AI Design Essay

 Layers, Levels, and the Cognitive Maze

Feb 22 2026

This essay explores the difference between meaningful architectural layers and mere levels of indirection in software design. I argue that splitting code into smaller pieces often creates navigational mazes rather than genuine separation of concerns, using the bloated business-logic layer and the repository pattern as key examples. AI coding assistants highlight the problem: they can follow complex call chains perfectly but still struggle when the underlying organization doesn't reflect coherent business concepts. The piece advocates for indirection that earns its existence through a distinct purpose, not just a smaller file size.

AI Design

 It's All About Interfaces

Feb 21 2026

The most important thing in software design isn't the logic or the algorithms — it's the interfaces. Coding assistants are making this truth visceral: when a machine consumes your API, every implicit assumption and ambiguous contract is exposed. This piece explores how hexagonal architecture, basic principles, and the DRY rule all take on new significance when AI agents stress-test your designs, and why getting interfaces right is becoming the most human skill in software engineering.

AI Design Essay

 The Tension Between Consistency and Improvement

Feb 20 2026

Improving a software codebase often creates temporary inconsistency because new patterns must coexist with older ones during gradual migrations. While consistency helps developers understand and navigate systems efficiently, evolving requirements and better practices make change unavoidable. Incremental refactoring is the safest approach but introduces short-term cognitive complexity—especially as AI tools accelerate experimentation and increase the risk of unfinished migrations. This article argues that teams must consciously balance consistency and improvement by making deliberate decisions, keeping changes focused, and finishing migrations to maintain long-term code quality.

AI Design

 Why Your Code Always Feels Wrong (And That's Okay)

Oct 7 2025

Every developer faces the same impossible choice: keep all your logic in one place and watch it become an unmaintainable monster, or split it across multiple files and create a maze where simple changes require archaeological expeditions through twelve layers of indirection. This isn't a sign you're doing it wrong—it's the fundamental tension of software architecture. The good news? Both approaches are tools, not traps. Understanding when to use monolithic clarity versus distributed modularity, and having the courage to refactor between them as your system evolves, is what separates thoughtful architecture from cargo-cult pattern following. Your code will always feel imperfect, and that's exactly how it should feel when you're working on something complex enough to matter.

Design Essay

 It's All About Semantics

Sep 14 2025

Programming exists in two worlds: the syntactic realm of compilers and the semantic realm of human understanding. While syntax gets code to run, semantics determine whether systems can evolve. Every name, abstraction, and domain boundary creates semantic contracts that either enable or constrain future development. When business concepts contaminate infrastructure layers—like introducing "squads" into an S3 client—semantic pollution occurs, creating rigid systems that resist change. Clean semantic architecture requires disciplined vocabulary, respected domain boundaries, and recognition that we're not just building software, but building languages. The words we choose today become the conceptual framework that shapes what our systems can become tomorrow.

Design Essay

 Value Objects for the Win!

Jun 15 2025

Value Objects solve the primitive obsession problem by encapsulating data, validation, and behavior in a single unit. Stop scattering domain logic and start creating more cohesive, maintainable code.

Design

 Lifespan Strategies

Jun 14 2025

Mutability × Time: The Compound Risk series.
\r\nProven techniques for containing the compound risk of mutable state over time. From theoretical patterns to a successful real-world refactoring that eliminated invisible coupling.

Design State Management

 Invisible Coupling

Jun 14 2025

Mutability × Time: The Compound Risk series.
\r\nWhy components become secretly coupled through shared mutable state. Examines how invisible dependencies erode trust and create debugging nightmares separated by both code and time.

Design State Management