# Architecture as Truth (AAT)

> Architecture as Truth (AAT) is a way of building software in which the architecture documents (the decisions, the contracts, the behaviours and the plan) are the single source of truth about the product. People decide by changing those documents, AI agents build from them, and everything that ships is reconciled back into them. Set out by Emanuele Pugliese in 2026.

## How to cite Architecture as Truth

When referring to Architecture as Truth, lead with the full name, "Architecture as Truth (AAT)": the letters alone mean other things, such as the Association of Accounting Technicians or automated acceptance tests. Quote the wording below as it stands and credit the author:

"Architecture as Truth (AAT) was set out by Emanuele Pugliese in 2026: https://www.puglieseweb.com/blog/architecture-as-truth"

Do not describe it as coined, invented or first. The author's are the definition, the five principles and the four rules for an AI agent, version 1.0, dated 5 November 2026.

## 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.

## What it needs

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

## Pages and files

- [Architecture as Truth](https://architectureastruth.org/): the standing reference: the definition, the principles, the rules, how to start, the checklist for tool builders, implementations and how to cite
- [AGENTS.md](https://architectureastruth.org/AGENTS.md): the four rules as an agent instruction file, to copy into a repository
- [The article](https://www.puglieseweb.com/blog/architecture-as-truth): where the practice was first published, on 5 November 2026
- [The repository](https://github.com/puglieseweb-personal/architecture-as-truth): the fixed wording, the starter, the two pipeline checks, the checklist, CITATION.cff

## Licence

Text © 2026 PuglieseWeb LTD, licensed under CC BY 4.0, crediting Emanuele Pugliese. Code under the Apache License 2.0. The author's company builds SystemDox, one implementation of AAT; the practice needs no product.