Decisões mais rápidas. Onboarding em dias, não semanas. IA que responde com evidência.
Documentação que envelhece cria decisões baseadas em fatos obsoletos. Ferramentas de IA sem grounding alucinam. O Knowledge OS é a infraestrutura que transforma conhecimento corporativo em ativo executável — com limites, rastreabilidade e custos sob controle.
- Em uma frase
- O Knowledge OS trata o conhecimento corporativo como infraestrutura cognitiva governada, não como repositório passivo de documentos: uma plataforma que o transforma em ativo executável, com limites, rastreabilidade e custos sob controle.
- Formato
- Apresentação
- Profundidade
- Leitura aprofundada · ~3 min para a ideia central · ~20 min completo
Prefere o essencial antes? Ler a síntese (~1 min)
Por que o conhecimento corporativo falha — e por que isso custa caro
Antes de qualquer arquitetura, três problemas reais corroem o valor estratégico do conhecimento. Cada um deles tem custo operacional, financeiro e de risco.
A documentação envelhece. As decisões, não.
RFCs aprovadas em 2022 ainda guiam arquiteturas em 2026. Seniors que sabem a história real estão em 1:1s — não na wiki. Quando eles saem, o conhecimento some.
IA que alucina é pior do que ausência de IA.
Ferramentas genéricas de LLM respondem com confiança sobre contexto que não conhecem. Uma decisão de produto tomada em cima de uma resposta inventada tem custo real.
O conhecimento crítico mora onde não pode ser auditado.
Slack DMs. Apresentações sem versionamento. A cabeça de quem foi embora. Conhecimento não recuperável não é patrimônio — é risco estratégico.
Para dimensionar o impacto
- • Estima-se que 40% do tempo de engenheiros seniores seja gasto respondendo perguntas que já foram respondidas — informalmente, sem registro auditável.
- • Onboarding médio em empresas sem KM estruturado: 3 a 6 meses até produtividade plena. Cada mês adicional é custo direto de payroll sem retorno.
- • Quando um engenheiro sênior sai, o conhecimento que vai embora não está no Confluence — está nas conversas que nunca foram codificadas.
Por que isso importa para o board
A especificação original estava densa em engenharia, mas silenciosa em business outcomes. Esta revisão traduz a arquitetura em três outcomes mensuráveis e três riscos evitados.
Time-to-Decision −60%
Do "quem sabe disso?" para "qual a evidência?". Decisões de arquitetura e produto deixam de depender de tribal knowledge.
Reuso Cognitivo +3x
Specs, decisões e padrões são consumidos por agentes — não morrem em PDFs. Cada novo projeto parte de um lastro semântico.
Compliance by Design
Lineage entre requisito → código → teste → deploy. Auditoria deixa de ser arqueologia.
Três riscos que esta arquitetura evita
- Risco 1 — Knowledge Decay: documentação ficcional desalinhada do código produtivo, gerando decisões em cima de fatos obsoletos.
- Risco 2 — Hallucination at Scale: agentes IA respondendo sem grounding em fontes auditáveis, contaminando decisões de produto.
- Risco 3 — Shadow Knowledge: conhecimento crítico em DMs, decks e cabeças de seniors — não recuperável, não auditável, não escalável.
"O ativo mais subutilizado da organização não é o dado bruto. É o julgamento contextual que ninguém soube codificar."
10 dimensões da revisão crítica
Cada item lista o gap encontrado na proposta original e a contramedida concreta aplicada nesta versão.
01 Clareza Executiva
Gap original
- Linguagem 100% técnica; ausência de outcomes financeiros e operacionais.
- Sem narrativa de transformação — apenas catálogo de componentes.
- Nenhum mapeamento entre arquitetura e KPIs de negócio.
Correção aplicada
- Camada executiva no topo: 3 outcomes, 3 riscos, 1 quote.
- Cada componente arquitetural justificado por business capability.
- Roadmap com critérios de saída por fase em linguagem de board.
02 Operacionalização
Gap original
- Conceitual — "usaremos GraphRAG" sem fluxo de uso real.
- Sem jornadas de engenheiro / PM / SRE / arquiteto.
- Falta integração com ferramentas existentes (Jira, GitHub, IDE).
Correção aplicada
- Quatro knowledge journeys documentadas (ver §4).
- Pontos de integração: PR check, IDE plugin, Slack agent, ChatOps.
- Workflow operacional com handoffs explícitos entre humano/agente.
03 Governança Enterprise
Gap original
- "Governança" mencionada sem ownership, stewardship ou approval flow.
- Sem versionamento semântico de specs ou decisões.
- Lifecycle do conhecimento implícito (criação, revisão, deprecação).
Correção aplicada
- Modelo RACI por knowledge domain (§5).
- SemVer de specs + ADRs + ontologia; deprecação com janela e replacements.
- Knowledge Council com cadência mensal e mandato definido.
04 Escalabilidade Organizacional
Gap original
- Modelo central — não escala para múltiplos times/BU.
- Risco alto de duplicidade semântica entre domínios.
- Sem política de contribuição nem federação.
Correção aplicada
- Modelo federado: core ontology + domain extensions.
- Padrão "Knowledge Mesh" inspirado em Data Mesh (domain ownership).
- Contract testing semântico entre domínios para evitar drift.
05 Arquitetura Cognitiva
Gap original
- Memória monolítica — episódica e semântica misturadas.
- Sem política de retrieval (recência × autoridade × proximidade).
- Conflitos semânticos resolvidos implicitamente pelo LLM.
Correção aplicada
- Separação de memórias: episódica · semântica · procedural · contextual.
- Retrieval policy declarativa com precedence rules auditáveis.
- Conflict resolver explícito + drift detector contextual.
06 Estratégia IA-First
Gap original
- Agentes mencionados sem feedback loop, sem self-healing.
- Nenhum quality gate cognitivo entre retrieval e geração.
- Sem score de confiança nem tracing contextual.
Correção aplicada
- Loop cognitivo Sense → Retrieve → Reason → Validate → Act → Learn.
- Quality gates: groundedness, faithfulness, answer-relevance, citation coverage.
- Tracing semântico ponta-a-ponta (OpenTelemetry + LLM spans).
07 Engenharia de Conhecimento
Gap original
- Granularidade documental indefinida (capítulo? parágrafo? bloco?).
- Metadata frágil; sem entidades canônicas.
- Sem capability map nem domain catalog.
Correção aplicada
- Atomic units: Claim, Decision, Constraint, Pattern, Risk.
- Ontologia base + schemas semânticos versionados em JSON-LD.
- Capability map ligando domínio → entidade → spec → agente.
08 Rastreabilidade
Gap original
- Lineage rasa: spec ↔ código sem dependências transitivas.
- Sem impact graph para mudanças semânticas.
- Validação não cobre cobertura de requisito.
Correção aplicada
- Traceability matrix: requisito → spec → ADR → código → teste → deploy → telemetria.
- Impact graph navegável. Human-in-the-Loop gate: mudanças que orfanam requisitos disparam revisão assistida — não bloqueio automático.
- Coverage cognitivo: % de claims com evidência rastreável.
09 Observabilidade Cognitiva
Gap original
- Sem métricas de retrieval, qualidade semântica ou cobertura.
- Sem SLA cognitivo (latência, freshness, groundedness).
- Sem dashboard de health do conhecimento.
Correção aplicada
- 18 KPIs cognitivos divididos em 4 camadas (§7).
- SLOs por domínio: P95 retrieval < 800ms; freshness < 24h.
- Dashboard "Knowledge Vital Signs" com alerting.
10 Roadmap & Adoção
Gap original
- Big bang implícito — adote tudo, espere milagre.
- Sem quick wins, sem pilotos, sem critérios de saída.
- Sem mapa de dependências entre componentes.
Correção aplicada
- 4 fases incrementais: Foundation → Pilot → Federate → Autonomous.
- Quick wins de 30/60/90 dias com KPI mensurável por fase.
- Critérios de promoção entre fases auditáveis (§8).
Documentação tradicional × Knowledge OS
Visão de board: 9 dimensões em 30 segundos.
| Dimensão | Modelo atual | Knowledge OS | Impacto |
|---|---|---|---|
| Organização | Por stack tecnológico — silos React/Node/DB. | Por bounded context (Orders, Payments, Identity). | Coesão +80% |
| Recuperação | Navegação manual + busca lexical. | Hybrid retrieval: vector + BM25 + graph traversal. | Precisão 3× |
| Engenharia | IA gera com contexto raso e ambíguo. | Agentes consomem contexto pré-computado e citável. | Velocity 3–5× |
| Governança | Ownership implícito; decisões em cabeças. | ADRs versionados + RACI federado + audit trail. | Compliance ↑ |
| Escalabilidade | Onboarding lento; conhecimento tribal. | Knowledge mesh com domain ownership. | Onboarding −70% |
| Validação | Testes como verificação posterior. | Testes como spec executável (contract/golden/property). | Bugs −60% |
| Rastreabilidade | Zero — código não liga a requisito. | Policy → Contract → Spec → Test → Code → Deploy. | Audit 100% |
| Cognição IA | Doc longa polui o context window. | Atomic units tipados; chunk-optimal. | Hallucination < 2% |
| Decisão | Reuniões para descobrir o que existe. | Pergunta → resposta citada em segundos. | TTD −60% |
Sete camadas do Knowledge OS
Cada camada tem responsabilidade única, contratos explícitos e SLA próprio. Substituível sem reescrever a stack.
Loop Cognitivo Padrão
Toda interação atravessa este pipeline. Cada etapa é instrumentada e auditável.
Self-healing: falhas em VALIDATE re-acionam RETRIEVE com contexto expandido. Backpressure: baixa confiança em REASON aciona escalation para humano via approval gate.
Sua IA tem limite. E você sabe exatamente onde ele é.
Agentes autônomos podem economizar centenas de horas — ou queimar orçamento em loops infinitos. O Knowledge OS vem com Circuit Breakers cognitivos configurados por padrão: autonomia com contenção.
Fluxo de Hard Escalation
Toda execução cognitiva atravessa o loop padrão. Falhas em Validate retornam para Retrieve com contexto expandido — mas apenas dentro de uma janela limitada de tentativas. Atingido o limite, o Circuit Breaker é acionado.
Limites por fase de autonomia
Cada fase do roadmap opera com limites e mecanismos de escalação distintos. Limites são padrões configuráveis via admin panel.
| Fase | Autonomia do agente | Limite de tentativas | Mecanismo de escalação | Proteção FinOps |
|---|---|---|---|---|
| 1 — Foundation | Apenas leitura (read-only) | — | Sempre humano | Custo previsível (sem write) |
| 2 — Pilot Cognitive | Consulta + sugestão (HITL) | 1 tentativa | Human-in-the-Loop em cada ação | Budget alertado em 70% / 90% |
| 3 — Federate / Agentic Assist | Execução supervisionada | 3 tentativas | Hard Escalation (review humana) | Budget mensal + alertas escalonados |
| 4 — Autonomous | Execução autônoma (write) | 3 tentativas | Hard Escalation obrigatório | Budget configurado obrigatório |
FinOps para IA — métricas operadas
Cada execução de agente é tratada como recurso mensurável — análogo ao FinOps de cloud, mas para infraestrutura cognitiva.
Princípios não-negociáveis de governança de custo
- • Sem teto, sem autonomia. A Fase 4 (Agentes Autônomos) não pode ser ativada sem um budget mensal configurado e aprovado.
- • Toda escalação é auditável. Cada Hard Escalation gera evento com contexto, custo estimado em USD e tokens consumidos.
- • Alertas escalonados. Notificações em 70%, 90% e 100% do budget mensal — antes do incidente, não depois.
- • Limites configuráveis, não hard-coded. Os 3× tentativas são padrão; cada org ajusta via admin panel conforme apetite ao risco.
Documentação que se paga para quem documenta bem.
A razão pela qual documentação sempre ficou desatualizada não é falta de disciplina — é falta de incentivo visível. O Knowledge OS muda a equação: quem documenta bem tem seu trabalho multiplicado por agentes, e isso aparece para todo o time.
Modelo Punitivo (o que não funciona)
- Motivação: evitar que o deploy seja bloqueado.
- Sinal de qualidade: passar no quality gate.
- Comportamento: documentação mínima viável para passar.
- Feedback: erro no pipeline — nenhum reconhecimento pelo bom trabalho.
- Resultado: conformidade maliciosa. Qualidade baixa. Frustração.
Índice de Reuso (o que muda)
- Motivação: ter o trabalho reconhecido e multiplicado por agentes.
- Sinal de qualidade: seu conteúdo resolve problemas de outros times.
- Comportamento: documentação como investimento profissional visível.
- Feedback: dashboard pessoal de impacto cross-team em tempo real.
- Resultado: cultura orgânica. Qualidade crescente. Orgulho de contribuir.
Como o Índice de Reuso funciona
Da contribuição ao reconhecimento, em 5 passos rastreáveis. Cada passo gera um evento auditável no Knowledge Graph.
Você documenta uma decisão ou padrão no Knowledge OS
Um ADR, uma spec, um runbook. Tipado, citável, com frontmatter semântico.
Um agente de outro time usa seu conteúdo para resolver um problema
Retrieval citável: cada resposta carrega a fonte. Seu trabalho deixa de ser invisível.
O evento é registrado — você é creditado como fonte
Citação aparece no trace OpenTelemetry. Lineage completo: query → resposta → sua spec.
Seu Índice de Reuso sobe. Gestores e pares veem a contribuição
Dashboard pessoal e de time. Conversa de 1:1 e review deixam de ser sobre suposições.
Na próxima sprint, você documenta mais — porque vale a pena
O incentivo se torna estrutural. Cultura emerge do sistema, não de um pôster na parede.
Métricas do Índice de Reuso
Indicadores individuais e de time, exibidos em dashboard pessoal. Mensuram impacto profissional em vez de policiamento.
Quantas vezes seu conteúdo ajudou outros times
Soma ponderada de decisões influenciadas
% das suas contribuições ainda válidas
Quantas specs referenciam seu trabalho
"Antes eu documentava porque era obrigado. Agora documento porque quando um agente usa minha spec para resolver um bug em outro time, meu nome aparece no trace. Isso mudou como eu penso sobre documentar."
Conhecimento tipado, granular e endereçável
Sem tipologia computável, agentes recebem ruído. Estes são os 6 tipos canônicos + o frontmatter que torna cada artefato citável + o layout single-source-of-truth.
Os 6 tipos canônicos de unidade atômica
Verdades do domínio
Invariantes objetivos e estáveis. Não opinião.
type: fact id: FACT-001 # "Pedido tem estado"
Regras ativas
Regra de negócio validável e executável.
type: policy id: POL-042 # "Cancelar requer auth"
ADRs versionados
Decisão arquitetural com contexto e consequências.
type: adr id: ADR-019 # "Adotar CQRS em Orders"
APIs e schemas
Interface formal entre componentes/serviços.
type: contract id: CNT-007 # "POST /orders spec"
Restrições não-funcionais
Performance, compliance, segurança — limites duros.
type: constraint id: CON-003 # "p99 < 200ms"
Runbooks executáveis
Processo operacional passo-a-passo, auditável.
type: procedure id: PRC-012 # "Deploy rollback"
Frontmatter semântico — exemplo completo
Cada documento carrega metadata que o torna citável, rastreável e indexável por agentes. Sem frontmatter, não há semântica computável.
--- id: FEAT-042 type: feature-spec title: "Checkout Express" domain: orders status: approved version: 2.1.0 owner: "@squad-checkout" created: 2026-03-15 updated: 2026-04-20 depends_on: - FEAT-018 # auth-flow - CNT-007 # orders-api implements: - POL-042 # cancel-policy - ADR-019 # cqrs-pattern validated_by: - TEST-FEAT-042-001 - CONTRACT-FEAT-042 tags: [checkout, payments, critical-path] context_for_agents: - checkout-agent - payments-agent retrieval_weight: 0.92 freshness_sla: 7d ---
Estrutura de diretórios canônica
Layout single-source-of-truth. Cada pasta tem dono, contrato e CI gate próprio. Índices semânticos gerados em build.
docs/ ├── domains/ # Bounded Contexts DDD │ ├── orders/ │ │ ├── capabilities.md │ │ ├── ubiquitous-language.md │ │ └── specs/ │ ├── payments/ │ └── identity/ │ ├── specs/ # Spec Driven Dev │ ├── features/FEAT-001-checkout.md │ ├── apis/orders-api.openapi.yaml │ └── contracts/CNT-007.md │ ├── architecture/ # Decisões │ ├── adr/ADR-019-cqrs.md │ ├── diagrams/ │ └── capability-map.md │ ├── engineering/ # Padrões + DSL │ ├── patterns/ │ ├── dsl/ │ └── runbooks/ │ ├── validation/ # Testes como spec │ ├── golden-tests/ │ ├── contract-tests/ │ └── property-tests/ │ ├── ontology/ # Modelo formal │ ├── domain-model.ttl │ └── relationships.yaml │ ├── glossary/ # Linguagem ubíqua │ └── terms.yaml │ ├── agents/ # Context por agente │ ├── orders-agent.ctx.yaml │ └── payments-agent.ctx.yaml │ └── index/ # Gerado em CI ├── knowledge-graph.json └── embeddings.index
Quatro jornadas reais de uso
Sai do conceitual: estes são fluxos auditáveis com handoffs explícitos humano ↔ agente.
Jornada 1 — Engineer escrevendo PR
- IDE plugin recupera specs e ADRs relacionados ao arquivo.
- Agente sugere padrões já estabelecidos para o domínio.
- PR check valida: cobertura de spec, drift de contrato, citação obrigatória.
- ADR auto-rascunhado quando decisão arquitetural é detectada.
- Merge gera evento → KG indexa nova evidência → métricas atualizadas.
Jornada 2 — PM definindo feature
- Agente recupera capabilities relacionadas no capability map.
- Sugere ADRs e constraints históricos que limitam escopo.
- Gera spec-stub em DSL com requisitos verificáveis (Given/When/Then).
- Approval gate: arquiteto + tech lead validam impact graph.
- Spec versionada vira contrato consumido por agentes downstream.
Jornada 3 — SRE em incidente
- Sintoma na telemetria → query no KG retorna runbooks + ADRs do componente.
- Agente correlaciona com mudanças recentes (lineage reverso).
- Sugere mitigations já validadas; se nova, exige approval explícita.
- Postmortem auto-rascunhado com evidências ligadas (logs, traces, ADR).
- Lessons learned viram Pattern ou Risk no KG.
Jornada 4 — Auditor / Compliance
- Pergunta: "evidência de que controle X está implementado em Y".
- Lineage navega: requisito regulatório → spec → ADR → código → teste → deploy.
- Cada nó com timestamp, autor, aprovação e versão.
- Resposta sempre citada; sem citação, sem afirmação.
- Export auditável (PDF + JSON-LD assinado).
Cadeia de rastreabilidade ponta-a-ponta
Cada artefato da cadeia carrega ID estável, versão, autor, timestamp e citação para a fonte de cima. Auditoria deixa de ser arqueologia.
Capacidades que o grafo habilita
Impact Analysis
"Dado ADR-019, quais specs/contratos/testes serão afetados?" — resposta automática via traversal.
Conflict Detection
Políticas contraditórias detectadas por análise de arestas conflitantes no grafo.
GraphRAG Retrieval
Agente navega o grafo para recuperar contexto estruturado, não chunks isolados por similaridade.
Auditabilidade Completa
Qualquer linha de código rastreável até a política de negócio que a originou.
Onboarding Contextual
"O que preciso saber para trabalhar em Orders?" — resposta estruturada automática.
Testes como conhecimento executável
Um teste que falha é uma spec violada, rastreável até a política que a originou. Três modalidades complementares.
Contract Tests
Verificam que a implementação honra o contrato formal. Executados a cada PR; bloqueiam merge em violação.
// refs: CNT-007, POL-042 describe('POST /orders/cancel', () => { it('requires auth (POL-042)', ...); it('returns 403 for anon', ...); });
Golden Tests
Snapshots de comportamento aprovados pela equipe. Detectam regressões semânticas, não apenas sintáticas.
// golden: FEAT-042-checkout expect(result).toMatchGolden( 'checkout-express-v2.1' );
Property-Based
Casos gerados aleatoriamente a partir de constraints formais. Garante invariantes em casos extremos.
// constraint: CON-003 property('p99 < 200ms', () => { fc.assert(latency < 200); });
Agent context file — pré-computado, versionado, governado
Cada agente especializado por bounded context recebe contexto pré-computado em build-time. Context window limpo, custo previsível, geração determinística.
# agents/orders-agent.ctx.yaml — v3.2.0 agent: orders-specialist version: 3.2.0 domain: orders owner: "@platform-cognition" context_sources: facts: - domains/orders/capabilities.md - glossary/orders-terms.yaml policies: - POL-042 # cancel-auth - POL-055 # refund-window - POL-071 # fraud-detection contracts: - CNT-007 # orders-api - CNT-012 # payments-api decisions: - ADR-019 # cqrs pattern - ADR-031 # event-sourcing constraints: - CON-003 # latency p99 - CON-008 # data-residency patterns: - engineering/patterns/saga.md - engineering/patterns/outbox.md memory: episodic: pr-context semantic: kg.orders.v3 procedural: dsl.orders retention: 90d retrieval: strategy: hybrid graph_depth: 2 semantic_threshold: 0.82 max_tokens: 8192 precedence: [authority, recency, proximity] min_groundedness: 0.85 capabilities: - spec-generation - code-review - contract-validation - impact-analysis quality_gates: - groundedness - faithfulness - citation_coverage - safety on_failure: escalate_to_human observability: trace: otel metrics: [latency_p95, groundedness_score, escalation_rate, cost_usd]
Por que agentes especializados?
Foco de domínio
Agente de Orders não carrega Billing — context window limpo, menor custo, maior precisão.
Pré-computação
Retrieval em build-time. Resposta mais rápida e determinística.
Governança como API
Cada agente tem ownership, versão SemVer e audit trail próprios.
Evolução independente
Contexto evolui com o domínio — sem acoplamento entre agentes.
Catálogo de agentes
Modelo federado de governança
Inspirado em Data Mesh: core central + domain ownership — sem cair no extremo do data lake monolítico nem no caos do bottom-up puro.
| Papel | Escopo | Responsabilidade | Cadência | SLA |
|---|---|---|---|---|
| Knowledge Council | Org-wide | Aprovação de mudanças na core ontology, política de retrieval, padrões de DSL. | Mensal + ad hoc | Decisão em ≤ 10 dias úteis |
| Domain Owner | Knowledge Domain | Curadoria de specs, ADRs, ontology do domínio. Quality gates internos. | Semanal | Freshness < 72h |
| Knowledge Steward | Sub-domínio / time | Triage de contribuições, deprecação, revisão de evidências. | Diária (assíncrona) | Triage < 24h |
| Platform Team | L1–L5 (substrate → reasoning) | Operação da plataforma, observabilidade, SLOs cognitivos. | Contínua | P95 retrieval < 800ms |
| Contributor | Qualquer | PR de spec, ADR, evidência. Sob template + lint semântico. | Just-in-time | — |
| Auditor | Read-only cross-domain | Verificação de lineage, evidência, conformidade regulatória. | Trimestral | Export < 1h |
Lifecycle do conhecimento
- • SemVer obrigatório (MAJOR.MINOR.PATCH).
- • Deprecação com janela mínima de 90 dias e replacement pointer.
- • Specs retiradas continuam navegáveis (immutable archive).
Política de federação
- • Core ontology compartilhada — mudanças exigem Knowledge Council.
- • Domain extensions — autônomas, sob curadoria do Domain Owner.
- • Contract testing semântico entre domínios em CI.
- • Aliases controlados evitam duplicidade (ex: "client" ≠ "customer" ≠ "account").
- • Federated query com policy enforcement por domínio.
Quatro memórias, não uma
A proposta original tratava memória como bucket único. Aqui separamos por função cognitiva, com políticas de retenção e retrieval distintas.
O que aconteceu
Conversas, runs de agente, decisões pontuais.
TTL: 30–180 dias.
Uso: contexto curto, debugging.
O que é verdade
Entidades canônicas, ontologia, fatos versionados.
TTL: permanente (versionado).
Uso: grounding, retrieval principal.
Como fazer
Workflows, runbooks, DSLs de agente, padrões.
TTL: por SemVer.
Uso: execução de tarefas.
Onde estamos
Tenant, usuário, projeto, ambiente, permissões.
TTL: sessão.
Uso: escopo + autorização.
Retrieval policy declarativa
Sem heurísticas escondidas no código. Toda decisão de "o que recuperar" é declarativa, versionada e auditável.
precedence: - authority # ADR aprovado > spec draft - recency # menor decay rate por domínio - proximity # entidade no contexto atual - citation_count # quantas vezes referenciado conflict_resolution: strategy: explicit on_conflict: surface_both_with_provenance never: silent_majority_wins
Drift detector contextual
Detecta quando o contexto recuperado começa a divergir do estado real do sistema. Previne respostas baseadas em memória obsoleta.
- • Schema drift: mudança em entidades canônicas dispara re-index.
- • Authority drift: ADR superseded → invalidação de respostas em cache.
- • Behavioral drift: queda de groundedness em runs sucessivas.
- • Time drift: claims com freshness expirada são marcadas como "stale evidence".
22 KPIs cognitivos em 5 camadas
SLOs por domínio + camada FinOps explícita. Dashboard "Knowledge Vital Signs" plugado em alerting padrão (Datadog / Grafana).
| Camada | KPI | Definição | SLO sugerido |
|---|---|---|---|
| Substrate | Knowledge Coverage | % de capabilities com pelo menos 1 spec aprovada. | > 90% |
| Source Freshness | Idade média da última atualização de fontes ingeridas. | < 24h | |
| Orphan Rate | % de specs sem requisito ou ADR vinculado. | < 5% | |
| Ingestion Lag | Latência entre evento e disponibilidade no KG. | P95 < 5min | |
| Retrieval | Recall@k | % de docs relevantes nos top-k recuperados. | > 0.85 |
| Precision@k | % dos top-k que são realmente relevantes. | > 0.75 | |
| MRR | Mean Reciprocal Rank — onde está o primeiro relevante. | > 0.7 | |
| Retrieval Latency P95 | Tempo de resposta da camada de retrieval. | < 800ms | |
| Citation Reachability | % de citações que apontam para fonte viva. | > 99% | |
| Reasoning | Groundedness | % da resposta suportada por evidência citada. | > 0.9 |
| Faithfulness | Resposta não introduz fatos fora do contexto recuperado. | > 0.95 | |
| Answer Relevance | Resposta endereça a pergunta feita. | > 0.85 | |
| Hallucination Rate | % de respostas com claim sem suporte. | < 2% | |
| Escalation Rate | % de queries que requerem intervenção humana. | 10–25% (saudável) | |
| Outcome | Time-to-Decision | Tempo médio de pergunta a decisão acionável. | −60% vs baseline |
| Reuse Index | Quantas vezes uma spec é citada por outra. | > 3x trimestre | |
| Lineage Depth | Profundidade média do grafo requisito → telemetria. | > 5 níveis | |
| Audit Time | Tempo para gerar evidência de compliance. | < 1h | |
| FinOps | Cost per Query (USD) | Custo médio (LLM + retrieval) por pergunta resolvida. | Tendência mensal ↓ |
| Token Burn Rate | Tokens consumidos por agente / dia. | Dentro do budget mensal | |
| Hard Escalations / semana | Acionamentos do Circuit Breaker (limite de tentativas). | < 5% das execuções | |
| Budget Utilization | % do budget mensal consumido. | Alertas em 70% / 90% / 100% |
Tracing semântico ponta-a-ponta
OpenTelemetry instrumentando agentes, retrieval e LLMs. Cada span carrega:
- trace.id — ponta-a-ponta da query
- retrieval.policy — versão da política aplicada
- grounding.score — confidence do reasoning
- citations[] — IDs e versões das fontes
- model.id + prompt.hash
- cost.tokens + cost.usd
- decision.gate — quais quality gates passaram
- human.in.loop — escalation se aplicável
Adoção em 4 fases incrementais
Cada fase tem critérios objetivos de saída. Sem milestone sem evidência mensurável.
Fase 1 — Foundation
0–90 dias Quick winsEstabelecer substrate, ontologia base e primeiros agentes read-only.
Entregas
- • Docusaurus + OpenKB integrados
- • Core ontology v1 (10–15 entidades canônicas)
- • Ingestão de specs e ADRs existentes
- • GraphRAG read-only para 1 domínio piloto
- • 5 KPIs cognitivos baseline
Critérios de saída
- ✓ Knowledge Coverage > 60% no domínio piloto
- ✓ Recall@10 > 0.75 em benchmark interno
- ✓ Knowledge Council operando
- ✓ NPS interno > 40 entre engenheiros
Fase 2 — Pilot Cognitive
3–6 mesesLoop cognitivo completo, quality gates e primeiras ações automatizadas com human-in-the-loop.
Entregas
- • Agentes com loop SENSE→...→LEARN completo
- • Quality gates (groundedness, faithfulness)
- • PR check com revisão assistida de drift de contrato (HITL)
- • Tracing OTel completo
- • Dashboard "Knowledge Vital Signs"
Critérios de saída
- ✓ Groundedness > 0.85 em produção
- ✓ Hallucination rate < 5%
- ✓ Time-to-Decision −30% vs baseline
- ✓ Pelo menos 1 incidente resolvido com lineage
Fase 3 — Federate
6–12 mesesKnowledge Mesh: domain extensions, contract testing semântico, escalonamento para 3+ domínios.
Entregas
- • Federated query com policy enforcement
- • Contract tests entre domínios em CI
- • Domain Owners + Stewards estabelecidos
- • Self-service de onboarding de domínio
Critérios de saída
- ✓ 3+ domínios em produção sem coordenação central
- ✓ Reuse Index > 3x
- ✓ Audit Time < 4h
- ✓ Drift entre domínios < 1% por trimestre
Fase 4 — Autonomous
12–24 mesesAgentes com authority delegada (write actions), self-healing, learning loops fechados — operando dentro de Circuit Breakers configurados.
Entregas
- • Write agents (PR autoral, ADR auto-publicada)
- • Self-healing em retrieval e reasoning
- • Closed-loop learning com feedback do usuário
- • Marketplace interno de agentes/skills
Critérios de saída
- ✓ Time-to-Decision −60% vs baseline
- ✓ > 30% de PRs com contribuição cognitiva
- ✓ Auditoria regulatória passada com lineage
- ✓ Conhecimento operando como produto
Circuit Breaker ativo nesta fase
Agentes autônomos operam com janela de 3 tentativas. Na quarta, o sistema escala para revisão humana e registra o evento para auditoria FinOps. Sem budget configurado, esta fase não é habilitada. Detalhes em Segurança & FinOps.
Anti-padrões a evitar
- Big bang ontológico — desenhar a ontologia perfeita antes de qualquer entrega.
- Agente sem human-in-the-loop em fase 1–2.
- RAG sem citação obrigatória — vira gerador de plausibilidade.
- "Vamos depois adicionar governança" — débito ontológico é exponencial.
- Centralização tardia — quando 5 domínios já divergiram, a fusão custa caro.
Princípios não-negociáveis
- No claim without citation.
- Specs are versioned, deprecation is explicit.
- Every agent action is traceable end-to-end.
- Quality gates fail closed, not open.
- Domain owns its semantics, platform owns its substrate.
O que muda quando o conhecimento é um sistema operativo
A versão original era uma stack. Esta versão é uma plataforma: tem usuários, SLOs, contratos, governança e roadmap auditável. Mais importante — ela trata o conhecimento como produto interno, não como subproduto da entrega.
Da documentação
para specs versionadas, citáveis, executáveis.
Do search
para retrieval governado, com policy declarativa e lineage.
Do chatbot
para agentes com loop cognitivo, quality gates e tracing.
Da IA sem teto
para Circuit Breakers cognitivos com FinOps integrado.
Da governança punitiva
para Índice de Reuso que recompensa documentar bem.
Do jargão técnico
para Âncoras de Valor — toda camada técnica explicada para o board.
"Conhecimento que não é executável vira folclore. Folclore que governa decisões é dívida estratégica."
Próximo passo
Esta especificação está pronta para um workshop de 90 minutos com arquitetura, plataforma e domínio piloto. Saída: backlog priorizado para a Fase 1 — Foundation.