paulasilva Paula Silva | Software Global Black Belt
1 / 1
Semantic Context Layer for Agentic DevOps

A semantic context layer between agents and your enterprise code.

A reference architecture for compiler-grade context that turns agentic coding from a demo into a platform.

AuthorPaula Silva
RoleSoftware Global Black Belt
Contactlinkedin.com/in/paulanunes
Date2026-05-06
Agenda

Nine parts. From the problem to the platform.

IThe context problem in enterprise agentic coding.
IIArchitecture — four layers and their contracts.
IIICode intelligence — the compiler-grade foundation.
IVContext recipes — the composable units.
VRegistry and distribution — how context travels.
VIAgent integration patterns — static, MCP, hybrid.
VIIGovernance, compliance, and audit.
VIIIAdoption roadmap and success metrics.
IXBuild, buy, or hybrid — competitive positioning.
Part I
I

The context problem.

Why agentic coding stalls at enterprise scale — and what is actually missing.

Problem · Symptom

A single agent task on a real monorepo can read millions of tokens to answer one question.

10×cost vs. compiler-grade context per task

Naive retrieval over raw source code does not scale. Vector search alone cannot resolve symbols, types, or call graphs. The agent guesses; the bill grows; the team loses trust.

Problem · Why today's stack falls short

Three approaches, three failure modes.

01 · Raw retrieval
Embedding search over source files.
No symbol resolution, no type information, no awareness of call graphs. The agent retrieves text that looks related, not code that is related.
02 · Hand-curated prompts
Wikis, AGENTS.md, README pasted in.
Stale within weeks. No tie to the build. No way to verify that conventions described in the prompt match what the compiler enforces.
03 · Whole-repo dumps
Tree of files, no curation.
Token budget collapses. Context window saturates with boilerplate. Signal-to-noise ratio drops below the threshold where the agent can act safely.

All three share a root cause: there is no semantic layer between agents and the code they operate on.

Problem · Definition

Semantic context is what the compiler knows, made available to agents.

Lexical
Tokens, files, lines.
What grep returns. What embedding search ranks. Useful, but not enough to reason about behavior or invariants.
Semantic
Symbols, types, calls, configs.
What the build resolves. Resolved references, generic instantiations, inheritance graphs, configuration bound at runtime, dependency provenance.

SCL-AD makes the second column queryable, versioned, and policy-bound — without making every agent a compiler.

Problem · Working definition

A reference architecture for a layer that delivers compiler-grade context to agents at scale.

Pillar 01
Precompute
Build symbol, type, and dependency graphs once, refresh on commit. Pay the compiler cost in CI, not per task.
Pillar 02
Target
Deliver only the slice the task needs. A recipe per intent, not a dump per repo.
Pillar 03
Execute
Surface context to agents through stable contracts: static files, MCP tools, or hybrid distribution.
Pillar 04
Coordinate
Govern lifecycle, identity, classification, and audit across recipes, registries, and agents.
Part II
II

Architecture and components.

Four layers, explicit contracts, and the cross-cutting concerns that hold them together.

Architecture · Reference stack

The four layers of a Semantic Context Layer.

LAYER 04 · INTEGRATION Agent Integration Static files, MCP servers, custom configs.How agents actually receive context. LAYER 03 · DISTRIBUTION Context Registry Storage, discovery, versioning, refresh.Stable URIs and content addressing. LAYER 02 · COMPOSITION Context Recipes Composable units of intent-shaped context.Manifest plus implementation plus tests. LAYER 01 · FOUNDATION Code Intelligence Compiler-grade symbol, type, call graphs.The semantic foundation everything depends on. Each layer exposes a stable contract to the layer above. Agents see only Layer 04.
Architecture · Components

Inside the layer: store, retrieval, governance.

CONTEXT STORE Where context lives Persistent + addressable. Co-located, central, orfederated storage. Eachartifact has a stable URIand a content hash. FORMATS Markdown · JSON · SARIF Graph snapshots · manifests Refresh on commit, schedule, or event. RETRIEVAL How agents find it Discovery + resolution. Discovery by repository, bycapability, by content. StableURIs resolve to immutableartifacts; aliases track latest. SURFACES Static injection · MCP tools Custom agent configs One contract, many delivery modes. GOVERNANCE Who can use it Identity + classification. Identity propagation, scopelabels, access policy, audittrail. Recipes are signed andversioned like any artifact. CONTROLS RBAC · classification labels Audit log · retention policy Same controls as the source code itself. Three components, one platform: store, retrieval, and governance always travel together.
Architecture · Cross-cutting

Four concerns cut every layer.

Identity
Who is asking.
Identity propagates from agent to recipe to registry to source. RBAC is per recipe and per artifact, not per platform.
Observability
What was used.
Every retrieval emits an OTel span: agent, recipe, artifact version, classification, latency, tokens.
Security
What is allowed.
Classification labels travel with the artifact. Recipes that read regulated data require explicit policy approval.
Lifecycle
When it expires.
Manifest versioning, content hashes, refresh policies, deprecation aliases. Stale context is the silent failure mode.
Architecture · Reference topology

A topology that survives audit.

Per-repository recipe authoring, central registry for distribution, MCP gateway for runtime delivery, with identity and audit threaded through every hop.

Code intelligence in CI Recipes in repo Registry as a service MCP gateway runtime OTel + audit log SPIFFE identity per agent
Part III
III

Code intelligence layer.

The compiler-grade foundation everything else depends on.

Code intelligence · Why it matters

Approximate context produces approximate code.

Without compiler-grade
Hallucinated symbols, wrong types, broken refactors.
The agent invents a method that looks plausible but does not exist. Cross-module changes miss callers. Generic instantiations fail at build.
With compiler-grade
Resolved symbols, typed signatures, complete call graphs.
The agent knows which calls cross a module boundary, which generics are bound, which configuration keys are read at runtime, and where each definition lives.
Code intelligence · Required capabilities

Seven capabilities define the layer.

01
Symbol resolution
Each reference points to its unique definition across files and modules.
02
Type resolution
Generics, inferred types, and overloads resolved with full fidelity.
03
Inheritance graph
Classes, interfaces, traits, and their implementers across the workspace.
04
Call graphs
Static and virtual calls, intra- and inter-module, with cardinality.
05
Dependency resolution
Direct, transitive, and provenance for every external package.
06
Configuration mapping
Which keys are read where, with defaults and validation rules.
07
Source ranges
Every fact carries file plus line plus column for round-trip evidence.
All seven
No partial credit.
Missing one capability collapses recipe quality. Plan for all seven from day one.
Code intelligence · Pipeline

From source to a graph an agent can query.

STAGE 01 Source Repos under build. Multi-language code,build files, manifests,infra config. Trigger: every commit. STAGE 02 Compiler / AST Parse and resolve. Language-native orunified analysisplatform. Output: typed AST. STAGE 03 Graphs Symbols, types, calls. Inheritance, deps,configuration map,source ranges. Snapshot per commit. STAGE 04 Recipe-ready Queryable artifacts. Indexed graph andstructured artifactsfor recipe authors. Consumed by Layer 02. Pay the compiler cost in CI — once per commit — not per agent task.
Code intelligence · Per-language

Different languages, same contract.

JVM · .NET
Native compilers + LSP.
Use javac, kotlinc, Roslyn through LSP servers. Mature symbol and type resolution out of the box.
TypeScript · Python
Compiler API + type stubs.
tsc compiler API for TS, Pyright or Pyre for Python. Tree-sitter for fast lexical, then layered type analysis.
Go · Rust
Toolchain-native indexers.
gopls and rust-analyzer expose call graphs and type info via LSP. Both feed the same recipe contract.
Mainframe
COBOL, PL/I.
Specialized parsers (Cobol Programming Tooling, OpenLegacy) plus copybook and JCL resolution.
Polyglot
Cross-language refs.
REST schemas, OpenAPI, gRPC IDL, Avro — resolve calls that cross language boundaries.
Rule
One contract, many engines.
Layer 02 should not know which compiler produced the graph. Hide language-specific tooling behind the recipe API.
Part IV
IV

Context recipes.

Composable, intent-shaped units of context that turn graphs into agent-ready artifacts.

Recipes · Definition

A recipe is a contract between intent and context.

Inputs
Source plus graphs.
A recipe consumes Layer 01 artifacts (symbol graph, type info, call graph, dependency tree, configuration map) and project-local conventions.
Outputs
A targeted, versioned artifact.
Markdown, JSON, or structured graph snippet sized for the agent task. Manifest, implementation, and tests, like any code module.

A recipe answers one question well. Six recipes compose. Sixty recipes describe a platform.

Recipes · Categories

Six categories cover most enterprise tasks.

CATEGORY 01 Structural Inventory Modules, packages, classes,public API surface, ownership. "What is in this repo?" CATEGORY 02 Dependency Intelligence Direct, transitive, provenance,vulnerabilities, license posture. "What does it depend on?" CATEGORY 03 Service Topology Endpoints, queues, datastores,and the calls that connect them. "How does it talk to others?" CATEGORY 04 Convention Extraction Logging, error handling, naming,layering rules, observed in code. "What patterns does it follow?" CATEGORY 05 Test Intent Mapping Tests grouped by intent and thecode paths each one exercises. "What does it actually verify?" CATEGORY 06 Configuration Surface Keys read at runtime, defaults,validation, environment binding. "What can change at deploy?"
Recipes · Anatomy

Manifest, implementation, tests, docs.

Manifest
recipe.yaml
Identity, version, inputs, outputs, classification, refresh policy. The contract layer reads.
Implementation
Pure function over graphs.
Code that turns Layer 01 facts into a targeted artifact. Reproducible, deterministic, free of side effects.
Tests
Golden fixtures.
Snapshot tests over a fixed graph. CI fails if a recipe changes its output without an explicit version bump.
Docs
Intent + sample output.
One paragraph of intent, one example output. Recipe consumers should never have to read the implementation.
Recipes · Authoring

Five rules for recipe authors.

01One question per recipe. If the title needs an "and", split it into two recipes.
02Token budget per output. Declare it in the manifest. Fail the build when exceeded.
03Stable shape. Output schema is part of the contract; breaking changes require a major version.
04No secret leaks. Classification labels propagate from inputs to outputs. Recipes cannot widen scope.
05Provenance always. Every fact in the output cites its source range from Layer 01.
Part V
V

Registry and distribution.

Where recipes live, how they version, how they reach the agent at runtime.

Registry · Responsibilities

A registry is a package manager for context.

Storage
Co-located, central, federated.
Same repository, central object store, or per-domain federation. Pick one and document the trade-offs.
Discovery
By repo, capability, content.
Stable URIs and content addressing. Aliases for "latest stable" track moving versions safely.
Refresh
Commit, schedule, event.
Three triggers cover most needs. Staleness policy declares when a stale artifact must be refused.
Registry · Distribution flow

From a commit to an agent in three hops.

HOP 01 Author + Build Recipe runs in CI. Commit triggers Layer 01refresh, recipe execution,test snapshot, sign andtag artifact. Where: developer repo + CI. HOP 02 Registry Store + index + alias. Content-addressed storage,stable URIs, version aliases,classification labels,retention policy. Where: registry as a service. HOP 03 Gateway MCP or static fetch. Resolves identity, appliesRBAC, fetches artifact, emitsaudit span, returns contextto the agent. Where: agent-side runtime. CONSUMER Agent Receives context. Targeted, signed,classified context.Within token budget. Acts on the task. Identity and audit thread through every hop. Stale or unauthorized artifacts are refused at the gateway.
Registry · Versioning + refresh

Content addressing keeps history honest.

Versioning
Hash + manifest + alias.
Each artifact is addressed by its content hash. Manifest carries semantic version. Aliases like "stable" or "preview" track moving heads without breaking pinned consumers.
Refresh
Commit-driven, scheduled, event-driven.
Most recipes refresh on commit. Some run nightly (e.g., dependency advisories). Some are event-driven (new endpoint published, schema changed). Staleness policy decides when stale is unacceptable.
Part VI
VI

Agent integration patterns.

Static, MCP, custom configuration, hybrid — pick the right contract for the agent.

Integration · Patterns

Three patterns, one stack.

PATTERN 01 Static File Injection Pre-rendered context, in repo. AGENTS.md, .cursor/rules,.copilot-instructions.md, etc.Recipes generate the file atCI; agent reads on every task. BEST FOR Stable conventions, low churn. No infra to deploy. Simplest start. Rebuild on commit. PATTERN 02 MCP Server On-demand context, via tools. Recipes exposed as MCP toolcalls. Agent fetches only whatit needs, when it needs it.Identity and audit per call. BEST FOR Large repos, dynamic queries. Token budget under control. Most powerful. Requires gateway. PATTERN 03 Hybrid Distribution Static base + MCP for specifics. Stable conventions injectedstatically; deep queries servedvia MCP. Best of both, withcareful contract design. BEST FOR Mature platforms. Mixed agent surfaces. Recommended at scale.
Integration · Per-agent reference

Where context lands in each agent.

GitHub Copilot
.github/copilot-instructions.md
Plus repository custom instructions. Static injection is the primary surface; MCP is emerging.
Cursor / Windsurf
.cursor/rules · .windsurfrules
File-based rules with scope. Both editors support MCP servers for richer queries.
Claude Code
CLAUDE.md + skills + MCP
Layered model: static base, on-demand skills, MCP tools. Hybrid distribution maps cleanly.
Custom agents
SDK + recipe API.
Internal agents call recipe APIs directly. Same contract, no parsing of static files required.
Part VII
VII

Governance and compliance.

Same controls as the source code. No exceptions for "AI context."

Governance · Policy flow

Policy enforcement on every retrieval.

REQUEST Agent asks Identity, recipe URI,task context, targetrepository. Span starts. CHECK 01 Identity + RBAC Agent identity matchesa role allowed to readthis recipe? Reject if not. CHECK 02 Classification Artifact label fits theagent runtime trustboundary? Block on mismatch. CHECK 03 Freshness Artifact within therecipe's stalenesspolicy window? Refresh or fail. RESULT Serve Audit spanclosed. Token-budget OK. Three checks, every retrieval. Audit span captures decision and reason regardless of outcome.
Governance · Roles + policies

Five roles. Six policy domains.

Roles
Platform owner, recipe steward, repo owner, security reviewer, auditor.
Each role has explicit responsibilities and a named owner. The auditor is independent of platform and repository teams.
Policy domains
Scope, classification, access, refresh, retention, integration.
Each domain has a written policy, a control mapped to it, and an audit query that proves enforcement.
Governance · Audit + controls

Four control families. One audit log.

Identity + access
Who can do what.
Per-recipe RBAC, identity propagation, scoped tokens. SPIFFE for inter-service identity where required.
Integrity
Proof of provenance.
Signed artifacts, content hashes, build attestation. Tampering detected at retrieval time.
Lifecycle
Birth to deprecation.
Versioning, refresh, deprecation, deletion. No orphan artifacts; every URI resolves or returns a tombstone.
Observability
Evidence on demand.
OTel spans, audit log, classification labels, and policy decisions queryable by auditor without engineering help.
Part VIII
VIII

Adoption roadmap and metrics.

Five phases. Measurable exit criteria. The metrics that prove the layer is paying off.

Adoption · Roadmap

Five phases over twelve months.

MONTH 0 M 1-2 M 3-5 M 6-9 M 10-12+ PHASE 00 Discovery Inventory agents,map repos, baselinetoken spend. Exit: baseline doc. PHASE 01 Pilot One repo, threerecipes, one agent.Static injection. Exit: token cut 30%. PHASE 02 Expansion Five repos, registrydeployed, MCP fordeep queries. Exit: governance live. PHASE 03 Platform Self-service for newrepos. Hybrid is thedefault pattern. Exit: SLA met. PHASE 04 Optimization Continuous tuning.Recipes deprecate.Metrics drive ROI. Exit: never — ongoing.
Adoption · Success metrics

Six metrics. Measured every release.

Token spend
Tokens per task.
Median tokens consumed per agent task. Target: 30-60% reduction vs baseline within two phases.
Hallucination
Hallucination rate.
Frequency of references to non-existent symbols. Target: trending to zero with compiler-grade context.
Convention
Convention adherence.
Generated code that matches repo conventions on the first pass. Target: above 80%.
Time to value
Time to first useful suggestion.
Seconds from task start to a suggestion the developer accepts. Target: under 8 seconds.
Satisfaction
Developer satisfaction.
Quarterly NPS or equivalent. Should track upward as recipes mature.
Throughput
PR throughput.
PRs merged per developer per week, controlled for repo. Lagging signal but the one that pays the bill.
Part IX
IX

Build, buy, or hybrid.

Three paths to a Semantic Context Layer — and how to choose.

Build vs Buy · Three paths

Same architecture. Three implementation choices.

Path A · Build
GitHub + Microsoft stack.
Build on Roslyn, LSP, GitHub Actions, Azure object storage, and an MCP gateway you operate. Highest control, highest commitment.
Path B · Buy
Commercial platform.
Adopt a vendor that ships compiler-grade context as a product (e.g., Moderne). Fastest time to value; vendor lock-in trade-off.
Path C · Hybrid
Build the contract, buy the engine.
Own recipes, registry, and gateway; rent code intelligence from a vendor. Decouples the durable contract from the engine.
Build vs Buy · Decision matrix

Where each path wins.

CONTROLHigh CONTROLLow TIME TO VALUE · SLOW TIME TO VALUE · FAST QUADRANT · BUILD Path A · Build on the stack Maximum control over recipes, registry, gateway.Slowest path; highest in-house expertise required. Wins: regulated industries, deep customization, mainframe footprints. QUADRANT · HYBRID Path C · Hybrid Own the durable contract; rent the heavy engine.Best of both for most enterprises today. Wins: portfolios mixing greenfield and legacy. QUADRANT · AVOID Slow + low control Custom build with no real ownership of the contract.All the cost of build with none of the strategic value. Avoid: unfocused PoCs, departmental scripts that never harden. QUADRANT · BUY Path B · Buy Fastest path. Vendor owns the engine and the upgrades.Less control over recipes and lock-in to a single vendor. Wins: aggressive timelines, large legacy modernization at scale.
Closing thought
paulasilva

Context is the platform. Build it like one.

Building the future of software development with AI and Agentic DevOps.

Paula Silva | Software Global Black Belt
linkedin.com/in/paulanunes
Agentic DevOps Hub↗
PDF
ENESPT