Governed ADRs in the Age of AI Architecture

Architecture Decision Records, as Michael Nygard described them in 2011, were invented for a slower world. A team made an important call — pick a database, choose an event format, commit to a service boundary — and someone wrote it down so the next generation of engineers would understand the reasoning. ADRs accumulated at the pace of important decisions: a few per quarter, sometimes per year.

That cadence assumed humans were the only ones proposing architecture. In 2026, an agent proposes architecture in nearly every non-trivial PR. It picks libraries, invents abstractions, decides where state lives, chooses how errors propagate. Most of those choices never reach an ADR. Most of them never reach a human review at the architectural layer at all. They land in code, get merged, and become the de facto architecture of the system — chosen by no one, owned by no one, retrievable by no one.

This is not a tooling problem. It is a control problem. ADRs need to evolve from a ceremonial artifact into a daily filter.

Software is still the expression of human intent. The speed of generation has changed. The need for intent has not.

The drift nobody is watching

Pick a codebase that has been AI-assisted for twelve months. Open it. The patterns will not look chosen. They will look accumulated: three different HTTP clients because three different generations picked their favorite, two retry strategies that interact in ways nobody intended, an event payload shape that mutated five times because each new feature reshaped it slightly. None of these are bugs. Each one is a small architectural decision the agent made and nobody contested.

This is what GAISD.3.1 calls the failure of architecture as prerequisite. When architecture is not declared upfront and enforced as a constraint on generation, the agent reads the existing code, infers a pattern, and produces something "consistent enough" with what it sees. Over time, the inferred pattern drifts from any pattern a human would have chosen. The system keeps working until the day it doesn't, at which point the question "why is it like this?" has no answer.

The traditional ADR was meant to prevent exactly this — to make architectural decisions retrievable. But traditional ADRs assumed that important decisions were rare and conscious. Now they are frequent and silent.

What "governed" adds to ADR

A governed ADR is not a heavier ADR. It is an ADR wired into the generation loop, with three properties the original format did not need:

It is invoked, not just written. When a generation crosses an architectural boundary — introduces a new dependency, changes a contract, alters a state machine, picks a persistence strategy — the system requires an ADR reference. Either an existing ADR covers the choice (cite it), or a new one is written and signed (create it). There is no third path. The agent cannot quietly invent a new pattern because the pipeline asks "which decision authorizes this?"

It has an owner, named. Every ADR carries an Architect Owner — a human who signs the decision and is responsible for its consequences. This is GAISD.1.2 made concrete. When the system fails six months later because of how errors propagate, the incident review opens the relevant ADR and reads the name at the bottom. Not for blame. For the conversation that produces the next ADR.

It is contested before it is adopted. The agent can propose an ADR. It cannot ratify one. The proposal goes through a structured contrast: what alternatives were considered, what trade-offs were accepted, what the agent suggested versus what the human chose and why. The contrast is the artifact. Reading it five years later, a new engineer can reconstruct not just what was decided but what was deliberately rejected. That is the only way architecture survives the people who made it.

The shape of a governed ADR

A practical example. The agent is asked to add idempotency to a payment endpoint. It would, by default, hash the request body and store the result. That is one of three reasonable choices. The system requires an ADR before the diff merges:

adr:
  id: ADR-0117
  title: "Idempotency strategy for payment endpoints"
  status: accepted
  architect_owner: thiago.lima@company.com
  date: 2026-04-28
  context: |
    Payment endpoints can be retried by clients on network failure.
    We need a deterministic idempotency mechanism that does not
    rely on client-generated keys (clients are mobile, untrusted).

  options_considered:
    - id: A
      summary: "Hash the request body server-side, dedupe on hash."
      proposed_by: agent
      pros: ["Zero client change", "No new schema"]
      cons: ["Hash collisions on near-identical requests", "Cannot dedupe legitimate retries that mutate one field"]

    - id: B
      summary: "Require clients to send an Idempotency-Key header per the IETF HTTPAPI working group draft."
      proposed_by: human
      pros: ["Industry-standard", "Explicit semantics", "Survives field mutation"]
      cons: ["Requires client SDK update", "Coordinated rollout"]

    - id: C
      summary: "Persist a request log with TTL, dedupe on (user_id, endpoint, payload_hash, window)."
      proposed_by: agent
      pros: ["Granular control"]
      cons: ["Storage cost", "Complex eviction", "Window tuning is operational toil"]

  decision: B

  rationale: |
    Industry-standard semantics outweigh the rollout cost. Option A's
    collision behavior is a silent failure mode we cannot detect from
    server logs. Option C creates ongoing operational burden.

  consequences:
    - "Payment SDK v3.2 must ship before this rolls to production."
    - "All payment endpoints adopt the same Idempotency-Key contract."
    - "Supersedes the ad-hoc dedupe in /v1/charge introduced in 2025."

  supersedes: []
  superseded_by: null

  signed_by:
    - thiago.lima@company.com
    - finance.platform.lead@company.com

Notice what this artifact does that a code comment, a PR description, or a Slack thread cannot. It records the rejected options and why they were rejected. It names a human who is accountable. It explicitly declares the operational consequences (the SDK dependency, the supersession of an earlier ad-hoc choice). And it is queryable — six months from now, a new engineer asking "why don't we just hash the body?" finds Option A and the reason it lost.

This is GAISD.3.4 — governed ADRs — not as documentation but as an architectural control gate.

Why the agent helps here, instead of hurting

There is a counterintuitive upside in this workflow: the agent gets better at architecture once you make it operate inside ADRs.

When the agent is asked to add a new endpoint and it can read ADR-0117, it knows the idempotency strategy already. It does not invent a fourth option. It applies the existing one, cites the ADR in the PR, and produces code consistent with the rest of the system. The system gets coherent in a way that hand-coded systems often were not — because the conventions are explicit, machine-readable, and present in every generation's context.

This is the inversion most teams miss. ADRs feel like overhead until you treat them as prompt context. Then they become the cheapest way to keep an AI-assisted codebase coherent over time. Every new generation inherits the prior decisions instead of relitigating them. The Architect Owner spends less time reviewing and more time deciding.

What this means for the Tech Lead

Three moves to install governed ADRs without turning your team into a documentation factory.

Define what triggers an ADR, in the pipeline. A new third-party dependency. A change to a public API contract. A new persistence pattern. A new cross-service boundary. Encode the triggers as checks in CI — when a PR touches one of these, it must cite an ADR id or include a new ADR file. Vague rules ("important decisions") produce zero ADRs. Specific triggers produce the right number.

Name Architect Owners for each domain. Not a committee. A person per domain who signs ADRs in that domain. This is GAISD.1.2. Without a named owner, ADRs become anonymous and the accountability principle dissolves. With one, the question "who do I need to convince?" has a clear answer, and the friction is correctly placed.

Feed ADRs to the agent as first-class context. When the agent operates in your repo, the relevant ADRs should be in its working set, not buried in a /docs directory it never reads. The same artifact that disciplines humans should constrain the model. One source, two enforcement paths.

The invitation

Architecture is not what the system does. It is what the system cannot do — the boundaries the team has chosen to honor. When agents propose architecture in every PR, the only way those boundaries survive is if they are written, owned, and enforced. ADRs were always the right tool. They just need to operate at the new cadence.

If your team is generating code daily and producing ADRs quarterly, the gap between the two is where your architecture is silently being chosen for you. Closing that gap is principle two of the manifesto — governed structural primacy — made operational.

Sign the manifesto at gaisd.dev/sign, and adopt the practice of governed ADRs as the next thing your team commits to. Architecture is a decision. Decisions need owners.