How to design context for your AI software factory

Two teams run the same incident triage agent, on the same model, against the same production stack. One closes the alert in under two minutes using minimal tokens. The other burns four minutes and several hundred thousand tokens hopping between GitHub, Jira, and PagerDuty, then hands the on-call engineer a root cause by guessing which service is to blame. The model is identical in both cases. What differs is the context each agent was handed, and whether anyone designed it.

That is the hardest open problem in agentic engineering right now, and it is a design problem rather than a tooling one. Once agents run stages of the SDLC instead of autocompleting inside an editor, the factory's output tracks the quality of the context it feeds them. Context design is the discipline that decides that quality: what gets modeled, what stays live, what gets remembered, and who is accountable when it drifts.

“By 2029, 90% of engineering teams will have a dedicated context engineering and management function that specifically supports the build of the SDLC context layer, compared with less than 10% today. “ - Gartner

Why Context Is the Foundation of a Working AI Software Factory

A coding assistant works inside a repo it can read. A factory agent works across the organization, and almost nothing it needs lives in the model or in the code. Take a PagerDuty alert. To act on it, an agent has to know which of your 5,000 repos backs the failing service, which team owns that service, who is on call this week, whether the last deploy went out 20 minutes ago, what the rollback runbook says, and whether this environment requires a human to approve the fix. Every one of those facts sits in a different tool, under a different naming convention.

Most teams answer this by pointing agents at a pile of MCP servers and letting them work it out at runtime. It works in a demo, and it gets expensive fast. Gartner® names context accumulation as the main cost driver for agent workloads, because each step of a workflow reingests a context window that keeps growing. Tool schemas alone can eat 55,000 tokens across a modest five-server setup, with Jira accounting for roughly 17,000 of them, and unoptimized tool definitions have been observed consuming 134,000 tokens before the agent reasons about anything.

SDLC work makes this worse, because it repeats. The process for triaging a payment service alert looks roughly the same on the thousandth run as it did on the first, so an agent that rediscovers the same relationships every time pays the same bill every time.

We tested how much that costs. Across 12,000 production SDLC queries run on Haiku, Sonnet, and Opus, agents querying a pre-related context layer ran about 80% cheaper than the same agents hopping across MCP servers, and the savings held on every model. Cost is the visible half of the problem. The other half is accuracy, since a bloated context window degrades output, so you pay more and get worse answers.

The Three Types of Context Your Software Factory Agents Need

The context layer is split into three different parts: semantics, operational state, and provenance. Mapped onto an agentic SDLC, those become three questions your agents ask on nearly every task.

Semantic context: what things are and how they connect

This is the ontology of your engineering org. service, team, domain, environment, incident, deployment, runbook, and the typed relations between them. Every company defines these differently, which is why a generic schema never survives contact with a real stack.

The relations matter more than the entities. GitHub knows repos, PagerDuty knows schedules, Jira knows tickets, and none of them knows that this repo backs that service owned by that team paged through that schedule. Store those relations once, and the agent reads a service and gets the full picture, instead of reasoning its way to a join it will have to rebuild on the next query.

Shortcuts belong here too. A field like service.on_call or open_incident_count can be computed at ingestion and read directly, which moves arithmetic off the agent and out of the token bill.

Operational context: what is true right now

Semantics tell an agent what a service is. Operational state tells it that the service deployed 18 minutes ago, that the feature flag is half rolled out, and that Maya is on call until Thursday.

Stale operational context is worse than missing context, because the agent acts on it confidently. So freshness is a design decision rather than an integration detail: pick which sources stream events, which ones poll, and what staleness you accept per property. Ownership can lag an hour; deploy status cannot.

Some context should never be stored at all. A file diff, a log tail, or a live cloud cost query is cheaper to fetch through MCP at the moment it is needed than to sync continuously. Drawing that line between stored versus fetched is one of the first calls a platform team makes.

Decision context: what happened before and why

This is the trace: past incidents and their postmortems, which policy got overridden and who approved it, which agent run opened which pull request, what the review flagged.

Without it, your factory repeats its mistakes. With it, an agent recognizes a failure pattern it has seen before and skips straight to the fix. It also gives auditors a straight answer when they ask who approved an autonomous change to a payment service, which is what makes an agentic SDLC viable in a regulated org. Most companies have this context already. It lives in Slack threads and closed tickets, which means agents cannot use it.

What Context Design Looks Like in Three Real Workflows

The three types get abstract quickly, so it helps to walk the workflows most orgs automate first. Each one leans on a different mix.

Autonomous ticket resolution

A scoped ticket arrives, and an agent writes the fix and opens a pull request. Semantic context does the routing: which service the ticket names, which repo backs it, who reviews changes there, what the test and coding standards are for that domain. Decision context does the harder part. How were similar tickets resolved, what does review keep rejecting in this codebase, which classes of change need a human signature. The known failure mode here is specification quality, since a ticket vague enough that a human engineer would ask three clarifying questions produces an agent that silently builds the wrong thing. Good context design absorbs some of that gap by attaching the definition of done, the risk class, and the review policy to the service entity instead of hoping each ticket author restates them.

Self-healing incidents

An alert fires and the agent needs the service, its owner, the on-call engineer, recent deploys, upstream dependencies, the rollback runbook, and the right Slack channel. Designed well, that is one read rather than six tool calls and a reconciliation step.

This is the workflow where operational freshness dominates. An ownership record that lags an hour is survivable; a deploy status that lags five minutes sends the agent after the wrong change. Decision context is what makes the workflow compound, because every resolved incident and postmortem stored against the service means the next matching signature skips investigation and goes to the fix.

AgentOps

The third case is the factory watching itself. Once dozens of agents run across the SDLC, the agents, skills, and MCP servers become entities you model like any other: what each agent may touch, which run opened which pull request, what it cost, which policy it tripped.

This is provenance turned on the factory rather than on the software, and it is the prerequisite for scaling safely. You cannot scope an agent's access, attribute its spend, or retire a duplicate patching agent that no one registered if the agent is not in the model. Teams that skip it end up with agent sprawl and no way to answer who deployed on Sunday.

How Platform Teams Design and Govern Factory Context

Context design is platform work, and it looks more like data modeling than documentation. A few practices hold up across the teams doing it well. Start from the query, not the data. Take your three highest-volume agentic workflows, write down the questions agents ask in each, and work backward to the entities, relations, and properties that answer them in one call. 

1. Treat the model as code. Entity schemas, relations, and mappings go through Git, get reviewed in a pull request, and are promoted from a dev org to production. Context that anyone can change in a UI drifts the same way undocumented infrastructure did. 

2. Write for a machine reader. Descriptions on properties and entity types, markdown attached to entities, and consistent naming across sources cut hallucinations, because the agent stops guessing what svc_tier_2 means.

3. Scope what each agent sees. All-or-nothing access to the full graph is a blast radius problem and a token problem at once. A patching agent does not need the customer PII tables or every tool in the hub.

4. Run an improvement loop. Sample real agent queries every quarter, find the ones that still hop between systems, and fix the model: add the missing relation, mirror the property, retire the entity nobody reads. This is the work that keeps context accurate as teams reorganize and services get renamed.

One finding from our research is worth flagging, because it catches people out. Adding a well-written skill file to a raw MCP setup made things worse, raising cost by 13% to 24% depending on the model, because agents ran the skill as a checklist and executed every step instead of reasoning about which ones they needed. The same skill file on top of a pre-related context layer cut cost further. Instructions do not rescue an unstructured data layer.

What Breaks When Context Design Is Left to Individual Teams

Leave this to individual teams, and you get three patterns, each of which works at small scale and breaks at org scale.

1. The first is the MCP pile. Every team wires up its own servers, and every agent reasons about the same relationships at runtime, so the cost of the join gets paid on every query by every team forever.
2. The second is RAG on its own. Vector search over docs and wikis is genuinely useful for unstructured knowledge, and it is still predictive and bounded by similarity. It surfaces a page that reads like your question rather than a typed relation that answers it, so ownership, dependency, and escalation questions come back as plausible prose.
3. The third is the AGENTS.md repo. A folder of markdown files works well for one team with ten files. At enterprise scale, it becomes tens of thousands of static files, and the moment someone needs live data, they start hand-rolling JSON state files, which is the point where they have begun building a context layer without admitting it.

The organizational damage runs deeper than any of these. Definitions drift, so one team's "service" is another team's "component" and cross-team agents produce conflicting answers. Nobody can audit what an agent knew when it made a call. Token spend has no owner, so it shows up as a line item on an invoice rather than a budget someone manages.

That last point is the argument for platform ownership. The context window is a managed resource with a budget, in the same way cloud spend and CI minutes are, and platform engineering is the team that already productized ownership, golden paths, and standards for the human SDLC. Pre-integrating context moves work from inference time to ingestion time: you pay to build the relations once, and every query after that is cheaper.

Your factory's ceiling is the context you designed for it. Models will keep getting better and cheaper on their own, and none of that progress tells an agent which of your 5,000 repos owns the failing endpoint. The teams that treat context design as a named discipline now with an owner, a review process, and a budget are the ones whose factories keep working at a hundred agents.

FAQ

What is context engineering in an AI software factory?

Context engineering is the practice of designing what goes into an agent's context window: which entities and relations get modeled, which data is stored versus fetched live, how fresh each property stays, and what each agent can see. In a software factory, it sits alongside orchestration and governance as a core platform discipline.

Who is responsible for designing context in a software factory?

Platform engineering owns it. They already productized standards and golden paths for human developers, and context is the same job for agents: model the org once, govern access to it, and hand teams a foundation to build on. Domain teams contribute definitions; the platform team owns the schema and the freshness guarantees.

How do you keep agent context accurate as the engineering org changes?

Treat it as a live system rather than documentation. Sync from source tools continuously with a defined freshness target per property, manage the data model through GitOps so changes get reviewed, and run a regular loop that samples real agent queries to find where the model is missing a relation or serving stale state.

Do agents still need MCP if you have a context layer?

Yes, for different work. The context layer holds the structured, repeatedly queried facts about your org services, owners, relations, history. MCP fetches what is cheaper to pull live than to sync, like a file diff or a log tail. The design question is which data belongs in each, not which one wins.