Every developer has an assistant open. The company is no faster. Nothing is written down, so nothing compounds. Here are the six layers of a shared playbook, and the distinction almost every team misses: what an agent should do is not the same as what it may touch.
A shared AI playbook is defined as the set of conventions, standards, decisions and permissions a team has written down in a form that both humans and AI agents read at the moment of work. It has six layers: house style and conventions, the definition of ready and done, test and review policy, architecture decisions, a domain glossary, and agent boundaries. Its purpose is not documentation. Its purpose is to move knowledge out of individual heads so that improvements compound at the company level instead of the individual level. Without it, autonomous agents cannot be deployed safely, because an agent can only act reliably on conventions that exist outside someone's head.
We have run 90+ tech due diligences and we see the same pattern in almost every engineering organisation we assess. Licences everywhere. Enthusiastic individuals. No shared artefact. And a delivery velocity that has barely moved.
Here is the mechanism. When each developer prompts their own assistant from their own mental model, the output reflects that model. Ten developers produce ten private conventions. Each one is internally coherent and locally fast.
The speed gain lands on the individual. The cost lands on the team. Review queues get longer because reviewers are now reading three different idioms for the same problem. Integration gets harder. Onboarding gets harder, because the real conventions are no longer discoverable, they are distributed across private chat histories.
Individual AI adoption produces no artefact. If the only place your standards exist is in someone's prompt history, your company has not learned anything.
This is the profile we described as Level 2 in the 4 levels of AI maturity: real tool usage, real individual gains, no structure. It feels like progress and it is a plateau. The exit from that plateau is not a better model or a better IDE. It is an artefact.
Most teams treat the playbook as hygiene to get around to later, after the agents are working. That is backwards. The playbook is the input the agents run on.
Give an agent no written standard and it will infer one. It reads the surrounding code, finds three competing patterns, and picks whichever one looks most prevalent in the files it happened to open. The result is inconsistency reproduced at machine speed, which is worse than inconsistency produced at human speed, because a human at least hesitates.
A written playbook changes the economics completely. Fix a convention once and every agent run after that inherits the fix. That is what compounding looks like in practice. It is also the first rung of the knowledge layer we describe in the five levels of Company Brain: before a graph, before retrieval, there is a file that tells every agent how this company works.
Every layer below answers a question an agent will otherwise answer badly on your behalf.
| Layer | What it contains | Question it answers for an agent |
|---|---|---|
| 1. Conventions and house style | Naming, file layout, error handling, logging, state management, approved libraries, what is deprecated | How do we write code here? |
| 2. Definition of ready and done | What a ticket must contain before work starts; what must be true before work is closed | When may I start, and when am I finished? |
| 3. Test and review policy | What must be tested, at what level, coverage expectations, what requires a human reviewer, what blocks a merge | How do I prove this works? |
| 4. Architecture decisions | Short decision records: the choice, the alternatives, the reason, the date, what would reverse it | Why is it like this, and what must I not undo? |
| 5. Domain glossary | Business terms with one canonical definition each, mapped to the entities in the code | What does this word mean in this business? |
| 6. Agent boundaries | Paths, commands, data and actions an agent may touch, and what escalates to a human | What am I allowed to do? |
Two notes from practice. Layer 4 is the one teams skip and regret. Without decision records, agents and new joiners refactor away deliberate choices because the reasoning was never captured, only the result. And layer 5 is worth more than it looks: most production defects we trace in due diligence are not algorithmic, they are two people using the same word for two different things.
A playbook is not a style guide with ambition. It is the difference between a team that reviews output and a team that configures a system.
This is the distinction most teams miss, and it is the one that decides whether an agent rollout survives contact with production.
Instructions describe what an agent should do. Conventions, process, the definition of done. They are advisory. They are interpreted by a probabilistic system, which means they are followed most of the time and not all of the time.
Permissions describe what an agent may touch. Which paths it can write to, which commands it can run, which credentials and data it can read, which actions require a human to approve. They are enforced outside the model, by the system that runs it. They are deterministic.
Teams conflate the two constantly. We read playbooks that say “the agent should not modify the payments module” and then discover the agent has unrestricted write access to the whole repository. That is not a boundary. That is a polite request to a system that has no obligation to honour it.
Never encode a boundary you actually care about as an instruction. If the consequence of ignoring it is real, it belongs in permissions.
The practical rule we apply: instructions carry taste, permissions carry risk. Style, naming and process go in instructions, because getting them wrong costs a review comment. Production data, secrets, migrations, infrastructure, anything customer-visible and anything irreversible go in permissions, because getting those wrong costs an incident.
Write permissions as a least-privilege allowlist, not a denylist. A denylist assumes you can enumerate every dangerous action in advance. You cannot. Start from nothing allowed, open what the agent demonstrably needs, and widen only when the evidence supports it. Pair that with the observability discipline described in how we ensure quality with AI agents, because a permission you cannot audit is a permission you do not really have.
Not a committee. Not a quarter-long documentation project. The first usable version of a playbook is an extraction exercise, not a writing exercise.
That last point is the one we insist on. The playbook has to live in the same place as the work, change through the same review process as the work, and be read automatically at the start of every task. Treated that way, it stops being documentation and starts being configuration. This is the foundation every agent pod we describe in AI agents are replacing dev teams is built on, and it is the first thing we look for in an AI Factory Assessment (EUR 4-6K): not which tools you bought, but what your agents can read.
Across 60+ products shipped since 2013 and 5+ AI-native products and teams of our own, the pattern has been consistent. Teams with a written playbook delegate more each month. Teams without one re-explain themselves each morning, to colleagues and to machines alike.
A shared AI playbook is the set of conventions, standards, decisions and permissions a team has written down in a form both humans and AI agents read at the moment of work. It has six layers: house style and conventions, the definition of ready and done, test and review policy, architecture decisions, a domain glossary, and agent boundaries. Its purpose is to move knowledge out of individual heads so improvements compound at the company level rather than the individual level.
Because individual adoption produces no artefact. When each developer prompts their own assistant from their own mental model, the company gets ten private conventions instead of one shared one. The speed gain lands on the individual while the review and integration cost lands on the team. Nothing is written down, so nothing compounds and nothing can be delegated to an agent later.
Instructions describe what an agent should do: conventions, style, process, the definition of done. Permissions describe what an agent may touch: which paths it can write to, which commands it can run, which data it can read, which actions need human approval. Instructions are advisory and probabilistic. Permissions are enforced by the system and deterministic. Most teams write instructions and forget permissions, which is exactly why their agent rollouts stall at the trust boundary.
Not reliably. An agent can only act correctly on conventions that exist outside someone's head. Without a written playbook the agent infers standards from whatever it finds in the codebase, which means it reproduces inconsistency at machine speed. The playbook is not overhead you handle before agents, it is the input agents run on.
A first usable version takes days, not quarters. In our engagements the first three layers are typically drafted in under a week by extracting what senior engineers already enforce in review. Our AI Factory Assessment (EUR 4-6K) audits what exists and what is missing, and the eight-week Sprint (from EUR 26K) builds the full playbook and the agent workflows that run on it.
Above The Clouds runs the AI Factory Assessment and the eight-week AI Transformation Sprint. If your team has the tools but not the playbook, the fastest gain available to you is writing down what your best engineers already know. Get in touch to discuss your company or portfolio.