Kostas Karolemeas
Writing archive

· software architecture

AI Can Help Design the Architecture. The Decision Needs Your Context.

I use AI for architectural research and implementation. I keep responsibility for the decisions because a repository and a conversation contain only part of the context that makes an architecture appropriate.

software architecturecoding agentsengineering leadershiptechnical judgment
Staggered teal and near-black painted planes overlap beneath translucent aqua fields and a coral sweep on cream.

In a recent LinkedIn discussion, Georgios Petas described an approach to coding with AI: establish the architecture, boundaries, and conventions yourself, then let AI do more of the implementation within that foundation. His concern was retaining responsibility for the codebase's important decisions.

My reply started with a qualification: architecture evolves as the system evolves. I research architectural decisions separately from the actual implementation, and I use AI in both processes. The decisions remain mine because I have more context than I can give the AI in any particular interaction.

That distinction matters. I want AI involved in architectural thinking. I also want a deliberate point at which someone assesses a proposal against the circumstances in which the system will have to operate.

The reason to retain that responsibility is practical: an architecture can be technically coherent and still be the wrong decision for this team, this product, and this moment.

The repository contains only part of the system

A coding agent can inspect dependencies, trace execution, find inconsistent conventions, and help investigate alternatives. The repository gives it substantial evidence about what exists. It gives it less reliable evidence about why that arrangement exists, which commitments surround it, or what is likely to change next.

Consider an illustrative decision about splitting a module into a separate service. The code might suggest a clean boundary. Yet the decision could also depend on whether another team will own the service, whether independent deployment solves a real problem, and whether the people operating it can support another failure mode.

Some of that context is documented. Some lives in conversations. Some remains an unresolved possibility: a customer request, a staffing change, or a product direction that has not become a commitment. Those possibilities should influence a decision differently from established requirements.

This is why “give the agent more context” is useful advice but an incomplete operating model. Someone still has to distinguish facts from assumptions, decide which uncertainties matter, and make conflicting priorities explicit.

Anthropic's September 2025 account of context engineering describes the technical task of selecting and maintaining relevant information for an agent, including retrieving material as needed. It treats context as a resource to curate. That supports improving what the agent can see; it does not establish that the supplied material captures every consideration behind a business decision.

Nor does my having more context mean I am automatically right. I may be carrying an outdated assumption or protecting a familiar design. A valuable use of AI is to expose exactly that weakness. I should be able to explain the context that changes my conclusion and let the proposal challenge it.

Separate the question from the implementation

When I say I research architecture separately, I mean giving the decision its own attention. I do not mean completing an entire design before allowing any code to be written.

There is a difference between asking an agent to investigate whether a service boundary is useful and asking it to implement a feature that quietly introduces one. Both can produce code. Only the first makes the architectural question explicit before the result becomes something the team has to maintain.

For a significant decision, I would start with a short brief:

  • What problem are we trying to solve, and what evidence says it exists?
  • Which constraints are established, and which are assumptions?
  • What alternatives deserve comparison, including keeping the current design?
  • What would make us reject each option?
  • Which uncertainty could a small experiment resolve?

AI can help research those alternatives, inspect their fit with the existing system, identify missing questions, and implement a disposable experiment. The brief gives that work a purpose beyond producing a plausible design.

Suppose the proposed service is meant to isolate a slow integration. I would want to test whether a queue and worker within the current deployment model address the actual bottleneck before accepting the operational cost of a new service. If independent ownership or a distinct security boundary is the real requirement, the comparison changes. This is a hypothetical example, not a claim that one topology is generally superior.

The experiment should return evidence to the decision. Its existence should not settle the decision by default.

Architecture keeps changing after the choice

Retaining responsibility cannot mean defending the initial architecture indefinitely. The system will teach us things we did not know when we started.

In his 2017 foreword to Building Evolutionary Architectures, Martin Fowler describes architecture as continuing work that responds to changing requirements and feedback from programming. Small changes and feedback loops make that evolution deliberate.

That fits how I think about AI-assisted development. Research informs implementation; implementation exposes constraints; those findings can reopen the architectural question. Keeping the activities distinct helps us recognize when we have moved from executing a decision to reconsidering it.

In the service example, a single deployment might be appropriate today. Later, a separate team may need an independent release cycle, or measured contention may justify isolation. The original decision can have been sensible and still need replacing.

I would therefore attach a reason to revisit a consequential choice. “Reconsider extraction when ownership separates” is more useful than an indefinite promise to keep the design flexible. It identifies a change in circumstances that should trigger fresh reasoning.

That review trigger is my proposed working practice, not evidence that a particular architecture will evolve successfully.

Give future work the reason, not only the rule

Instructions such as “use the existing pattern” help an agent stay consistent. They do not necessarily tell it when the pattern has stopped serving its purpose.

Michael Nygard's original architecture decision record proposal, published in 2011, offers a useful foundation: preserve a decision's context, status, and consequences. When a choice is replaced, retain the earlier record and identify its successor. The history helps a future reader understand why the system took its current shape.

I would extend that discipline into agent work. Keep a concise project entry point that points to the relevant decisions, constraints, and checks. For a consequential change, provide the specific record and the current evidence. Ask the agent to identify conflicts with that record instead of silently resolving them through implementation.

An illustrative instruction could read:

Keep the integration in the existing worker for now. The current team owns both components and deploys them together. Independent release is not a requirement. Preserve the module boundary. If the proposed change requires separate data ownership, explain why and reopen the decision before implementing it.

This provides both direction and a condition under which that direction may need to change. It also makes it easier for another engineer to challenge the reasoning.

Where a constraint can be checked mechanically, I would turn it into a check. For example, ArchUnit's user guide documents tests for dependency direction, layers, and cycles in Java code. Similar project-appropriate checks can make a stated boundary observable during development.

A passing check establishes the property it tests. It does not establish that the boundary remains the right business choice. That question still needs the broader context and the people responsible for it.

Responsibility should make the decision explainable

The wrong conclusion from all this would be that an architect should hold the context privately and approve everything. If a decision depends on knowledge that never leaves one person's head, both the team and the agent remain unnecessarily dependent on that person.

My responsibility should include making more of the reasoning available: which facts matter, what remains uncertain, what we chose, what cost we accepted, and what would cause us to change our minds. Some details may need restricted access, but the applicable constraint can often be stated without reproducing the sensitive material behind it.

This develops the argument I made in Coding Agents Reward Engineers Who Can Explain What They Want. Clear expression makes technical understanding usable. At the architectural level, that expression must also carry the reasons a choice fits its circumstances.

I am comfortable using AI to challenge a design, propose a better one, and help implement the result. Keeping responsibility for the decision means being able to explain why we accepted it and noticing when its justification no longer holds.

The architecture will change. What I want to preserve is an understandable connection between the context, the decision, and the evidence that tells us it is time to decide again.

Sources