DEV Community: Alistair Clarkson

AI Coding Assistants Have an Architectural Context Problem

Alistair Clarkson — Fri, 10 Jul 2026 15:09:40 +0000

I’ve spent a while experimenting with AI-assisted software development using tools like Claude Code, Codex and Kiro.

One thing has surprised me.

AI coding assistants receive plenty of implementation context, but very little architectural context.

Typically they can see:

Source code
APIs
Unit tests
Documentation
Prompts

What they rarely see is why the system was designed the way it was.

That matters because many security decisions aren’t implementation decisions.

They’re architectural decisions.

Humans infer architecture

Experienced developers usually have advantages that AI doesn’t.

They’ve attended design meetings.

They’ve spoken with architects.

They understand organisational conventions.

They know which systems are trusted, where boundaries exist and why certain technologies were chosen.

Even when documentation is incomplete, experienced engineers can often infer architectural intent.

AI generally can’t.

It only knows what it’s been given.

Security starts before code

Looking back through the history of Secure by Design, one pattern kept appearing.

Whether you’re looking at:

Microsoft’s SDL and threat modelling
OWASP’s secure design guidance
NIST SSDF
CISA Secure by Design
the Cyber Resilience Act

they all encourage organisations to consider security before implementation.

The terminology changes.

The mechanisms change.

The principle doesn’t.

Security is strongest when architectural decisions are analysed before software is written.

The gap

Today’s architecture diagrams are usually documentation.

They explain systems to humans.

They rarely provide structured guidance that AI coding assistants can consume directly.

That creates an interesting possibility.

Instead of treating architecture as documentation, perhaps we should treat it as engineering knowledge.

A model could become the source for things like:

security requirements
architectural controls
implementation constraints
trust-boundary rules
implementation guidance
assurance evidence
evaluation criteria

Those aren’t separate documents.

They’re different views of the same architectural security analysis.

Architecture as executable knowledge

This is the idea I’ve been exploring.

If architectural knowledge became structured enough for tools to consume, AI coding assistants wouldn’t just receive prompts.

They could receive architectural intent.

That doesn’t replace threat modelling.

It doesn’t replace secure coding.

It doesn’t replace DevSecOps.

Instead, it gives those activities a consistent architectural source that remains connected to implementation throughout delivery.

As AI agents become increasingly capable, I think this becomes more important rather than less.

Interested in the history?

I recently researched how Secure by Design evolved from Saltzer & Schroeder’s original engineering principles through Microsoft’s SDL, OWASP, NIST, CISA and recent regulation, and why AI-assisted development may represent the next stage of that evolution.

The full article, including references, is available here:

https://isecurebydesign.com/news/what-is-secure-by-design

I’d be interested to hear how others are handling architectural context with AI coding assistants.

Do you think architecture should remain documentation, or should it become something AI tools can actively consume?

Architecture Models as First-Class Context for AI-Assisted Software Development

Alistair Clarkson — Tue, 30 Jun 2026 08:36:58 +0000

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.

What if architecture models became first-class inputs to AI-assisted software development rather than documentation produced after the fact?

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?