Shared Agent Context: Versioning What AI Agents Know

What it is

Treating what an agent needs to know about the codebase, conventions, architecture, house style, prior decisions, as a versioned artifact that lives in the repo and gets reviewed like code, instead of something someone retypes into a prompt every session.

Fig. 1

A versioned store feeds every agent session on the read path; a contribution travels its own path through CI validation before it ever reaches the store. Hover a box to trace its connections. Original diagram, not a reproduction. Click to enlarge.

Why you need it (in a large team)

Without this, every agent session starts from zero. It either re-derives your conventions from scratch or guesses wrong, and at the volume these companies run agents, that's not a rare inconvenience, it's the default outcome of most sessions.
Uber's skills marketplace alone serves more than 30,000 executions a day. Re-deriving context that many times over would be its own enormous hidden cost, separate from whatever the agent is actually being asked to do.
Making context a stored, versioned thing turns that repeated cost into a one-time one, paid down as the store improves rather than every single session.

How it should work

The context has to live somewhere durable and inspectable, not in a person's prompt history. Shopify's agents work against World, its monorepo, described as containing not just code but skills, conventions, intent documents, runbooks, and AGENTS.md files directly. Uber's version is heavier machinery, an AI Context Graph built from more than 30 source systems, but the principle is the same: context is infrastructure with an owner, not a prompt someone remembers to paste.

The best evidence in this roster points at contribution mattering as much as storage. Zalando treats its skill collection as something the organization discovers rather than something a central team designs up front, in Bartosz Ocytko's own words, "by encouraging broad contribution of skills that teams found useful, we got an opportunity to discover and disseminate best practices across the organization." That only works safely because contributions get syntax-validated in CI before they land, the same review discipline applied to code applied here too.

Format portability is a smaller but real problem underneath all of this. Stripe standardized on Cursor's rule format and then synced it separately to stay compatible with Claude Code, an explicit acknowledgment that context written for one agent harness doesn't automatically work in another.

Where it fits into a software factory

This is the memory underneath the muscle. Background agents produce the change; the MCP gateway and model router give them somewhere to reach and something to reach it with; this is what tells them what "correct" looks like in your specific codebase before they start. None of the other patterns in this series work well without it, they just work generically instead of specifically.

What you should look for when deciding on one

Bottom-up discovery or top-down design, decided honestly. Zalando's approach, letting teams surface what actually helped them rather than mandating a structure in advance, is a deliberate bet, not the absence of a plan. A top-down design might cover more ground faster; a bottom-up one tends to reflect what people actually use.
Whether contributions are actually validated before they ship, not just accumulated. Zalando's CI syntax check is the difference between a living, curated resource and a junk drawer that happens to be searchable.
Whether the format travels across whatever agent harnesses your teams actually use. Stripe's answer was to maintain a sync step between two formats rather than pick one and force everyone onto it, worth noting as a real cost of supporting more than one harness, not a solved problem.