# Stale architecture docs used to be embarrassing. Now agents act on them.

Standards and decision records as runtime context for AI agents: parseable, current and true, or ignored.

_Published 2026-07-14 · 8 min read_

A team points its coding agent at a new integration, and the agent does everything right. It
retrieves the integration standard from the wiki, follows the documented authentication pattern,
scaffolds the service exactly to spec, and opens a tidy pull request citing its sources. The
pattern it implemented was deprecated eighteen months ago. The replacement lives in a newer page
the agent had no way to rank above the old one, because nothing in either document says which one
is alive. The agent did everything it was built to do. It executed your documentation faithfully,
which is the new problem, because your documentation was never written to be executed.

Architecture artifacts have had a quiet job change. Principles, standards, decision records, the
technology radar, capability maps: for decades these were documentation, read occasionally by
humans who brought judgment and healthy skepticism to every page. A stale standard was
embarrassing at worst, because the human reader would ask around before acting on it. Agents
retrieve and act. Whatever corpus you publish is now input to systems that generate code at
volume, which makes the architecture corpus runtime infrastructure, with the quality bar
infrastructure carries. Staleness used to age like clutter. Now it ships.

The blast radius changed with the reader. A wrong page used to mislead engineers one at a time,
at reading speed, each of them applying doubt before betting a sprint on it. An agent applies the
same wrong page to every task that retrieves it, in parallel, minus the doubt. Documentation
defects now have the failure economics of platform defects, and platform defects get engineering
standards, named owners and expiry dates. That is the whole argument of this piece, stated as an
incident category.

The payoff for engineers arrives on the first scaffold. When the standards are agent-readable and
current, the agent produces the compliant version on the first try: right pattern, right
authentication, right observability hooks, because the governance arrived as pre-loaded context.
The alternative you live with today is governance as post-hoc review comments, delivered after
the code exists, at the price of a rework cycle. Context front-loads what review used to
back-charge. And context, unlike reviewer attention, scales with the machines.

## Parseable, current, true

The new quality bar has three properties, and each fails differently.

### Parseable

Structured, typed, addressable. A standard as a stable URL with machine-readable metadata (owner,
status, scope, last verified) can be retrieved precisely, ranked confidently and cited in a
provenance trail. A standard as a paragraph inside a forty-page slide export is, to an agent, a
rumor. The failure mode of unparseable context is silent partial retrieval: the agent gets a
fragment, misses the constraint two sections down, and builds confidently on the fragment.

### Current

Staleness is now a defect with a propagation path: it enters the corpus, gets retrieved, and
compiles. The deprecated pattern from the opening scene travels straight from the wiki to
production, at agent speed, in as many services as asked. Currency needs a mechanism rather than
a virtue: docs that update as a side effect of decisions actually made, with review dates
enforced like expiry rather than aspiration. The metadata this runs on is ordinary governance
hygiene: expiry dates on exceptions, status fields on decision records, a last-verified stamp on
every standard.

### True

The document can be structured, freshly dated, and wrong: the standard that no longer matches
what the platform actually does, the reference architecture describing a system as it was planned
rather than as it runs. Humans route around falsehood with hallway knowledge. Agents enforce it
faithfully, at scale, with citations. Truth is the property that requires the corpus to be
reconciled against reality, which is governance work no retrieval pipeline does for you.

![Three-property gauge for architecture context: parseable, current, true, each with a pass state.](/images/writing/agents-act-on-your-architecture-docs/agents-act-on-your-architecture-docs.d2.svg)

## The function becomes a context supplier

Two outside anchors size the shift.
[Gartner's Predict 2026 research](https://www.gartner.com/en/documents/7173730) on enterprise
architecture expects AI agents to be delivering half of EA outcomes by 2028, which is a forecast
about your artifacts becoming operational surface, whatever you think of analyst timelines. And
Thoughtworks' [Technology Radar Vol. 34](https://www.thoughtworks.com/insights/podcasts/technology-podcasts/themes-technology-radar-34)
made context engineering one of its running themes: the craft of feeding agents the right
context, in the right shape, at the right time. Read from the architecture side, that theme names
a supply chain, and the architecture function is the natural supplier.

A research anchor completes the thought. The
[CHASE '26 study](https://arxiv.org/html/2603.24879) of open source governance treated written
governance documents as "textually observable infrastructure." That was a research method. Agents
have since made it a literal description, because the infrastructure is now executed by machines
that read it.

I've been close to this shift in production, inside the central architecture function of a global
enterprise, through a governance platform built hands-on for exactly this purpose. The design
choice that mattered most: the standards knowledge base updates from approved decisions instead
of manual editing. When a decision or exception is approved, the knowledge base absorbs it as a
side effect of the approval itself, so the manual upkeep that kills every wiki mostly
disappeared, and currency stopped depending on anyone's discipline. Decisions feed the delivery
pipeline rather than a shelf. Qualitative observation, but a durable one: the artifacts that stay
true are maintained as a by-product of the process that creates them, and the artifacts
maintained by good intentions drift within the quarter.

## The lab version, with receipts

My personal site runs the miniature of the same argument, and every mechanism is public:

- An [MCP server](https://github.com/fst-it/felipetavares.dev/tree/main/packages/mcp) publishes
  the site's content as typed tools with validated inputs. An agent calls `search_content` or
  `get_page` and receives structured JSON, drawn from the same core services the HTML pages
  render from, so there is no second copy of the truth to drift.
- An [llms.txt route](https://github.com/fst-it/felipetavares.dev/blob/main/src/pages/llms.txt.ts)
  gives crawling agents the machine-readable index, and markdown twins of the pages serve readers
  that prefer text (documented in
  [ai-ready.md](https://github.com/fst-it/felipetavares.dev/blob/main/docs/ai-ready.md)).
- An [AGENTS.md](https://github.com/fst-it/felipetavares.dev/blob/main/AGENTS.md) at the repo
  root tells coding agents where to start and which rules bind them.

Toy scale, deliberately. The transferable part is the design stance: every artifact assumes a
machine reader first, and the human-readable version is a rendering, never the only copy.

The typed-tool detail deserves a sentence, because it's where "parseable" stops being abstract.
An agent scraping HTML gets whatever survived the render, guesses at structure, and breaks when
the layout changes. An agent calling a typed tool states what it wants in a validated shape and
receives structured data from the same source of truth the site itself renders. The difference in
failure mode is the difference between a rumor and a contract, and it's available to any
architecture function willing to put an interface in front of its corpus.

![The context layer: standards, decision records and the radar feed a typed, addressable context layer, which serves engineers' coding agents, CI gates and chat interfaces.](/images/writing/agents-act-on-your-architecture-docs/agents-act-on-your-architecture-docs.d1.svg)

## Where to start

The order matters less than the discipline, but three moves pay back immediately:

- **Make decision records addressable**: one stable URL per decision, a status field an agent can
  filter on, and supersession links both ways, so a retrieval can tell which of two conflicting
  records won. Your ADRs are the highest-value context you own, because they carry the why that
  stops an agent from helpfully undoing a constraint it never learned about.
- **Declare one canonical source for standards** and make every other copy a pointer. Agents
  can't choose between the wiki, the slide deck and the PDF export; the ambiguity you've
  tolerated for years becomes machine nondeterminism. The pointer pattern is boring and it works:
  every legacy location keeps its URL and gains a one-line reference to the canonical page.
- **Retire dead documents**, actually delete them, because an agent cannot tell your dead docs
  from your live ones. Every page you keep "for reference" is a candidate citation in next
  month's faithfully wrong pull request. The cleanup you postponed as housekeeping is now a
  correctness issue.

## Start with ten standards

Take your ten most-used standards. Give each a stable URL and a machine-readable header: owner,
status, scope, last-verified date. Delete the two that are dead; you know which two. Then point
your own coding agent at the result, ask it to scaffold something the standards govern, and watch
what it retrieves and what it misses.

That corpus is your context layer, version zero. It will be small, incomplete and more honest
than the wiki it replaces, and it's the first architecture artifact you own that works while you
sleep.

Worth taking away:

- **Your documentation is now executed, so hold it to an infrastructure bar**: parseable,
  current, true. Each property fails differently, and "current" is the one that ships defects.
- **Currency comes from mechanisms, never discipline.** Docs that update as a by-product of real
  decisions stay true; docs maintained by good intentions drift in a quarter.
- **Give agents a contract, and stop making them scrape.** Stable URLs and typed interfaces turn
  retrieval from a rumor into a lookup.
- **Deleting dead docs is now a correctness fix**, and it's the cheapest one available to you
  this sprint.