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 Abstraction 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 Abstraction Design Philosophy

 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.

Best Practices Code quality

 The Assumptions That Break Systems

Feb 15 2026

Every bug you've ever spent hours hunting had the same root cause: something you were sure was true, wasn't. Assumptions are the invisible scaffolding of software development — inferences we treat as facts because checking everything is impossible, and our cognitive context, much like an LLM's, has hard limits. The dangerous part isn't making assumptions; it's losing track of which beliefs are proven and which are just comfortable shortcuts. Even tests — our best tool for replacing assumptions with proof — are themselves built on assumptions. This is the paradox at the heart of reliable software.

AI Design Philosophy

 It's All About Decisions

Feb 14 2026

Software development isn't a typing discipline. It's a decision-making discipline. And now that you can prototype five approaches in the time it used to take to build one, the decisions matter more than ever.

AI Design Philosophy

 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.

Architecture Design Philosophy

 What Human Learning Can Teach AI

Sep 28 2025

This essay examines how emotional weighting fundamentally distinguishes human from artificial learning, drawing on neuroscience research showing that amygdala-hippocampus interactions create a biological "highlighting" system for emotionally salient information—absent in current Large Language Models despite their sophisticated attention mechanisms. While AI systems excel at systematic processing through statistical optimization, they lack the subjective relevance judgments and persistent purposefulness that characterize human cognition, particularly the ability to maintain coherent goal-directed behavior across complex, multi-step tasks. We argue that effective human-AI collaboration will emerge from leveraging complementary cognitive architectures: AI's consistent attention mechanisms paired with human emotional weighting, subjective prioritization, and embodied purposefulness, with meta-learning skills like problem decomposition becoming crucial for humans to enhance their effectiveness as AI partners.

AI Philosophy

 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 Philosophy

 The New Ontology of Code

Aug 30 2025

AI code generation isn't just changing how we write software—it's changing what code is. We're witnessing a fundamental inversion where code transforms from permanent artifact to regenerable output, where implementation becomes fluid while interfaces become the new bedrock. But this shift creates uncomfortable paradoxes: "easier" coding that doesn't eliminate complexity but displaces it, democratization that centralizes power, and the strange alienation of debugging code you commanded but didn't create. This essay explores what we're really trading in this transformation—intimate understanding for broad capability, craft for productivity, independence for efficiency. Neither utopian nor dystopian, it offers language for that unsettling feeling many developers can't quite name: working with systems we control but don't comprehend. For anyone grappling with AI's impact on software, this is about recognizing the trade-offs we're making before we've made them irreversible.

AI Philosophy

 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.

DDD Design