How to Give AI Agents Real System Context in 2026

Your AI coding agent just shipped a change that compiles cleanly, passes every test in CI, and sailed through human review. Three days later it takes down a payment service in production. The code was correct. The decision behind it wasn't — the agent reintroduced a caching pattern your team deliberately killed six months ago, because nothing in the repo told it that pattern was radioactive. This is the defining engineering problem of 2026: agents that are technically fluent and operationally blind. Fixing it requires layering structural context (Backstage, Xirp), a lightweight baseline (AGENTS.md), and a decision/session layer like ZeroShot (the BuildBetter CLI) that carries prior sessions, PR history, and conventions across agents and teammates. This guide walks through each layer and how to assemble them into a stack that actually works.

The Failure Mode: Code That Compiles, Passes Review, and Still Breaks Prod

The most dangerous agent failure in 2026 is not broken code — it's operationally incorrect code. The distinction matters. Technically correct code is syntactically valid, type-safe, and green in CI. Operationally correct code also respects the realities the agent never saw: the service it doesn't own, the downstream consumer it didn't know existed, the pattern a prior team abandoned on purpose.

Consider a common scenario. An agent is asked to speed up a slow endpoint. It adds an in-memory cache — a textbook fix. The code is clean. CI passes. The reviewer approves the diff in ninety seconds. What neither the agent nor the reviewer knew: that service runs three replicas behind a load balancer with sticky sessions disabled, so the cache produces inconsistent reads across pods. The team hit this exact wall last year and switched to a shared cache with explicit invalidation. That history lived in a closed PR and two engineers' memories, not in the code.

This is worse than a syntax error for one reason: it defeats every safety net you built. A syntax error dies in CI. An operationally-incorrect change is green everywhere and surfaces only in production, where the blast radius is largest and the on-call engineer has the least context.

Treat 'technically correct' and 'operationally correct' as two separate quality gates. An agent can max out the first while completely missing the second, because the second lives outside the code.

System context has two structurally distinct halves. Structural context answers who owns what and what depends on what. Historical or decision context answers why the last decision went the way it did. Most tooling covers only the first.

What 'System Context' Actually Means for an Agent

System context for an AI agent is the set of facts about your systems and your decisions that make a change operationally safe. It breaks into six concrete categories:

• Service ownership — which team owns a service and who is on-call for it.
• Dependency graph — what a service depends on and what depends on it (its blast radius).
• Architectural decision records (ADRs) — the documented reasoning behind structural choices.
• Team conventions — the informal rules a stack follows: error handling, logging, migration patterns, naming.
• Prior sessions and PR history — what agents and teammates already tried, accepted, and rejected in the same area.
• Operational constraints — SLOs, deploy windows, feature-flag state, migration status.

Structural context lives in catalogs and metadata — machine-readable, relatively stable, and already maintained by many orgs. Decision context lives in people's heads, past PRs, and prior agent sessions. It's messy, unstructured, and constantly changing.

The systematic blind spot is this: catalogs tell an agent WHAT the system is; they rarely tell it WHY the system is that way. The rest of this guide follows that split — the catalog approach for structure, AGENTS.md as the baseline, and a session/decision layer for the part catalogs can't hold.

The Catalog Approach: Backstage and Xirp

Backstage is the structural source of truth many engineering orgs already run. A CNCF Incubating project used by thousands of companies, its software catalog holds service ownership, component relationships, dependency metadata, and TechDocs — originally built to help humans navigate a sprawling system, now doubling as an ideal substrate for agent-consumable structural context.

If your org already maintains a Backstage catalog, you have the WHAT layer sitting right there. The question is how to feed it to an agent.

Xirp: making the catalog agent-readable

Xirp is a Spotify Portal/Backstage plugin that surfaces service ownership, dependency, and architecture context to AI agents. Its tagline says it plainly: "Know your systems. So your agents can too." Xirp is model-agnostic and does two things well. First, it turns the Backstage catalog you already maintain into context an agent can actually consume. Second, it auto-generates self-updating documentation from each agent session — closing the doc-staleness loop that plagues manually maintained TechDocs.

That second capability is underrated. Documentation rots the moment it's written; Xirp regenerates docs from what agents actually did, so the structural picture stays current instead of drifting.

Where the catalog stops

Backstage and Xirp hold structural truth well. But three things sit largely outside them:

• Decision rationale — the WHY behind an architecture.
• Informal team conventions — the rules that never made it into an ADR.
• Cross-agent session history — what other agents and teammates already tried.

None of these are catalog failures. They're a different kind of context that a catalog is not structured to store. That's the gap the next layers fill.

The Lightweight Baseline: AGENTS.md

AGENTS.md is the minimum viable system-context artifact: a plain file checked into the repo alongside your code, containing build and test commands, conventions, do-not-touch areas, and ownership hints. It has become a de facto standard, referenced by tools including OpenAI Codex, Cursor, and others as the repo-level agent instruction file.

It works for three reasons:

• Model-agnostic — the same file works across Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, and Amazon Q.
• Version-controlled — it lives in git, so it evolves with the code and shows up in diffs.
• Co-located — it sits next to the code the agent edits, so there's no lookup step.

Where it stops: a single flat file doesn't scale to a large monorepo, can't load conditionally (the agent reads the whole thing regardless of what it's touching), and captures conventions without the reasoning behind past decisions. It tells an agent "we use repository pattern here" but not "we tried the active-record approach in Q1 and abandoned it because migrations became untestable."

Start with the floor before the ceiling. Ship AGENTS.md in every repo first — it's version-controlled, model-agnostic, and lives next to the code — before investing in catalog or session layers.

Every team should have AGENTS.md before layering anything more sophisticated on top. It's the floor, not the ceiling.

The Missing Layer: Sessions, PR History, and Decisions

Prior sessions, PR history, and team conventions ARE system context — and they're the exact part catalogs structurally cannot hold. Go back to the caching example. The agent didn't need a better dependency graph. It needed to know that three months ago the team rejected the precise pattern it was about to reintroduce, and why. That's decision truth, and it lives in a closed PR and a Slack thread, not in any catalog.

Where ZeroShot fits

ZeroShot — the BuildBetter CLI, run as bb — is the evidence-based context layer that saves, indexes, and shares every coding session across teammates and across agents. It is not another coding agent. It's the memory and decision layer that makes Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, and Amazon Q work together with your whole team's history.

ZeroShot embraces the AGENTS.md standard and extends it with BB-Skills: composable, conditional skill packs that load only when relevant, encoding a team's actual conventions. Instead of a flat file every agent reads in full, skills like /bb-review, /bb-specify, and /bb-plan activate contextually — the review skill fires on a review, the spec skill on a spec.

The cross-teammate resume workflow is where the decision layer becomes tangible. Running bb agent-sessions resume picks up any teammate's session on your machine, in any agent. If a colleague spent Tuesday wrestling with a migration and hit a dead end, you don't start cold — you resume their context, dead ends and all. No catalog captures that.

Uniquely, ZeroShot pulls customer evidence from BuildBetter.ai into specs and PR reviews, so agents build what customers actually asked for rather than what the ticket vaguely implied. It's used by Brex, Rappi, PostHog, AppFolio, Clay, Lufthansa, Procore, and Macmillan.

To be clear about the boundary: ZeroShot is the memory and decision layer, not a service catalog. Pair it with Backstage and Xirp for structural context. Each holds a different half of the picture.

The Broader 2026 Landscape of Context Tools

Several tools now target different slices of the agent-context problem. They're complementary layers, not interchangeable competitors.

• agent-hop (open source) — search and resume any chat across Claude Code, Codex, OpenCode, Pi, and Grok Build. Local only, no account required. It overlaps the resume workflow with a lightweight, privacy-first footprint — a solid fit for teams that want session recall without any cloud dependency.
• HQ by Indigo — a file-based "company brain" of skills, knowledge, and workflows, with reusable /skills across a team and persistent Slack/email agents. Strong on turning institutional knowledge into shared, callable capabilities.
• KiroCrew — a persistent agent workspace on your own hardware, where corrections become durable lessons and sessions and memory survive restarts. Good for teams that want long-lived, on-prem agent state.
• skillrank (open source; also bb skills) — indexes the public agent-skill registry with security scans and evals. This matters because conventions encoded as skills need to actually run and prove they earn their token cost.

The takeaway: structural context, decision context, and skill context each need a home. No one of these tools is the whole answer, and dismissing any of them means leaving a layer empty.

Comparison: Where Each Tool Holds System Context

No single tool covers every dimension of system context. The practical answer is a catalog layer plus a decision/session layer plus a skills layer. This table maps who leads where.

Capability	ZeroShot (bb)	Backstage	Xirp	AGENTS.md	agent-hop	HQ by Indigo
Cross-agent session memory	✅ Lead	❌	Partial	❌	✅	Partial
Team conventions (conditional skills)	✅ BB-Skills	❌	❌	Partial (flat)	❌	✅
Architectural rationale / decisions	✅ PR history	Partial (ADRs)	Partial	❌	❌	Partial
Customer evidence in specs/reviews	✅ Unique	❌	❌	❌	❌	❌
Service ownership	Via catalog pairing	✅ Lead	✅	Hints only	❌	❌
Dependency graph / blast radius	Via catalog pairing	✅ Lead	✅	❌	❌	❌
Self-updating docs	Session-indexed	Manual TechDocs	✅ Lead	❌	❌	Partial
Model-agnostic	✅	✅	✅	✅	✅	✅
Open source	BB-Skills open	✅	Plugin on OSS	✅ (standard)	✅	❌

Read the rows honestly. Xirp and Backstage lead on structure and self-updating docs. agent-hop leads on lightweight, local session resume. ZeroShot leads on cross-agent session memory, encoded conventions, and — uniquely — customer evidence in specs and reviews. Combine the leaders; don't expect one column to fill the rest.

Checklist: What an Agent Should Know Before Touching a Service

Before an agent modifies a service, it should have a green answer to each of these. A red column here means the agent is guessing.

• Ownership and on-call — who owns this service and who is paged when it breaks. (Catalog)
• Blast radius — what depends on it and what it depends on. (Catalog / dependency graph)
• Governing decisions — which architectural decisions apply and which patterns were previously rejected, and why. (ADRs + PR history)
• Conventions for this stack — enforced as skills that load conditionally, not as a wiki page nobody reads. (BB-Skills)
• Operational constraints — SLOs, deploy windows, feature-flag state, migration status. (Catalog + ops metadata)
• Prior sessions in this area — resumable teammate and agent context, not a cold start. (ZeroShot session memory)
• Customer-facing intent — what was actually requested and why. (BuildBetter.ai evidence)

Every item maps to a specific layer. When any layer is missing, the gap shows up as an operationally-incorrect change that passes review.

A Practical Rollout: From AGENTS.md to a Full Context Stack

You don't need to build the whole stack at once. Each layer is useful on its own, and none requires ripping out an existing agent.

Step 1 — Ship AGENTS.md in every repo

Start with the floor. Add build/test commands, conventions, do-not-touch areas, and ownership hints. Version-controlled, model-agnostic, co-located with code. This alone eliminates a class of dumb agent mistakes.

Step 2 — Wire the structural catalog

Connect Backstage (and Xirp to make it agent-readable) so agents can read service ownership and the dependency graph. If you already run Backstage for humans, this is mostly plumbing.

Step 3 — Add a decision/session layer

Install ZeroShot (bb) so past sessions, PR history, and conventions travel across teammates and across agents. This is the layer that would have caught the caching regression — the agent would have seen the rejected pattern before writing it.

Step 4 — Encode conventions as measurable skills

Turn conventions into BB-Skills that load conditionally, and measure them with evals (skillrank / bb skills) so they earn their token cost. A skill that can't be shown to run correctly and improve outcomes is context bloat, not context.

Step 5 — Close the loop

Combine self-updating docs from sessions (Xirp) with indexed session memory (ZeroShot) so context stays fresh instead of rotting. The system documents itself as agents work, and the decision history compounds instead of evaporating.

Adopt incrementally. Steps 1 and 2 give immediate value; steps 3 through 5 turn a collection of agents into a team with shared memory.

Frequently Asked Questions

Why does an AI agent write correct code that still breaks something?

Because it's missing structural or decision context — service ownership, the dependency graph, or the rationale behind a prior pattern. The code is locally valid, but the agent optimized without seeing operational reality: who owns the service, what depends on it, or why a pattern was previously abandoned. The result is code that compiles, passes CI, and passes review, then breaks prod.

Is AGENTS.md enough on its own?

No — it's the necessary floor, not the ceiling. AGENTS.md is excellent for build/test commands, conventions, and do-not-touch areas because it's version-controlled, model-agnostic, and lives next to the code. But a single flat file doesn't scale to a large monorepo, can't load conditionally, and captures conventions without the reasoning behind past decisions or the dependency graph.

What does Xirp do, and does it replace Backstage?

Xirp is a Spotify Portal/Backstage plugin that surfaces service ownership, dependencies, and architecture to AI agents and auto-generates self-updating docs from each session. It's model-agnostic. It builds on Backstage's catalog — it doesn't replace it. Its tagline captures the intent: "Know your systems. So your agents can too."

How is ZeroShot different from a service catalog?

A catalog holds structural truth — what the system is (ownership, dependencies, architecture). ZeroShot holds decision truth — prior coding sessions, PR history, team conventions, and customer evidence — and carries it across agents (Claude Code, Cursor, Codex, Copilot, Gemini CLI, Windsurf, Amazon Q) and across teammates. It's the memory/decision layer, not a catalog; you pair it with Backstage/Xirp for structural context.

Can these tools work together?

Yes, and they should. A catalog layer (Backstage/Xirp) for structure, a session/decision layer (ZeroShot) for rationale and memory, and a skills layer (BB-Skills/skillrank) for enforceable conventions are complementary, not mutually exclusive. No single tool covers all three, so the practical answer is a layered stack you can adopt incrementally.

Do agents need cloud sync for shared context?

Not necessarily. agent-hop is local-only with no account required. ZeroShot is privacy-first and keeps data in your repo. Pick based on your team's data posture — some teams want zero cloud footprint, others want durable shared memory across a distributed team. Both approaches solve the resume problem; they differ on where the data lives.

Make churn optional.

Context-blind agents don't just break prod — they ship the wrong thing entirely, because they never saw what the customer actually asked for. ZeroShot pulls customer evidence from BuildBetter.ai straight into specs and PR reviews, so your agents build what customers want the first time. See how BuildBetter closes the loop between customer intent and shipped code.

Make churn optional. → Book a demo