AI Promoted Everybody. Architecture as Truth (AAT) Is the New Job.

AI promoted everybody on your team. Most of them have not noticed, and hardly anybody has rewritten the job description.

Take an analyst. Call her Marta. For six years, a good part of her week has gone on turning conversations with the business into acceptance scenarios: about two days for a feature of ordinary size. Last Tuesday she pasted half a page of notes into an AI assistant and had forty scenarios back before her coffee was cool. They were well formed. They covered cases she would have missed.

Three of them were wrong. They were not badly written. They were wrong for her company, where a business customer who returns goods gets a credit note, never a refund, because of how those accounts are settled. Nothing in her notes said so. Marta saw it at once, corrected the three, and went to her next meeting without counting it as work.

It was the only work in the room. Writing the scenarios, the thing her role is named for, took a machine under a minute. Knowing that three of them described some other company took six years. Marta has been promoted. Nobody told her, and she has not told herself.

What AI took over, and what it left

What happened to Marta has happened along the whole line. We run PuglieseWeb, more than sixty repositories across several products, on AI agents, and agents write most of our pull requests. A documentation page that took an afternoon is drafted in minutes. Business scenarios arrive forty at a time. A paragraph describing an idea becomes a board of epics and stories.

All of that is production: writing down, in the right format, something that somebody already understands. It was what our job titles were named for, and what most of us were measured on.

What it left is a shorter list and a harder one:

• Holding the whole product in your head. Who it is for, what it promises them, how one part leans on another.
• Judging what it should become. An assistant will offer ten plausible next steps. Choosing one is a decision about a business, and somebody has to answer for it.
• Noticing when the output is wrong for this system. Generated work is often wrong in general, but a test finds that. The expensive kind is wrong here: for this customer, this contract, this history.

An AI can read your code and tell you what the system does. It cannot tell you what the system was meant to do, what you considered and turned down, or which promise to a customer sits behind a rule that looks odd. In most companies that knowledge is written nowhere a machine, or a new colleague, can read it. It lives in a few heads.

The entry requirement moved

Those heads used to have titles. Understanding the product end to end was the work of architects and product owners. Everybody else was given a slice: a ticket, a screen, a test plan. The arrangement made sense while production was the expensive part: many hands for the production, a few heads for the whole.

Production is not the expensive part any more. A person with a slice of understanding and an AI produces slices very quickly, and cannot tell when they are wrong, because the errors that matter come from outside the slice. The credit note rule was never in Marta’s feature. It was in how the finance team closes the month.

So deep understanding of the product has stopped being a senior specialism. It is the entry requirement for working with AI well. The developer, the tester, the analyst, the product manager and the founder each now direct a machine that builds what it is told and fills every gap with a confident guess. Knowing what to tell it, and knowing when what came back is wrong, is the job. Everybody needs an architect’s sense of how the product fits together and a product owner’s sense of what it is for, whatever their title says.

Telling people to “think like an architect” does not deliver that. Understanding comes from a practice that puts the whole product in front of everyone, every week, in words they can read.

Architecture as Truth

We call that practice Architecture as Truth, AAT for short. This is the definition we work to:

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.

“Architecture” here means more than boxes and arrows: it is everything that says what the product is, what it promises and why.

Five principles hold it up.

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 fifth principle is the one that does the promoting. Every change makes somebody read a decision, a contract and a set of behaviours for a part of the product they may never have touched. After a few months each person will have read well beyond their own part, and a newcomer can follow any part of the product from the decision to the behaviour.

It is how we build our own products: four stages and two human approvals, described in Four Stages, Two Approvals. Our decision repository holds 226 decision records today, and 2,975 dated change records since 8 September, each naming the documents it reconciled.

AAT has relatives. Domain-driven design gave teams a shared language and a model of the business. AAT adds a reader DDD never planned for, a machine, and leaves the modelling to DDD. Spec-driven development is the nearest relative, and AAT uses it. Most specs describe one change and are retired when it ships. Some tools, OpenSpec among them, keep standing specs. AAT sides with those and widens what is kept to the decisions, the contracts and the plan for the whole product. Docs-as-code is the plumbing: where documents live and how they are reviewed, not what authority they carry. Architecture as code turns the checkable parts of an architecture into code. AAT uses those checks and keeps plain prose beside them, because a product manager has to read it.

One 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 Architecture as Truth asks of an AI agent

AAT is a practice, and it needs no product. A Git repository, plain text files, a test runner and the AI agent you already use are enough to start. What it does need is an agent that behaves in a particular way, and that is worth writing as a contract, because it applies to every agent and to everyone who builds one:

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 two of the four today: it can refuse a change that edits an approved file, or that names no documents. The other two can only be asked for, and an agent will sometimes build through a silence, as the example below shows. Its record is what makes that visible. We would like every AI coding tool to meet all four by default. An agent that writes confident code without asking what was decided is guessing, quickly.

One implementation: SystemDox

In one repository, the four rules need little more than a file the agent is told to read. Across dozens, the hard part is getting the same documents to every person and every agent at the same moment. We built SystemDox for that. It reads the documents from the team’s own Git repositories, which stay the source of truth (more than 5,700 documents in our workspace today), renders each change’s brief for the person who approves it, and serves the same files to agents over MCP, the protocol coding agents use to fetch context.

A real exchange from our workspace, trimmed. An agent about to work on a reminder feature asks for context:

get_context
  task_description: "add a text reminder that goes out 24 hours before a
    booking, with a reply of CANCEL cancelling the booking"

## Project Rules (18)
[...]

## Also Indexed (3)
- Reminders before the appointment, in Booking's settings
  [...]/features/appointment_reminders.feature
- ADR-214: Booking sends one or more reminders before an appointment [...]
- Booking API — reminders before an appointment (ADR-214)
  specs/changes/appointment-reminders/openapi.yaml

The agent asked how to build a reminder. The answer was the team’s rules, and the news that the product already has a decision about reminders, a contract and approved behaviours, with where to find them. That is where the first rule starts: the agent now knows what to read before it writes. Working from the code alone, an agent could easily have written a second reminder system.

SystemDox is in private preview: it runs our own engineering every day and is not open to the public yet. AAT does not wait for it. Everything in this article can be practised without it.

What this looks like on a Monday

Take a real change from our own product. On 30 October the request was one sentence: let the booking service remind a business’s customers before an appointment.

Shape. An agent drafted the brief: the decision, the contract and the scenarios. It found that an earlier decision had pencilled these reminders into a separate service, and amended that decision so the two would not disagree. It could do that only because the earlier decision was written down where it could read it. The brief also listed its open questions with a proposed answer each, and the owner accepted them as drafted: reminders stay off until a business switches them on, and they go out only between 8am and 9pm. Those are judgements about customers. An agent can propose them. Somebody has to own them.

Build. An agent built it in one pull request, against scenarios that were also the tests. Nobody was asked to read code.

Release. On 31 October the owner approved the release, and the change was recorded with every document it touched. Reminders were in production, off until a business switched them on.

The catch. The decision said the reminder text would end with the business’s number and never said which. The build agent chose one and said so in its record, where the third rule would have had it stop and ask. That evening the owner read the record and asked which number it was. It was one the business had ticked so that it would be told about its own bookings, in a small business often the proprietor’s own mobile. No test was failing, because no scenario named a number, and no customer had received a reminder. A short amendment changed the decision, the build followed it, and the owner approved the corrected release that night.

In our company the person in that story is one owner. In a team of ten we would expect the readings to divide: the analyst reading the behaviours, the developer the contract, the tester asking what no scenario asked, and one named person approving. All of them would have to understand the product. So far we have run this with one person, not ten.

A promotion, if you take it

Being promoted is not always comfortable. The old job was clear and its output could be counted. The new one is judged by decisions. But look at what went and what stayed. The typing went. The part that needed you stayed: knowing the customer, the promise and the history, and saying what the product should do next.

That part used to be reserved for a few senior people, and now it is open to anyone willing to understand their product deeply. Start small. Pick one part of your product, write down what it promises and why, and put that page where your colleagues and your AI tools will both read it. Then keep it true.

---

Architecture as Truth (AAT) is set out here by Emanuele Pugliese, founder of PuglieseWeb. The text of this article is © 2026 PuglieseWeb LTD and is licensed under CC BY 4.0: you may use, adapt and teach it, on condition that you credit Emanuele Pugliese and link to this page. Interest declared: we build SystemDox, one implementation of AAT, and we can set Architecture as Truth up for your team.