Software team proposes AAT: documents as the single source of truth
Understand this story
A software team has proposed a practice called Architecture as Truth (AAT), which advocates treating architecture documentation—decisions, contracts, behavior, and plans—as the single source of truth for the product: humans make decisions by modifying the documents, AI agents build accordingly, and delivered results are written back into the documents. The practice comprises five principles, requiring documentation to be version-controlled in the same repository as code, changes to be made in the documents first, humans to review documents rather than code diffs, and scenarios to be run as tests. The authors say AI has taken over most productive writing, so end-to-end understanding of the product has shifted from a specialty of senior staff to an entry-level requirement for everyone.
AI overview based on source reports · Updated 11 hr ago
Coverage timeline
Follow the coverage to explore different perspectives.
- Hacker News AIAI Promoted Everybody. Architecture as Truth (AAT) Is the New Job
PuglieseWeb founder Emanuele Pugliese argues that AI now handles most production work—drafting scenarios, docs and pull requests—so deep end-to-end understanding of the product has become the entry requirement rather than a senior specialism. He defines Architecture as Truth (AAT), a practice in which versioned architecture documents (decisions, contracts, behaviours and plan) are the single source of truth that people decide through and AI agents build from, held up by five principles and four rules for agents. He illustrates it with a 30–31 October reminder feature built by an agent, where the owner caught an unspecified phone number in the reminder text, and notes SystemDox, his tool for serving the same documents to people and agents over MCP, is in private preview.
Activity for this story
- Current comparable activity
- 7
- Peak comparable activity
- 10Nov 8 03:00
- Change in the past 24 hours
- –
Trends compare the same fully observed participants, which may cover fewer participants than current activity. Move the pointer or tap the chart to inspect hourly activity; use the left and right arrow keys with a keyboard.