Current Architecture Workshop

Why this workshop

In almost every product development organization, some parts of the system are truly understood by only a few people. That goes largely unnoticed while those people are around. It shows in handovers that take weeks, in changes with surprising side effects, and in new hires who need a long time before they can work with confidence.

AI agents change this situation in two ways.

An agent can now describe your architecture from the code in a few minutes. That does not mean anyone on the team understands it. Documentation has become cheap, understanding has not. And only people who understand their system can judge whether an agent’s suggestion fits.

On top of that, a second layer has grown up next to the code: instruction files, skills, MCP servers, and permissions. They determine how agents work on your system. They are often scattered, placed differently by each tool, and sometimes exist only on individual machines. A single line in the repository root affects every team, every agent, and every tool. That is architecture, not personal configuration.

What happens in the workshop

The goal is to map the architecture as it is today, not as it should be. The starting point is the use cases: who uses the system, and for what? They form the common thread through every other view, from the structure of the code through runtime to operations and data. That creates the end-to-end view: every flow can be traced through the whole system, not just through the part a single team knows.

In the room are people who have known the system for years and people who are just getting to know it. That mix is what drives the knowledge transfer. I facilitate, and your teams bring the knowledge of your system.

For each view, someone from your teams explains to everyone present what the sketch shows and answers questions. If you like, simply record it on a phone. These are not polished videos, just an easy way in for anyone who was not there.

AI takes part, but it does not go first. It helps find what was missed and does not replace shared understanding.

Gaps are nothing to be ashamed of. Every point where nobody in the room has an answer is a risk found and a concrete learning goal.

Questions the workshop answers

• Who uses the system for what, and which workflows are already handled by AI features?
• How is the code structured, and how is it actually laid out in the repository?
• What runs at runtime, including bots and agents, and what are they allowed to trigger?
• What does the system run on, and which parts can reach models?
• Which data is central, and which of it ends up in a model’s context?
• What may agents do without asking, and where could secrets or data leak?
• Which instructions, skills, and access rights exist, who maintains them, and which of them are team standards?

What you take away

Everything created in the workshop is produced by your teams themselves. It stays with you, and you decide what to do with it. I usually sign a nondisclosure agreement beforehand.

• Sketches of the most important views of your system
• An explanation of each view, optionally as a simple recording for anyone who was not there and for new hires
• Technical memos on what does not fit into any sketch: assumptions, pitfalls, and risks, including the places where AI keeps getting your system wrong
• An overview of your AI artifacts: what stays personal, what the team shares, and what the organization sets
• The open knowledge gaps, as concrete next steps
• The groundwork for your instruction files, so your agents work from the same picture as your teams

Who it is for

Product development organizations where several teams work on one product and use AI agents or are starting to.

The workshop helps most when knowledge of central parts rests with a few people, when new teams must become productive quickly, or when each team keeps its own instructions.

Each workshop covers exactly one product. Mixing several products does not produce a shared picture.

When AI is part of your product

If you use AI not only in development but also in the product itself, the workshop can be extended. It then also covers how the AI features behave, the dependence on models and providers, the limits of their autonomy, and the obligations that follow. Depending on the number of AI features, up to one more day is added.

More about the extension: AI in the product

Background

The format goes back to Craig Larman, one of the two creators of Large-Scale Scrum. I ran the workshop together with him and have used parts of it with several clients since. It builds on Philippe Kruchten’s 4+1 view model.

The extension to AI agents is new. It follows logically: once agents work on the code, their context is part of the architecture a team needs to understand together.