Architecture Models as First-Class Context for AI-Assisted Software Development
As software engineers, we’ve spent the last few decades treating architecture diagrams as documentation rather than development artefacts.
We design a system, produce an architecture diagram—if we’re disciplined enough—and then development begins. As the code evolves, the architecture changes, and eventually the diagram falls out of date. We all knew it wasn’t ideal, but when humans were the only ones writing software, we could usually get away with it.
Today, software isn’t written solely by engineers. We have AI coding assistants, vibe coding, and increasingly autonomous agents generating implementations on our behalf. The question is no longer just “Did we build what we intended?” but “How do we know what kind of jungle our AI has created inside our cloud environments?”
Modern coding assistants generate implementations based on the context they’re given. Over the last year we’ve seen the rise of specification-driven development as a way to provide that context. Standards such as SpecKit and tools like AWS Kiro encourage specifications to become part of the repository, allowing AI to work from structured requirements rather than ad hoc prompts.
Specifications are a huge step forward, but over time I found myself with dozens of partially implemented specifications scattered throughout my repositories. They described individual features well enough, but I was losing sight of how those features fitted together. I had requirements, but I was missing the architectural context.
What I needed wasn’t another diagram. I needed an architectural model that captured components, trust boundaries, security controls, contracts and deployment configuration—and I needed that model to remain useful throughout the entire software development lifecycle, not just during design reviews or onboarding sessions.
That led me to a simple question.
Instead of diagrams explaining the finished system, what if the architecture model could deterministically generate specifications, implementation guidance, security controls and evaluation criteria? The architecture would become the source of truth, with specifications derived from it rather than maintained separately. As the model evolves, the specifications evolve with it.
This becomes even more compelling as software teams adopt autonomous agents and AI-assisted workflows. If AI systems are expected to make implementation decisions, they need access to architectural intent—not just source code. Architecture becomes a source of governance, helping ensure generated software remains aligned with security objectives, organisational policies and design constraints.
To me, this is a shift in how we think about architecture. Instead of treating it as documentation, we begin treating it as executable knowledge that actively participates in software delivery.
Over the past few months I’ve been experimenting with this idea through a project called iSecureByDesign. The goal isn’t simply to draw diagrams, but to treat architecture models as a source of requirements, controls and implementation guidance. I’ve used it to model serverless applications, LangGraph-based agentic knowledge systems and other architectures with baseline security controls built in. Whether the implementation succeeds is for others to judge, but the experiment has convinced me there’s something really worth fleshing out here.
As AI becomes more capable, I suspect the quality of software won’t be determined by prompts alone. It will increasingly depend on the quality of the architectural knowledge we provide alongside them.
Perhaps the next evolution of software architecture isn’t producing better diagrams.
Perhaps it’s making architecture models first-class citizens in the AI-assisted software development lifecycle.
Have you been seeing the same shift, or have you found different ways of maintaining the architectural context for AI?