# AI Coding Assistants Can Read Your Code. They Can't See Your Platform.

*Published: April 30, 2026 | Author: David Tuite | Tags: context engineering, ai*

Your AI coding assistant receives the file currently open, whatever retrieval mechanism (keyword, embedding, or graph-based) pulls from surrounding files, and possibly a repo-level index if you've configured one. That is the full extent of its world, with no organizational structure, no ownership, no reliability targets, and no deployment history.

Consider a practical scenario: an engineer asks their assistant to refactor a synchronous downstream call in `payments-service` into retry logic with exponential backoff. The suggestion looks clean. The tests pass. The PR gets approved. But the assistant couldn't see that `payments-service` is already running at 99.91% against a 99.9% SLO, its p99 latency sits at 450ms against a 500ms budget, and the Fintech squad placed a code freeze on it 48 hours ago ahead of a critical release. The retry logic hammers a downstream service that's already degraded, pushes latency past the budget, and burns the remaining error budget in under an hour.

The model produced syntactically correct, architecturally reasonable code. Every piece of information that would have changed its output lived in the service catalog, the observability platform, and the on-call tooling, none of which it could reach. The problem is a missing operational data layer between your engineering metadata and the AI's context window.

## The Four Categories of Missing Platform Context

The industry conversation about context for AI coding assistants has focused almost entirely on codebase coverage: how many files can the retriever pull, how good is the semantic index, and does it understand cross-repo dependencies? [Augment Code's treatment of the context delta](https://www.augmentcode.com/tools/the-context-gap-why-some-ai-coding-tools-break) and [Sourcegraph's breakdown of keyword, embedding, and graph-based retrievers](https://sourcegraph.com/blog/lessons-from-building-ai-coding-assistants-context-retrieval-and-evaluation) describe this codebase-level layer well. While this is important, it's actually the easier half of the problem. The missing context that actually costs engineering teams time and trust falls into four categories.

### Service ownership

[Pete Hodgson's Constraint-Context matrix analysis](https://blog.thepete.net/blog/2025/05/22/why-your-ai-coding-assistant-keeps-doing-it-wrong-and-how-to-fix-it/) highlights that AI assistants carry no awareness of the constraints that only humans in your org hold. If `payments-service` is owned by the Fintech squad, and they have a code freeze in effect, any PR against it requires their explicit review and sign-off. None of this exists in the repository. It lives in `spec.owner` in your service catalog, team topology tooling, or PR process documentation. The assistant treats the code as ownerless.

### SLOs and reliability targets

Adding a synchronous downstream call to a service running a 99.95% availability SLO introduces a tail-latency risk that the model has zero signal for. It can read your retry configuration, but it can't read the Datadog SLO tracking data that tells you you've consumed 78% of this month's error budget. That signal lives in your observability platform and is only surfaced as structured metadata if you've built the bridge from observability to catalog.

### Deployment history and cadence

A major refactor on a service deployed three times a day carries entirely different risk from the same refactor on a quarterly-release service. The `EntityArgoCDHistoryCard` exposes per-entity deployment history (such as revisions, timestamps, commit info, and sync status) at the catalog level. An AI assistant working from the file buffer has no access to whether this service last deployed four hours ago or four months ago, and that cadence signal is material to any reasonable risk assessment.

### Incident history

If `payments-service` generated three P1 incidents in the last 60 days because of connection pool exhaustion under load, and the assistant suggests a pattern that increases connection pressure (spawning additional database clients per request, for instance), that's a regression. Post-mortem context is organizational memory. The model can't infer it from code because it lives in incident reports and runbooks.

## Why Individual Workarounds Don't Scale

Teams are already responding to this missing context with rational, locally effective solutions. Google Cloud's [AI coding assistant best practices guide](https://cloud.google.com/blog/topics/developers-practitioners/five-best-practices-for-using-ai-coding-assistants) recommends GEMINI.md files that give the assistant project-specific context, including what framework you're using, what conventions to follow, and what patterns to avoid. That's a sensible individual workaround for a team of five.

The problem is the maintenance surface. A GEMINI.md file written this morning doesn't reflect the deployment that happened this afternoon or the SLO breach that opened an hour ago. It's a static document maintained by humans in a system that changes continuously. If you have 50 engineers, 200 services, and 10 teams, accurate context file maintenance becomes a full-time job, and there’s little incentive to keep any individual file current because the cost of staleness is invisible until something breaks.

The queryability problem is separate. An AI retrieval pipeline can't ask a GEMINI.md "which services owned by the Payments team have open P1s?" and get a structured answer it can reason over. The file format is designed for human reading, so structured cross-service queries require a different architecture entirely. Because each file lives with its service, the assistant working on Service A has no access to Service B's SLO status even when Service A calls Service B synchronously.

With one hundred engineers and five hundred services, these files are perpetually stale and inconsistently structured, giving teams a false sense of coverage. The context that the AI receives reflects the state of a service as understood by whoever last edited the file, which is rarely the person who owns the service today.

## Platform Context Engineering: The Architectural Shift

Engineering organizations need to identify the authoritative, structured, machine-readable data layer that represents operational reality, and confirm if it has an API surface that AI retrieval pipelines can query. That reframe shifts the problem from prompt engineering (improving how the AI is instructed) to context infrastructure (improving what structured data the AI can retrieve).

Platform-level context engineering requires entities (services, teams, APIs, infrastructure components), relationships (ownership, dependency, responsibility), and operational signals (SLO status, deployment cadence, incident frequency). All of this information needs to be kept current through automation and exposed through a queryable API. Machine-readable, automatically updated data is the baseline requirement. The goal is a structured entity graph that works for both human engineers browsing the catalog and AI agents querying it programmatically.

This is an important distinction for AI retrieval specifically because a pipeline can only return what's structured and indexed. An LLM can ingest an unstructured text file, but it cannot reliably extract "which of the services that I depend on are currently breaching their error budget" from a collection of Confluence pages. Structured entity data with relationships and operational signals enables precise retrieval, which can return specific details like "Payments team, code freeze active, SLO at 99.91%, last deployed 4 hours ago" as a structured response that the retrieval pipeline can return directly.

## Closing the Delta: From Entity Graph to AI Context

Roadie's engineering context platform implements this architecture as a production-ready retrieval layer. The catalog reflects the actual ownership state of the repository without manual maintenance, because each entity carries structured ownership via `spec.owner`, which is populated automatically through the CODEOWNERS integration. Tech Insights surfaces SLO data as structured scorecard metadata: add a `datadoghq.com/slo_tag` annotation to your `catalog-info.yaml`, point the built-in Datadog Data Source at your Datadog instance, and SLO compliance data becomes a queryable fact on the entity, accessible from the same pipeline that serves the AI. Each of these steps still asks service owners to maintain one annotation. That's unavoidable, but it's a big improvement over GEMINI.md files. The right long-term approach is to ingest this association directly from the source systems, so the annotation burden eventually disappears.

The data flow from operational signals to the AI context runs through this architecture:

![Diagram](https://mermaid.ink/img/pako:eAEB2AEn_nsiY29kZSI6ImdyYXBoIFREXG4gICAgQVtFbnRpdHkgQ2F0YWxvZzxici8-c3BlYy5vd25lciArIENPREVPV05FUlNdIC0tPiBFW1JBRyBBSSBQbHVnaW48YnIvPkluZGV4aW5nIFBpcGVsaW5lXVxuICAgIEJbVGVjaCBJbnNpZ2h0czxici8-U0xPIFNjb3JlY2FyZHMgdmlhIERhdGFkb2ddIC0tPiBFXG4gICAgQ1tBcmdvIENEIFBsdWdpbjxici8-RW50aXR5QXJnb0NESGlzdG9yeUNhcmRdIC0tPiBFXG4gICAgRFtUZWNoRG9jcyArIE9wZW5BUEkgU3BlY3NdIC0tPiBFXG4gICAgRSAtLT4gRltwZ1ZlY3RvciBTdG9yZTxici8-UG9zdGdyZVNRTF1cbiAgICBGIC0tPiBHW0xMTSBCYWNrZW5kPGJyLz5BV1MgQmVkcm9jayBvciBPcGVuQUldXG4gICAgRyAtLT4gSFtBSSBDb250ZXh0IFdpbmRvdzxici8-T3duZXJzaGlwICsgU0xPICsgRGVwbG95bWVudCArIERvY3NdIiwibWVybWFpZCI6IntcInRoZW1lXCI6XCJkZWZhdWx0XCJ9In29sJX3)

Roadie's RAG AI Plugin makes this entity graph AI-consumable. It indexes catalog entities, TechDocs, OpenAPI specs, and Tech Insights scorecard data as embeddings, stored in PostgreSQL with the pgVector extension (enabled via `CREATE EXTENSION IF NOT EXISTS vector`). The LLM backend supports AWS Bedrock and OpenAI. The retrieval pipeline is explicitly extensible: teams can add incident post-mortem data, on-call schedules, or architecture decision records as additional indexed sources.

An assistant pulling from this pipeline can receive: "payments-service, owner: fintech-squad, SLO target: 99.95%, SLO status: 99.91% this month (78% error budget consumed), last deployed: 4 hours ago via Argo CD revision abc123f, P1 incidents last 60 days: 3 (connection pool exhaustion)." The assistant now has access to the same judgment inputs that a careful engineer would consult.

For Roadie's cloud-hosted platform, the AI Assistant is configured via Administration > Settings > AI Assistant. For self-hosted Backstage instances, the plugin is available as the `@roadiehq/rag-ai` frontend package with the corresponding backend plugin.

## Three steps to better retrieval context

You don’t need a complete overhaul to improve your retrieval context. There are three steps you can take this week to give your AI retrieval pipeline ownership, reliability, and deployment recency signals.

__First__, audit which services in your catalog have `spec.owner` set. Entities missing that field are invisible to any ownership-aware retrieval. Use CODEOWNERS auto-assignment to populate ownership systematically. The catalog can derive it from your existing file ownership structure, so you're not asking teams to maintain a new artifact.

__Second__, if you're tracking SLOs in Datadog, enable the Tech Insights Datadog Data Source. Navigate to the Tech Insights section in Roadie, add the built-in Datadog Data Source, and annotate your `catalog-info.yaml` files with `datadoghq.com/slo_tag`. Your SLO compliance data becomes a structured, queryable fact on each entity, updated automatically as Datadog updates.

__Third__, if you're using Argo CD, install the Argo CD plugin and add `EntityArgoCDHistoryCard` to your entity page for each service. Link components to their Argo CD applications via the `argocd/app-name` annotation. You get per-entity deployment history, sync status, and revision data, all queryable by any retrieval pipeline you build on top.

All three steps change what AI agents receive without changing how your engineers work with those agents.

[See what structured engineering context looks like for your team and your AI agents. Explore Roadie](https://roadie.io/demo)