Semantic Context Layer for Agentic DevOpsCamada de Contexto Semântico para DevOps AgênticoCapa de Contexto Semántico para DevOps Agéntico
A reference architecture for engineering compiler-grade, reusable semantic context that grounds AI coding agents in enterprise reality — turning agentic coding from a demo into a platform.Uma arquitetura de referência para engenharia de contexto semântico com qualidade de compilador, reutilizável e auditável, que fundamenta agentes de codificação com IA na realidade corporativa.Una arquitectura de referencia para construir contexto semántico de calidad de compilador, reutilizable y auditable, que ancla a los agentes de codificación con IA en la realidad empresarial.
The context problem in enterprise agentic coding
A single agent task on a real enterprise monorepo can read millions of tokens to answer one question. That is not a theoretical edge case — it is the default behavior when there is no semantic layer between the agent and the source code. Compared to compiler-grade context, naive retrieval costs 10× more per task while producing worse results.
Three approaches dominate today’s stack, and all three fall short in predictable ways. Raw retrieval — embedding search over source files — has no awareness of symbol resolution, type information, or call graphs. The agent retrieves text that looks related, not code that is structurally related. Hand-curated prompts (wikis, AGENTS.md, README files pasted into context) go stale within weeks and have no tie to the build; there is no way to verify that conventions described in the prompt still match what the compiler enforces. Whole-repo dumps saturate the context window with boilerplate, collapsing the signal-to-noise ratio 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.
Semantic context is what the compiler knows, made available to agents. The difference between lexical context (tokens, files, lines — what grep returns) and semantic context (symbols, types, calls, configs — what the build resolves) is the difference between an agent that guesses and an agent that reasons. SCL-AD makes the second column queryable, versioned, and policy-bound — without making every agent a compiler.
The architecture rests on four pillars: Precompute (build symbol, type, and dependency graphs once, refresh on commit — pay the compiler cost in CI, not per task); Target (deliver only the slice the task needs — a recipe per intent, not a dump per repo); Execute (surface context through stable contracts: static files, MCP tools, or hybrid); and Coordinate (govern lifecycle, identity, classification, and audit across recipes, registries, and agents).
Architecture: four layers and their contracts
The Semantic Context Layer is a four-layer stack in which each layer exposes a stable contract to the layer above. Agents see only the top layer.
Layer 01 — Code Intelligence is the compiler-grade foundation: symbol graphs, type graphs, and call graphs. Everything above depends on this layer being correct and current.
Layer 02 — Context Recipes are composable, intent-shaped units of context. Each recipe consumes Layer 01 artifacts and produces a targeted, versioned artifact sized for a specific agent task. A recipe is a contract between intent and context.
Layer 03 — Context Registry handles storage, discovery, versioning, and refresh. It functions as a package manager for context: stable URIs, content addressing, and aliases for moving versions.
Layer 04 — Agent Integration is how agents actually receive context — through static files injected into the repository, MCP server tool calls, or custom agent configurations.
Three components cut across every layer: the Context Store (persistent, content-addressed storage with stable URIs and content hashes, supporting co-located, central, or federated topologies); Retrieval (discovery by repository, capability, or content, with immutable artifacts and “latest stable” aliases); and Governance (identity propagation, classification labels, RBAC, audit trail — recipes are signed and versioned like any code artifact).
Four cross-cutting concerns thread through the entire stack: Identity (RBAC per recipe and per artifact, not per platform); Observability (every retrieval emits an OpenTelemetry span capturing agent, recipe, artifact version, classification, latency, and tokens); Security (classification labels travel with the artifact; recipes reading regulated data require explicit policy approval); and Lifecycle (manifest versioning, content hashes, refresh policies, deprecation aliases — stale context is the silent failure mode).
Code intelligence: the compiler-grade foundation
Approximate context produces approximate code. Without compiler-grade grounding, agents hallucinate symbols that look plausible but do not exist, miss callers in cross-module refactors, and fail generic instantiations at build time. With it, 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.
Seven capabilities define a complete code intelligence layer — no partial credit:
- Symbol resolution — each reference points to its unique definition across files and modules
- Type resolution — generics, inferred types, and overloads resolved with full fidelity
- Inheritance graph — classes, interfaces, traits, and their implementers across the workspace
- Call graphs — static and virtual calls, intra- and inter-module, with cardinality
- Dependency resolution — direct, transitive, and provenance for every external package
- Configuration mapping — which keys are read where, with defaults and validation rules
- Source ranges — every fact carries file, line, and column for round-trip evidence
Missing any one of these seven capabilities collapses recipe quality downstream. The pipeline flows from source (every commit triggers a run) through compiler or AST parsing (producing a typed AST) to graph extraction (symbols, types, calls, inheritance, deps, configuration map, source ranges) to recipe-ready queryable artifacts consumed by Layer 02. The key principle: pay the compiler cost in CI — once per commit — not per agent task.
Language coverage follows established toolchains: JVM and .NET use native compilers via LSP; TypeScript uses the compiler API, Python uses Pyright or Pyre; Go and Rust use gopls and rust-analyzer; mainframe workloads (COBOL, PL/I) use specialized parsers with copybook and JCL resolution; polyglot service boundaries are resolved via REST schemas, OpenAPI, gRPC IDL, and Avro. The rule is one contract, many engines — Layer 02 should not know which compiler produced the graph.
Context recipes: composable units of intent
A recipe answers one question well. Six recipes compose into a useful agent. Sixty recipes describe a platform.
Six categories cover the majority of enterprise tasks:
| Category | Question answered |
|---|---|
| Structural Inventory | ”What is in this repo?” — modules, packages, classes, public API surface, ownership |
| Dependency Intelligence | ”What does it depend on?” — direct, transitive, provenance, vulnerabilities, license posture |
| Service Topology | ”How does it talk to others?” — endpoints, queues, datastores, and the calls connecting them |
| Convention Extraction | ”What patterns does it follow?” — logging, error handling, naming, layering rules, observed in code |
| Test Intent Mapping | ”What does it actually verify?” — tests grouped by intent and the code paths each one exercises |
| Configuration Surface | ”What can change at deploy?” — keys read at runtime, defaults, validation, environment binding |
Each recipe has four components: a manifest (recipe.yaml) declaring identity, version, inputs, outputs, classification, and refresh policy; an implementation (a pure function over graphs — reproducible, deterministic, free of side effects); tests (snapshot tests over a fixed graph — CI fails if output changes without an explicit version bump); and docs (one paragraph of intent, one example output — recipe consumers should never have to read the implementation).
Five authoring rules keep recipes trustworthy: one question per recipe (if the title needs an “and”, split it); a declared token budget per output enforced at build time; a stable output schema with major versions for breaking changes; no secret leaks (classification labels propagate from inputs to outputs — recipes cannot widen scope); and provenance always (every fact in the output cites its source range from Layer 01).
Registry and distribution
The registry is a package manager for context. It covers three responsibilities: storage (co-located, central, or federated — pick one and document the trade-offs); discovery (stable URIs, content addressing, aliases for “latest stable” that track moving versions safely); and refresh (commit-driven, scheduled, or event-driven — staleness policy declares when a stale artifact must be refused).
Distribution flows from a commit to an agent in three hops. Hop 01 is the developer repo and CI: the commit triggers Layer 01 refresh, recipe execution, test snapshot, then sign-and-tag. Hop 02 is the registry: content-addressed storage, stable URIs, version aliases, classification labels, retention policy. Hop 03 is the MCP gateway or static fetch: identity is resolved, RBAC applied, artifact fetched, audit span emitted, and context returned to the agent within budget. Identity and audit thread through every hop. Stale or unauthorized artifacts are refused at the gateway.
Agent integration patterns
Three patterns cover the integration surface. Static File Injection pre-renders context into repository files (AGENTS.md, .cursor/rules, .github/copilot-instructions.md, etc.) generated by recipes at CI time. Best for stable conventions with low churn; no infrastructure to deploy; simplest starting point. MCP Server exposes recipes as on-demand MCP tool calls — the agent fetches only what it needs, when it needs it, with identity and audit per call. Best for large repos, dynamic queries, and tight token budgets; requires a gateway. Hybrid Distribution combines a static base for conventions with MCP for deep queries — the recommended pattern at scale.
Per-agent mapping: GitHub Copilot uses .github/copilot-instructions.md plus repository custom instructions (MCP is emerging); Cursor and Windsurf use file-based rules with scope, both supporting MCP servers; Claude Code uses a layered model of static base, on-demand skills, and MCP tools — hybrid distribution maps cleanly; custom internal agents call recipe APIs directly via SDK.
Governance and compliance
Governance enforces the same controls as source code — no exceptions for “AI context.” Every retrieval runs three checks: identity and RBAC (does this agent’s identity match a role allowed to read this recipe — reject if not); classification (does the artifact’s label fit the agent runtime’s trust boundary — block on mismatch); freshness (is the artifact within the recipe’s staleness policy window — refresh or fail). The audit span captures the decision and reason regardless of outcome.
Five roles have explicit responsibilities: platform owner, recipe steward, repository owner, security reviewer, and auditor — with the auditor independent of platform and repository teams. Six policy domains each have a written policy, a mapped control, and an audit query that proves enforcement: scope, classification, access, refresh, retention, and integration.
Four control families complete the governance picture: identity and access (per-recipe RBAC, identity propagation, scoped tokens, SPIFFE for inter-service identity); integrity (signed artifacts, content hashes, build attestation — tampering detected at retrieval time); lifecycle (versioning, refresh, deprecation, deletion — no orphan artifacts, every URI resolves or returns a tombstone); and observability (OTel spans, audit log, classification labels, and policy decisions queryable by the auditor without engineering help).
Adoption roadmap and success metrics
The reference roadmap spans five phases over twelve months. Phase 0 (Month 0) — Discovery: inventory agents, map repos, baseline token spend; exit with a baseline document. Phase 1 (Months 1–2) — Pilot: one repo, three recipes, one agent, static injection; exit when token spend drops 30%. Phase 2 (Months 3–5) — Expansion: five repos, registry deployed, MCP live for deep queries; exit when governance is running. Phase 3 (Months 6–9) — Platform: self-service for new repos, hybrid as the default pattern; exit when SLA is met. Phase 4 (Months 10–12+) — Optimization: continuous tuning, recipes deprecate, metrics drive ROI; no exit — ongoing.
Six metrics, measured every release: token spend (median tokens per agent task — target 30–60% reduction vs baseline within two phases); hallucination rate (references to non-existent symbols — target trending to zero with compiler-grade context); convention adherence (generated code matching repo conventions on first pass — target above 80%); time to first useful suggestion (seconds from task start to an accepted suggestion — target under 8 seconds); developer satisfaction (quarterly NPS — should track upward as recipes mature); and PR throughput (PRs merged per developer per week, controlled for repo — the lagging signal that pays the bill).
Build, buy, or hybrid
Three paths implement the same architecture. Path A — Build: assemble on Roslyn, LSP, GitHub Actions, Azure object storage, and an MCP gateway you operate. Maximum control over recipes, registry, and gateway; slowest path; highest in-house expertise required. Wins in regulated industries, deep customization needs, and mainframe footprints. Path B — Buy: adopt a commercial platform that ships compiler-grade context as a product (e.g., Moderne). Fastest time to value; vendor lock-in is the trade-off. Wins on aggressive timelines and large-scale legacy modernization. Path C — Hybrid: own recipes, registry, and gateway; rent code intelligence from a vendor. Decouples the durable contract from the engine. Best of both for most enterprises today — wins for portfolios mixing greenfield and legacy.
The quadrant to avoid is slow delivery with low control: custom build with no real ownership of the contract delivers all the cost of build with none of the strategic value. Unfocused proofs-of-concept and departmental scripts that never harden fall here.
Context is the platform. Build it like one.
O problema de contexto na codificação agêntica corporativa
Uma única tarefa de agente em um monorepo corporativo real pode ler milhões de tokens para responder uma única pergunta. Esse não é um caso extremo teórico — é o comportamento padrão quando não existe uma camada semântica entre o agente e o código-fonte. Comparado ao contexto com qualidade de compilador, a recuperação ingênua custa 10× mais por tarefa e produz resultados piores.
Três abordagens dominam o stack atual, e todas as três falham de maneiras previsíveis. A recuperação bruta — busca por embeddings sobre arquivos-fonte — não tem consciência de resolução de símbolos, informações de tipos ou grafos de chamadas. O agente recupera texto que parece relacionado, não código que é estruturalmente relacionado. Prompts curados manualmente (wikis, AGENTS.md, arquivos README colados no contexto) ficam desatualizados em semanas e não têm vínculo com o build; não há como verificar se as convenções descritas no prompt ainda coincidem com o que o compilador impõe. Dumps do repositório inteiro saturam a janela de contexto com código boilerplate, reduzindo a relação sinal-ruído abaixo do limiar em que o agente pode agir com segurança.
As três abordagens compartilham uma causa raiz: não existe uma camada semântica entre os agentes e o código em que operam.
Contexto semântico é o que o compilador sabe, disponibilizado para os agentes. A diferença entre contexto lexical (tokens, arquivos, linhas — o que o grep retorna) e contexto semântico (símbolos, tipos, chamadas, configurações — o que o build resolve) é a diferença entre um agente que adivinha e um que raciocina. O SCL-AD torna a segunda coluna consultável, versionada e vinculada a políticas — sem transformar cada agente em um compilador.
A arquitetura se apoia em quatro pilares: Pré-computar (construir grafos de símbolos, tipos e dependências uma vez, atualizar a cada commit — pagar o custo do compilador no CI, não por tarefa); Direcionar (entregar apenas o recorte que a tarefa precisa — uma recipe por intenção, não um dump por repositório); Executar (expor contexto por contratos estáveis: arquivos estáticos, ferramentas MCP ou híbrido); e Coordenar (governar ciclo de vida, identidade, classificação e auditoria em recipes, registries e agentes).
Arquitetura: quatro camadas e seus contratos
O Semantic Context Layer é um stack de quatro camadas em que cada camada expõe um contrato estável para a camada acima. Os agentes enxergam apenas a camada superior.
Camada 01 — Code Intelligence é a fundação com qualidade de compilador: grafos de símbolos, tipos e chamadas. Tudo acima depende desta camada ser correta e atual.
Camada 02 — Context Recipes são unidades composáveis de contexto moldadas pela intenção. Cada recipe consome artefatos da Camada 01 e produz um artefato direcionado e versionado, dimensionado para uma tarefa específica do agente. Uma recipe é um contrato entre intenção e contexto.
Camada 03 — Context Registry gerencia armazenamento, descoberta, versionamento e atualização. Funciona como um gerenciador de pacotes para contexto: URIs estáveis, endereçamento por conteúdo e aliases para versões em movimento.
Camada 04 — Agent Integration define como os agentes recebem o contexto — por meio de arquivos estáticos injetados no repositório, chamadas de ferramentas via servidor MCP ou configurações personalizadas de agente.
Três componentes permeiam todas as camadas: o Context Store (armazenamento persistente e endereçado por conteúdo com URIs estáveis e hashes de conteúdo, suportando topologias colocalizadas, centrais ou federadas); Recuperação (descoberta por repositório, capacidade ou conteúdo, com artefatos imutáveis e aliases para “latest stable”); e Governança (propagação de identidade, rótulos de classificação, RBAC, trilha de auditoria — recipes são assinadas e versionadas como qualquer artefato de código).
Quatro preocupações transversais percorrem todo o stack: Identidade (RBAC por recipe e por artefato, não por plataforma); Observabilidade (cada recuperação emite um span OpenTelemetry capturando agente, recipe, versão do artefato, classificação, latência e tokens); Segurança (rótulos de classificação viajam com o artefato; recipes que leem dados regulamentados exigem aprovação explícita de política); e Ciclo de vida (versionamento de manifesto, hashes de conteúdo, políticas de atualização, aliases de depreciação — contexto desatualizado é o modo de falha silencioso).
Code intelligence: a fundação com qualidade de compilador
Contexto aproximado produz código aproximado. Sem fundamentação com qualidade de compilador, agentes alucinam símbolos que parecem plausíveis mas não existem, perdem callers em refatorações entre módulos e falham em instanciações genéricas no build. Com ela, o agente sabe quais chamadas cruzam fronteiras de módulo, quais genéricos estão vinculados, quais chaves de configuração são lidas em tempo de execução e onde cada definição está localizada.
Sete capacidades definem uma camada de code intelligence completa — sem crédito parcial:
- Resolução de símbolos — cada referência aponta para sua definição única em arquivos e módulos
- Resolução de tipos — genéricos, tipos inferidos e sobrecargas resolvidos com fidelidade total
- Grafo de herança — classes, interfaces, traits e seus implementadores em todo o workspace
- Grafos de chamadas — chamadas estáticas e virtuais, intra e intermodulares, com cardinalidade
- Resolução de dependências — diretas, transitivas e proveniência de cada pacote externo
- Mapeamento de configuração — quais chaves são lidas onde, com padrões e regras de validação
- Intervalos de fonte — cada fato carrega arquivo, linha e coluna para evidência de ida e volta
A ausência de qualquer uma dessas sete capacidades degrada a qualidade das recipes a jusante. O pipeline flui da fonte (cada commit dispara uma execução) por compilação ou análise de AST (produzindo um AST tipado), extração de grafos (símbolos, tipos, chamadas, herança, deps, mapa de configuração, intervalos de fonte), até artefatos consultáveis consumidos pela Camada 02. O princípio central: pagar o custo do compilador no CI — uma vez por commit — não por tarefa do agente.
A cobertura por linguagem segue toolchains estabelecidas: JVM e .NET usam compiladores nativos via LSP; TypeScript usa a API do compilador, Python usa Pyright ou Pyre; Go e Rust usam gopls e rust-analyzer; workloads mainframe (COBOL, PL/I) usam parsers especializados com resolução de copybook e JCL; fronteiras de serviços polyglot são resolvidas via REST schemas, OpenAPI, gRPC IDL e Avro. A regra é um contrato, vários engines — a Camada 02 não deve saber qual compilador produziu o grafo.
Context recipes: unidades composáveis de intenção
Uma recipe responde bem a uma pergunta. Seis recipes se compõem em um agente útil. Sessenta recipes descrevem uma plataforma.
Seis categorias cobrem a maioria das tarefas corporativas:
| Categoria | Pergunta respondida |
|---|---|
| Structural Inventory | ”O que há neste repositório?” — módulos, pacotes, classes, superfície de API pública, ownership |
| Dependency Intelligence | ”Do que ele depende?” — diretas, transitivas, proveniência, vulnerabilidades, postura de licença |
| Service Topology | ”Como ele se comunica com outros?” — endpoints, filas, datastores e as chamadas que os conectam |
| Convention Extraction | ”Que padrões ele segue?” — logging, tratamento de erros, nomenclatura, regras de camadas, observados no código |
| Test Intent Mapping | ”O que ele realmente verifica?” — testes agrupados por intenção e os caminhos de código que cada um exercita |
| Configuration Surface | ”O que pode mudar no deploy?” — chaves lidas em tempo de execução, padrões, validação, vinculação de ambiente |
Cada recipe tem quatro componentes: um manifesto (recipe.yaml) declarando identidade, versão, inputs, outputs, classificação e política de atualização; uma implementação (função pura sobre grafos — reproduzível, determinística, sem efeitos colaterais); testes (snapshot tests sobre um grafo fixo — o CI falha se o output mudar sem um bump explícito de versão); e docs (um parágrafo de intenção, um exemplo de output — consumidores da recipe nunca devem precisar ler a implementação).
Cinco regras de autoria mantêm as recipes confiáveis: uma pergunta por recipe (se o título precisa de “e”, divida em duas); um token budget declarado por output aplicado no build; um schema de output estável com versões maiores para mudanças que quebram compatibilidade; sem vazamento de segredos (rótulos de classificação propagam dos inputs para os outputs — recipes não podem ampliar o escopo); e proveniência sempre (cada fato no output cita seu intervalo de fonte da Camada 01).
Registry e distribuição
O registry é um gerenciador de pacotes para contexto. Ele cobre três responsabilidades: armazenamento (colocalizado, central ou federado — escolha um e documente os trade-offs); descoberta (URIs estáveis, endereçamento por conteúdo, aliases para “latest stable” que rastreiam versões em movimento com segurança); e atualização (disparada por commit, agendada ou orientada a eventos — a política de staleness declara quando um artefato desatualizado deve ser recusado).
A distribuição flui de um commit para um agente em três saltos. Salto 01 é o repositório do desenvolvedor e o CI: o commit dispara a atualização da Camada 01, execução da recipe, snapshot de teste, depois assinar e marcar. Salto 02 é o registry: armazenamento endereçado por conteúdo, URIs estáveis, aliases de versão, rótulos de classificação, política de retenção. Salto 03 é o MCP gateway ou fetch estático: a identidade é resolvida, o RBAC aplicado, o artefato buscado, o span de auditoria emitido e o contexto retornado ao agente dentro do budget. Identidade e auditoria permeiam cada salto. Artefatos desatualizados ou não autorizados são recusados no gateway.
Padrões de integração com agentes
Três padrões cobrem a superfície de integração. Injeção de Arquivo Estático pré-renderiza o contexto em arquivos do repositório (AGENTS.md, .cursor/rules, .github/copilot-instructions.md, etc.) gerados por recipes no CI. Ideal para convenções estáveis com baixa rotatividade; sem infraestrutura para implantar; ponto de partida mais simples. MCP Server expõe recipes como chamadas de ferramentas MCP sob demanda — o agente busca apenas o que precisa, quando precisa, com identidade e auditoria por chamada. Ideal para repositórios grandes, consultas dinâmicas e orçamentos apertados de tokens; requer um gateway. Distribuição Híbrida combina uma base estática para convenções com MCP para consultas profundas — o padrão recomendado em escala.
Mapeamento por agente: GitHub Copilot usa .github/copilot-instructions.md mais instruções personalizadas de repositório (MCP está emergindo); Cursor e Windsurf usam regras baseadas em arquivo com escopo, ambos suportando servidores MCP; Claude Code usa um modelo em camadas de base estática, skills sob demanda e ferramentas MCP — a distribuição híbrida mapeia de forma limpa; agentes internos personalizados chamam APIs de recipe diretamente via SDK.
Governança e conformidade
A governança aplica os mesmos controles que o código-fonte — sem exceções para “contexto de IA.” Cada recuperação passa por três verificações: identidade e RBAC (a identidade deste agente corresponde a uma função autorizada a ler esta recipe — rejeitar se não corresponder); classificação (o rótulo do artefato se encaixa no limite de confiança do runtime do agente — bloquear em caso de incompatibilidade); atualidade (o artefato está dentro da janela de política de staleness da recipe — atualizar ou falhar). O span de auditoria captura a decisão e o motivo independentemente do resultado.
Cinco papéis têm responsabilidades explícitas: platform owner, recipe steward, repository owner, security reviewer e auditor — com o auditor independente das equipes de plataforma e repositório. Seis domínios de política têm cada um uma política escrita, um controle mapeado e uma consulta de auditoria que prova a aplicação: escopo, classificação, acesso, atualização, retenção e integração.
Quatro famílias de controle completam o quadro de governança: identidade e acesso (RBAC por recipe, propagação de identidade, tokens com escopo, SPIFFE para identidade entre serviços); integridade (artefatos assinados, hashes de conteúdo, atestação de build — adulteração detectada no momento da recuperação); ciclo de vida (versionamento, atualização, depreciação, exclusão — sem artefatos órfãos, cada URI resolve ou retorna uma lápide); e observabilidade (spans OTel, log de auditoria, rótulos de classificação e decisões de política consultáveis pelo auditor sem ajuda de engenharia).
Roadmap de adoção e métricas de sucesso
O roadmap de referência abrange cinco fases em doze meses. Fase 0 (Mês 0) — Discovery: inventariar agentes, mapear repositórios, estabelecer baseline de gasto de tokens; sair com um documento de baseline. Fase 1 (Meses 1–2) — Pilot: um repositório, três recipes, um agente, injeção estática; sair quando o gasto de tokens cair 30%. Fase 2 (Meses 3–5) — Expansion: cinco repositórios, registry implantado, MCP ativo para consultas profundas; sair com a governança funcionando. Fase 3 (Meses 6–9) — Platform: self-service para novos repositórios, híbrido como padrão; sair quando o SLA for cumprido. Fase 4 (Meses 10–12+) — Optimization: ajuste contínuo, recipes deprecadas, métricas direcionam ROI; sem saída — contínuo.
Seis métricas, medidas a cada release: gasto de tokens (mediana de tokens por tarefa — meta de redução de 30–60% vs baseline em duas fases); taxa de alucinação (referências a símbolos inexistentes — meta tendendo a zero com contexto de qualidade de compilador); aderência a convenções (código gerado correspondendo às convenções do repositório na primeira passagem — meta acima de 80%); tempo para primeira sugestão útil (segundos do início da tarefa até uma sugestão aceita — meta abaixo de 8 segundos); satisfação do desenvolvedor (NPS trimestral — deve crescer conforme as recipes amadurecem); e throughput de PRs (PRs mesclados por desenvolvedor por semana, controlado por repositório — o sinal atrasado que justifica o investimento).
Build, buy ou híbrido
Três caminhos implementam a mesma arquitetura. Caminho A — Build: montar em Roslyn, LSP, GitHub Actions, armazenamento de objetos Azure e um MCP gateway que você opera. Máximo controle sobre recipes, registry e gateway; caminho mais lento; maior necessidade de expertise interna. Vence em indústrias regulamentadas, necessidades de customização profunda e footprints mainframe. Caminho B — Buy: adotar uma plataforma comercial que entrega contexto de qualidade de compilador como produto (ex: Moderne). Tempo para valor mais rápido; lock-in de fornecedor é o trade-off. Vence em cronogramas agressivos e modernização de legado em grande escala. Caminho C — Híbrido: possuir recipes, registry e gateway; alugar code intelligence de um fornecedor. Desacopla o contrato duradouro do engine. O melhor dos dois para a maioria das empresas hoje — vence em portfólios misturando greenfield e legado.
O quadrante a evitar é entrega lenta com baixo controle: build customizado sem propriedade real do contrato entrega todo o custo do build sem nenhum valor estratégico. Provas de conceito sem foco e scripts departamentais que nunca endurecem se encaixam aqui.
Contexto é a plataforma. Construa como tal.
El problema de contexto en la codificación agéntica empresarial
Una sola tarea de agente en un monorepo empresarial real puede leer millones de tokens para responder una única pregunta. No es un caso extremo teórico — es el comportamiento predeterminado cuando no existe una capa semántica entre el agente y el código fuente. Comparado con el contexto de calidad de compilador, la recuperación ingenua cuesta 10× más por tarea y produce peores resultados.
Tres enfoques dominan el stack actual, y los tres fallan de maneras predecibles. La recuperación bruta — búsqueda por embeddings sobre archivos fuente — no tiene conciencia de resolución de símbolos, información de tipos ni grafos de llamadas. El agente recupera texto que parece relacionado, no código que es estructuralmente relacionado. Los prompts curados manualmente (wikis, AGENTS.md, archivos README pegados en el contexto) quedan obsoletos en semanas y no tienen vínculo con el build; no hay forma de verificar si las convenciones descritas en el prompt aún coinciden con lo que el compilador impone. Los volcados del repositorio completo saturan la ventana de contexto con código repetitivo, reduciendo la relación señal-ruido por debajo del umbral en que el agente puede actuar de manera segura.
Los tres enfoques comparten una causa raíz: no existe una capa semántica entre los agentes y el código en el que operan.
El contexto semántico es lo que el compilador sabe, puesto a disposición de los agentes. La diferencia entre contexto léxico (tokens, archivos, líneas — lo que devuelve grep) y contexto semántico (símbolos, tipos, llamadas, configuraciones — lo que resuelve el build) es la diferencia entre un agente que adivina y uno que razona. SCL-AD hace que la segunda columna sea consultable, versionada y vinculada a políticas — sin convertir cada agente en un compilador.
La arquitectura se apoya en cuatro pilares: Precomputar (construir grafos de símbolos, tipos y dependencias una vez, actualizar en cada commit — pagar el costo del compilador en CI, no por tarea); Dirigir (entregar solo el fragmento que necesita la tarea — una recipe por intención, no un volcado por repositorio); Ejecutar (exponer contexto mediante contratos estables: archivos estáticos, herramientas MCP o híbrido); y Coordinar (gobernar el ciclo de vida, identidad, clasificación y auditoría en recipes, registries y agentes).
Arquitectura: cuatro capas y sus contratos
El Semantic Context Layer es un stack de cuatro capas en el que cada capa expone un contrato estable a la capa superior. Los agentes solo ven la capa más alta.
Capa 01 — Code Intelligence es la fundación de calidad de compilador: grafos de símbolos, tipos y llamadas. Todo lo que está encima depende de que esta capa sea correcta y esté actualizada.
Capa 02 — Context Recipes son unidades composables de contexto moldeadas por la intención. Cada recipe consume artefactos de la Capa 01 y produce un artefacto dirigido y versionado, dimensionado para una tarea específica del agente. Una recipe es un contrato entre intención y contexto.
Capa 03 — Context Registry gestiona almacenamiento, descubrimiento, versionado y actualización. Funciona como un gestor de paquetes para contexto: URIs estables, direccionamiento por contenido y alias para versiones en movimiento.
Capa 04 — Agent Integration define cómo los agentes reciben el contexto — mediante archivos estáticos inyectados en el repositorio, llamadas a herramientas via servidor MCP o configuraciones personalizadas de agente.
Tres componentes atraviesan todas las capas: el Context Store (almacenamiento persistente y direccionado por contenido con URIs estables y hashes de contenido, soportando topologías colocalizadas, centrales o federadas); Recuperación (descubrimiento por repositorio, capacidad o contenido, con artefactos inmutables y alias para “latest stable”); y Gobernanza (propagación de identidad, etiquetas de clasificación, RBAC, pista de auditoría — las recipes se firman y versionan como cualquier artefacto de código).
Cuatro preocupaciones transversales atraviesan todo el stack: Identidad (RBAC por recipe y por artefacto, no por plataforma); Observabilidad (cada recuperación emite un span OpenTelemetry que captura agente, recipe, versión del artefacto, clasificación, latencia y tokens); Seguridad (las etiquetas de clasificación viajan con el artefacto; las recipes que leen datos regulados requieren aprobación explícita de política); y Ciclo de vida (versionado de manifiesto, hashes de contenido, políticas de actualización, alias de deprecación — el contexto obsoleto es el modo de fallo silencioso).
Code intelligence: la fundación de calidad de compilador
El contexto aproximado produce código aproximado. Sin anclaje de calidad de compilador, los agentes alucinan símbolos que parecen plausibles pero no existen, pierden callers en refactorizaciones entre módulos y fallan en instanciaciones genéricas en el build. Con él, el agente sabe qué llamadas cruzan fronteras de módulo, qué genéricos están vinculados, qué claves de configuración se leen en tiempo de ejecución y dónde vive cada definición.
Siete capacidades definen una capa de code intelligence completa — sin crédito parcial:
- Resolución de símbolos — cada referencia apunta a su definición única en archivos y módulos
- Resolución de tipos — genéricos, tipos inferidos y sobrecargas resueltos con plena fidelidad
- Grafo de herencia — clases, interfaces, traits y sus implementadores en todo el workspace
- Grafos de llamadas — llamadas estáticas y virtuales, intra e intermodulares, con cardinalidad
- Resolución de dependencias — directas, transitivas y procedencia de cada paquete externo
- Mapeo de configuración — qué claves se leen dónde, con valores predeterminados y reglas de validación
- Rangos de fuente — cada dato incluye archivo, línea y columna para evidencia de ida y vuelta
La ausencia de cualquiera de estas siete capacidades degrada la calidad de las recipes en la cadena descendente. El pipeline fluye desde la fuente (cada commit dispara una ejecución) a través de compilación o análisis de AST (produciendo un AST tipado), extracción de grafos (símbolos, tipos, llamadas, herencia, deps, mapa de configuración, rangos de fuente), hasta artefactos consultables consumidos por la Capa 02. El principio central: pagar el costo del compilador en CI — una vez por commit — no por tarea del agente.
La cobertura por lenguaje sigue toolchains establecidas: JVM y .NET usan compiladores nativos vía LSP; TypeScript usa la API del compilador, Python usa Pyright o Pyre; Go y Rust usan gopls y rust-analyzer; workloads mainframe (COBOL, PL/I) usan parsers especializados con resolución de copybook y JCL; las fronteras de servicios polyglot se resuelven vía REST schemas, OpenAPI, gRPC IDL y Avro. La regla es un contrato, muchos engines — la Capa 02 no debe saber qué compilador produjo el grafo.
Context recipes: unidades composables de intención
Una recipe responde bien a una pregunta. Seis recipes se componen en un agente útil. Sesenta recipes describen una plataforma.
Seis categorías cubren la mayoría de las tareas empresariales:
| Categoría | Pregunta respondida |
|---|---|
| Structural Inventory | ”¿Qué hay en este repositorio?” — módulos, paquetes, clases, superficie de API pública, ownership |
| Dependency Intelligence | ”¿De qué depende?” — directas, transitivas, procedencia, vulnerabilidades, postura de licencias |
| Service Topology | ”¿Cómo se comunica con otros?” — endpoints, colas, datastores y las llamadas que los conectan |
| Convention Extraction | ”¿Qué patrones sigue?” — logging, manejo de errores, nomenclatura, reglas de capas, observados en código |
| Test Intent Mapping | ”¿Qué verifica realmente?” — tests agrupados por intención y los caminos de código que ejercita cada uno |
| Configuration Surface | ”¿Qué puede cambiar en el deploy?” — claves leídas en tiempo de ejecución, valores predeterminados, validación, vinculación de entorno |
Cada recipe tiene cuatro componentes: un manifiesto (recipe.yaml) que declara identidad, versión, inputs, outputs, clasificación y política de actualización; una implementación (función pura sobre grafos — reproducible, determinista, sin efectos secundarios); tests (snapshot tests sobre un grafo fijo — el CI falla si el output cambia sin un bump explícito de versión); y docs (un párrafo de intención, un ejemplo de output — los consumidores de recipes nunca deberían necesitar leer la implementación).
Cinco reglas de autoría mantienen las recipes confiables: una pregunta por recipe (si el título necesita un “y”, divídala en dos); un token budget declarado por output aplicado en el build; un schema de output estable con versiones mayores para cambios que rompen compatibilidad; sin fugas de secretos (las etiquetas de clasificación se propagan de inputs a outputs — las recipes no pueden ampliar el alcance); y procedencia siempre (cada dato en el output cita su rango de fuente de la Capa 01).
Registry y distribución
El registry es un gestor de paquetes para contexto. Cubre tres responsabilidades: almacenamiento (colocalizado, central o federado — elija uno y documente las compensaciones); descubrimiento (URIs estables, direccionamiento por contenido, alias para “latest stable” que rastrean versiones en movimiento de forma segura); y actualización (disparada por commit, programada o dirigida por eventos — la política de staleness declara cuándo un artefacto obsoleto debe ser rechazado).
La distribución fluye de un commit a un agente en tres saltos. Salto 01 es el repositorio del desarrollador y el CI: el commit dispara la actualización de la Capa 01, ejecución de la recipe, snapshot de test, luego firmar y etiquetar. Salto 02 es el registry: almacenamiento direccionado por contenido, URIs estables, alias de versión, etiquetas de clasificación, política de retención. Salto 03 es el MCP gateway o fetch estático: se resuelve la identidad, se aplica RBAC, se obtiene el artefacto, se emite el span de auditoría y se devuelve el contexto al agente dentro del presupuesto. La identidad y la auditoría atraviesan cada salto. Los artefactos obsoletos o no autorizados son rechazados en el gateway.
Patrones de integración con agentes
Tres patrones cubren la superficie de integración. Inyección de Archivo Estático pre-renderiza el contexto en archivos del repositorio (AGENTS.md, .cursor/rules, .github/copilot-instructions.md, etc.) generados por recipes en CI. Ideal para convenciones estables con baja rotación; sin infraestructura que desplegar; punto de partida más sencillo. MCP Server expone recipes como llamadas a herramientas MCP bajo demanda — el agente obtiene solo lo que necesita, cuando lo necesita, con identidad y auditoría por llamada. Ideal para repositorios grandes, consultas dinámicas y presupuestos ajustados de tokens; requiere un gateway. Distribución Híbrida combina una base estática para convenciones con MCP para consultas profundas — el patrón recomendado a escala.
Mapeo por agente: GitHub Copilot usa .github/copilot-instructions.md más instrucciones personalizadas de repositorio (MCP está emergiendo); Cursor y Windsurf usan reglas basadas en archivos con alcance, ambos soportando servidores MCP; Claude Code usa un modelo en capas de base estática, skills bajo demanda y herramientas MCP — la distribución híbrida se mapea limpiamente; los agentes internos personalizados llaman a las APIs de recipe directamente vía SDK.
Gobernanza y cumplimiento
La gobernanza aplica los mismos controles que el código fuente — sin excepciones para “contexto de IA.” Cada recuperación pasa por tres verificaciones: identidad y RBAC (¿la identidad de este agente corresponde a un rol autorizado a leer esta recipe? — rechazar si no); clasificación (¿la etiqueta del artefacto encaja en el límite de confianza del runtime del agente? — bloquear si no coincide); frescura (¿el artefacto está dentro de la ventana de política de staleness de la recipe? — actualizar o fallar). El span de auditoría captura la decisión y el motivo independientemente del resultado.
Cinco roles tienen responsabilidades explícitas: platform owner, recipe steward, repository owner, security reviewer y auditor — con el auditor independiente de los equipos de plataforma y repositorio. Seis dominios de política tienen cada uno una política escrita, un control mapeado y una consulta de auditoría que prueba la aplicación: alcance, clasificación, acceso, actualización, retención e integración.
Cuatro familias de control completan el panorama de gobernanza: identidad y acceso (RBAC por recipe, propagación de identidad, tokens con alcance, SPIFFE para identidad entre servicios); integridad (artefactos firmados, hashes de contenido, atestación de build — la alteración se detecta en el momento de la recuperación); ciclo de vida (versionado, actualización, deprecación, eliminación — sin artefactos huérfanos, cada URI resuelve o devuelve una lápida); y observabilidad (spans OTel, registro de auditoría, etiquetas de clasificación y decisiones de política consultables por el auditor sin ayuda de ingeniería).
Hoja de ruta de adopción y métricas de éxito
La hoja de ruta de referencia abarca cinco fases en doce meses. Fase 0 (Mes 0) — Discovery: inventariar agentes, mapear repositorios, establecer baseline de gasto de tokens; salir con un documento de baseline. Fase 1 (Meses 1–2) — Pilot: un repositorio, tres recipes, un agente, inyección estática; salir cuando el gasto de tokens caiga un 30%. Fase 2 (Meses 3–5) — Expansion: cinco repositorios, registry desplegado, MCP activo para consultas profundas; salir con la gobernanza funcionando. Fase 3 (Meses 6–9) — Platform: autoservicio para nuevos repositorios, híbrido como patrón predeterminado; salir cuando se cumpla el SLA. Fase 4 (Meses 10–12+) — Optimization: ajuste continuo, recipes deprecadas, las métricas impulsan el ROI; sin salida — continuo.
Seis métricas, medidas en cada release: gasto de tokens (mediana de tokens por tarea — meta de reducción del 30–60% vs baseline en dos fases); tasa de alucinación (referencias a símbolos inexistentes — meta tendiendo a cero con contexto de calidad de compilador); adherencia a convenciones (código generado que coincide con las convenciones del repositorio en el primer intento — meta por encima del 80%); tiempo hasta la primera sugerencia útil (segundos desde el inicio de la tarea hasta una sugerencia aceptada — meta por debajo de 8 segundos); satisfación del desarrollador (NPS trimestral — debe crecer a medida que maduran las recipes); y throughput de PRs (PRs fusionados por desarrollador por semana, controlado por repositorio — la señal rezagada que justifica la inversión).
Build, buy o híbrido
Tres caminos implementan la misma arquitectura. Camino A — Build: construir sobre Roslyn, LSP, GitHub Actions, almacenamiento de objetos de Azure y un MCP gateway que usted opera. Máximo control sobre recipes, registry y gateway; camino más lento; mayor necesidad de expertise interno. Gana en industrias reguladas, necesidades de personalización profunda y footprints mainframe. Camino B — Buy: adoptar una plataforma comercial que entrega contexto de calidad de compilador como producto (ej: Moderne). Tiempo hasta el valor más rápido; el lock-in de proveedor es la compensación. Gana con cronogramas agresivos y modernización de legado a gran escala. Camino C — Híbrido: poseer recipes, registry y gateway; alquilar code intelligence a un proveedor. Desacopla el contrato duradero del engine. Lo mejor de ambos para la mayoría de las empresas hoy — gana en portafolios que mezclan greenfield y legado.
El cuadrante a evitar es entrega lenta con bajo control: build personalizado sin propiedad real del contrato entrega todo el costo del build sin ningún valor estratégico. Las pruebas de concepto sin foco y los scripts departamentales que nunca se endurecen caen aquí.
El contexto es la plataforma. Constrúyalo como tal.
Start with the platform, not the agents. Comece pela plataforma, não pelos agentes. Comience por la plataforma, no por los agentes.
Building the future of software development with AI and Agentic DevOps.