Get everyone the same picture of the system as it is now — first to bootstrap the docs agents lean on, then to keep them honest.
The team friction Two failures bracket agent adoption. At the start, teams point agents at a codebase with no written account of how it actually works — so every agent reconstructs the architecture from scratch, badly. Later, agents refactor and add services faster than anyone’s mental model updates, and the team’s shared picture of “how does our system work today?” quietly fragments — until two people are reasoning about different systems by the same name.
The pattern The team runs a workshop on the architecture as it is now, in two roles. First, before scaling up agents: walk the current system together and capture it as the initial architecture and product documentation the agents will lean on. Then, recurring: re-walk it on a cadence to reconcile drift, mark what changed and why, and refresh the shared model. An agent pre-generates the map from the code; the team’s job is to understand it together and agree what it means.
Why it works with AI Agents need a written account to be productive, and they erode it as they work — so the team has to both create the shared model up front and maintain it on a rhythm. A common, current picture is also what lets the team steer agents instead of guessing: understanding the system together is upstream of directing it well.
Watch-outs Map the system that exists, not an old diagram — ground it in real code. Keep it a working session, not a presentation; the value is shared understanding, not slides. And the kickoff workshop is where the first agent-written docs are born — capture, don’t just discuss.
Related Agent-written shared docs · Product memory · ADRs — record the why · Skill sharing