ARTICLE
CLEAR. Practical AI-First Design Principles for Real Codebases
AI tools have given architecture a second consumer alongside human developers. Our Software Architect, Mel Collins, outlines CLEAR, the practical framework for designing codebases where both humans and AI can reason effectively.
Mel Collins
Software Architect, 8 West Consulting
SHARE POST
June 08, 2026
If you are using AI tools seriously in day-to-day development, one thing becomes obvious quickly.
Architecture now has two consumers, humans and machines.
Most of our established principles, including SOLID, optimise for long-term human maintainability through abstraction and decoupling. That still matters.
But in practice, AI systems reason better when related logic is visible together. Fewer hops mean more usable context and fewer incorrect assumptions.
That is the “so what”. If you design only for human readers, AI may struggle to give you reliable results.
This is the framework we have been applying, via co-pilot instructions file.
CLEAR:
-
C. Context Locality. Keep related decisions and logic close together.
-
L. Linear and Explicit. Prefer straightforward flow over clever indirection.
-
E. Examples Everywhere. Tests and docs act as executable specifications.
-
A. Avoid Premature Abstraction. Start simple, refactor once patterns are proven.
-
R. Readable and Repeatable. Consistent naming and structure matter more than novelty.
What we consistently see when working with development teams is a common failure mode.
Highly fragmented folder structures, deep inheritance trees, or legacy stored procedures spread across decades make it hard for AI to follow the full decision path. The result is brittle suggestions and hallucinated behaviour.
The practical shift is this.
Instead of asking, “Is this perfectly abstracted?”, also ask, “Can an AI see the whole decision flow without jumping through ten files?”
In complex domains like Health InsurTech, we see better outcomes when core business logic is expressed locally and explicitly. AI-assisted changes become faster, safer, and easier to review because the reasoning is visible in one place.
Key takeaway:
Designing for bi-modal maintainability means balancing SOLID’s strengths with CLEAR. You reduce AI confusion, improve signal quality, and accelerate AI-assisted development without sacrificing human readability.
This is an area we have been applying in production systems at 8 West, and it is becoming a quiet differentiator for teams who want AI to be an asset rather than a liability.
#SoftwareArchitecture #AIDevelopment #EngineeringPractice #8West
