CLEAR: Software Design Principles for the Agentic Age
Traditional design principles optimize for human maintainability. CLEAR optimizes for safe evolution through explicit structure under AI-assisted change.
Over the past months, I’ve written a series of articles on AI-readable code. Each one explored a different design problem, refactoring pattern, and remediation strategy. But they all focused on the same question: what makes code easy for an AI to read, extend, and modify?
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.