Architecture as Truth (AAT)

The five principles

1. Write the truth down, in words the whole team can read. If it is not in the documents, it has not been decided. The documents live in version control, beside the code.
2. Decide in the documents, before the build. A change to the product begins as a change to the truth. People approve documents, not diffs.
3. One truth for people and for agents. The file a person approved is the file the agent is given at the moment it writes. No second copy in a wiki, no private prompt.
4. Hold the system to the truth, and the truth to the system. The scenarios run as tests. The contract is tested against the real code. Every change is recorded with the documents it touched, each one updated or marked unchanged with the reason. When a document and the system disagree, one of them has a defect, and it gets fixed.
5. Everyone reads, and anyone corrects. Understanding the product is not a role. The documents are short and plain enough for the analyst, the tester and the founder to read, and whoever knows better says so before anything is built.

The four rules for an AI agent

1. Read before writing. Before it changes anything, the agent fetches the decisions, the contracts and the behaviours that govern what it is about to touch.
2. Build what was approved. It may not edit a contract, or the wording of a scenario, to make its own work pass.
3. Stop, do not patch. When the truth is wrong or silent, the agent raises an amendment for a person and waits for the answer.
4. Leave the truth true. Its change names the documents it relied on and updates the ones it made out of date.

A pipeline can enforce the second and the fourth today, and the two checks in the repository do. The first and the third can only be asked for. An agent will sometimes build through a silence, and its record is what makes that visible.

The caution about the name

The running system is the fact. The architecture is the truth about what that system is meant to be, and why. AAT is the discipline of never letting the two drift apart quietly.

What it needs

A Git repository, plain text files, a test runner and an AI agent held to the four rules. No particular product.

Start in an hour

1. Copy the starter into a new repository, or its docs/ folder, AGENTS.md and workflow into an existing one.
2. Pick one part of your product. Write down what it promises and why: one decision, one contract, one feature file of scenarios, and the plan.
3. Merge the documents. That is the approval, and it is a person's.
4. Ask your AI agent for a change. It reads AGENTS.md, then the documents, and builds from them.
5. Read the record it wrote, not the code. Then keep the documents true.

The agent file alone is enough to begin. Your tool reads AGENTS.md at the root of the repository; Claude Code reads it through a one-line CLAUDE.md.

curl -fsSLO https://architectureastruth.org/AGENTS.md

The starter holds templates for each kind of document, a worked example and a workflow that runs both checks on every pull request:

For people who build AI coding tools

The four rules apply to every agent and to everyone who builds one. Each comes with a question and a way to test it.

A tool that passes all four by default may say it meets the four rules of Architecture as Truth 1.0. The checklist describes each test.

Implementations and adopters

Tools and teams are listed as they report. Nobody outside the author's company has reported adopting AAT yet. If you try it, add yourself.

How to cite

Quote the wording as it stands and give the credit line:

BibTeX

@misc{pugliese2026aat,
  author       = {Pugliese, Emanuele},
  title        = {Architecture as Truth ({AAT})},
  year         = {2026},
  month        = nov,
  version      = {1.0},
  howpublished = {\url{https://architectureastruth.org/}},
  note         = {First published at https://www.puglieseweb.com/blog/architecture-as-truth}
}

The repository carries a CITATION.cff, which GitHub turns into APA and BibTeX on request.

Versions

A changed wording is a new version with a date, never a quiet edit. The changelog records each one.