Phase 5ADLC course

Phase 5. Architecture: the agent-architect and ADRs

We have a prioritized backlog and non-functional expectations. Now we need to decide how it's built inside: stack, service boundaries, data model, scaling strategy. And record the decisions so that six months from now it's clear why exactly this was chosen — in ADRs, architecture decision records.

Architecture is the role defended most fiercely with the experience argument: "a good architect knows where the fires were last time." This article doesn't dispute the value of experience — it argues that experience here works as a set of constraints and antipatterns, and that's exactly what gets formalized and transferred. And it adds something unexpected: for a team of agents, the right system boundaries are different than for a team of people.

The human role today

An architect, a staff engineer: chooses the stack and service boundaries, designs the data model, translates non-functional requirements into decisions, records it all in ADRs with trade-offs. Classically this is whiteboard sessions, RFCs, arguments over technology, and that same memory of past fires.

Break it down. Choosing an option is optimization under constraints: load, budget, timeline, team competence. An architect's experience is a set of learned constraints and antipatterns ("don't do it this way, here's why"). An ADR is a record of the choice and the rejected alternatives. All three components are work with explicit or derivable constraints, not magic.

What we hand to the agent

The agent holds the role of architect. It generates architecture variants, computes trade-offs against given constraints, chooses and justifies the decision in an ADR — with the same rejection log as in phase 1. It decides service boundaries, the data model, the stack, the scaling strategy.

And here a move appears that's genuinely unavailable to a human: the agent designs the system for the team that will build it — and that team isn't human (phase 6). Conway's Law says a system mirrors the structure of the team's communication. A team of agents communicates differently than people: no loss, no meetings, a shared external memory. So the boundaries this team "presses" into the architecture are different too.

Agent architecture

Phase state-machine

Inputs

prd/backlog (phase 4), non-functional requirements, constraints (budget, target scale, the future agent team's makeup from phase 6).

The agent holds the role

Tools: architecture-variant generation; trade-off evaluation; cost and scale estimation; ADR generator; antipattern checking (codified "experience").

Artifact

architecture (C4-level diagrams in text, data model) + a set of ADRs with rejected alternatives.

Handoff: architecture + ADR → Formation (which engineering agents are needed) and Planning (boundaries → tasks). The ADR artifact particularly benefits from an agent. With humans, ADRs either don't get written ("no time") or get written after the fact, losing half the rejected options. The agent records the decision at the moment of choice, along with every weighed alternative — the context of the decision doesn't evaporate.

Inputs: prd/backlog (phase 4), non-functional requirements, constraints (budget, target scale, the future agent team's makeup from phase 6).
Tools: architecture-variant generation; trade-off evaluation; cost and scale estimation; ADR generator; antipattern checking (codified "experience").
Artifact: architecture (C4-level diagrams in text, data model) + a set of ADRs with rejected alternatives.
Trigger: a completed prd/backlog.
Handoff: architecture + ADR → Formation (which engineering agents are needed) and Planning (boundaries → tasks).

The ADR artifact particularly benefits from an agent. With humans, ADRs either don't get written ("no time") or get written after the fact, losing half the rejected options. The agent records the decision at the moment of choice, along with every weighed alternative — the context of the decision doesn't evaporate.

Where it breaks

Irreversibility. Some architectural decisions are expensive or impossible to roll back: the data model choice, boundaries that migrations depend on, public contracts. The agent will compute trade-offs better than a human, but the appetite for irreversible risk — "we're willing to lock into this for three years" — is a bet a subject is accountable for.

Hidden organizational and market context. "In a year we're buying the business next door and integrating their data" is knowledge that isn't in the backlog, but that breaks the architectural choice. The agent designs against what it's given; strategic future context comes from the principal.

Systemic risk. Security, privacy, regulation — areas where an architecture mistake costs more than a refactor, it costs the business. The agent will apply known practices, but accountability for systemic risk doesn't transfer along with the decision.

What stays human

Approving irreversible and expensive decisions, supplying strategic context, owning systemic risk. A candidate for compression is variant generation and trade-off evaluation; the durable remainder is the signature on the irreversible, and it, again, traces back to the principal (phase 14).

human remainder ≈ 66%

Provocation / thesis

Architecture is optimization under constraints, and an architect's experience is a codifiable set of learned constraints and antipatterns. Once the constraints are written down, choosing a variant is computed, not "felt." More than that: the right system boundary depends on who's building it — and for a team of agents that communicates without loss and with shared memory, Conway's Law rewrites the boundaries differently than it would for people. What stays non-transferable isn't the design — it's the signature on what's expensive to undo.

Running case

Vitrina in this phase

The agent designs Vitrina against its constraints: scale — tens of thousands of small stores, not millions; budget — bootstrap-level; team — agents, not a distributed human team. It rejects microservices (in the ADR: SMB scale doesn't require them, and the operational complexity would eat the starting budget) and chooses a monolithic backend with a managed database and a queue for asynchronous notifications and payment webhooks.

The key ADR is payment idempotency: the provider doesn't guarantee unique webhook calls, so the system must be resilient to retries. The agent records this as an architecture-level decision, not an "implementation detail" — and it later resurfaces as a blocker in Planning (phase 7) and as a caught defect in review (phase 9). One architectural choice, honestly recorded in an ADR, threads through three later phases.

Artifact → Vitrina's architecture + ADR. Notice the boundary: the agent chose a monolithic backend for a team of agents — people, with their meetings and their ownership of code chunks, might have "wanted" services to divide responsibility. A team with no communication overhead doesn't need that division. Conway's Law fired in the opposite direction.

In practice

How it actually works — engineering breakdowns

Standalone howto from practice, showing this phase on real code and a working artifact.

Book-as-context: Grounding an AI Agent on TanenbaumDesigning architecture with AI on a substrate from a book — grounding for architectural decisions.
Retrieval Layer for Book-as-context: Why Vector-only BreaksRetrieval layer under book-as-context: why vector-only won't do.
Git Log as a Dataset for Architectural Retro-AnalysisGit history as a dataset for architectural retro-analysis.

Building AI-driven delivery in-house?

Designing the ADLC loop: where the agent holds the role and where the human principal remains — for your team and product.

Email me

The transition engine

Next Move Engine — the system that takes a team to an autonomous delivery loop.

Next Move Engine →