Texto puro vence: construa um wiki apoiado em Git em que seus agentes de IA e engenheiros confiem

Você não tem um problema de alucinação. Você tem um problema de documentação. Se o seu conhecimento operacional vive espalhado por Notion, Confluence, threads no Slack, Google Docs e cinco wikis de fornecedores, seus agentes (e seus novos contratados) estão brincando de telefone sem fio. O resultado: resposta a incidentes lenta, automações instáveis e uma desconfiança crescente em relação à IA dentro de engenharia.

Existe uma solução sem glamour, rápida e que funciona: um wiki em texto puro, apoiado em Git, que humanos e agentes leem e escrevem. Inspirado pelo burburinho recente da comunidade sobre wikis de LLM no estilo Karpathy e pelo lembrete de que texto puro perdura, isso não é nostalgia. É uma decisão que otimiza para auditabilidade, latência e custo — exatamente o que uma stack de IA em produção precisa.

Por que texto puro + Git vence a sua atual proliferação

• Auditabilidade que você já domina: PRs, diffs, CODEOWNERS e reviews são memória muscular para o seu time. “Docs as code” dá a você proveniência e controle de mudanças sem comprar outra ferramenta.
• Compatível com LLM por padrão: Markdown é amigável em tokens, fácil de fragmentar e comprime bem. Você pode alimentá-lo em RAG sem brigar com formatos proprietários ou conectores frágeis.
• Barato e rápido: Um índice vetorial com 100k chunks (768-dim float32) tem cerca de 300 MB de vetores mais a sobrecarga do índice — chame de menos de 500 MB. Armazenamentos vetoriais modernos retornam top-k em menos de 50 ms nessa escala.
• Durabilidade offline-first: Se seus fornecedores limitarem APIs ou mudarem formatos, seu conhecimento ainda “compila”. Espelhos Git e snapshots em S3 sobrevivem a ferramentas e organogramas.

Um framework de decisão para CTOs: um wiki apoiado em Git e legível por agentes

1) Escopo: o que entra (e o que não entra)

• Dentro: Visões gerais de arquitetura, runbooks, playbooks, contratos de serviço, especificações de API, FAQs de produto, checklists de onboarding, docs de CI/CD, inventários de shadow IT, limites de fornecedores e SLAs.
• Fora: Segredos, credenciais, PII de clientes e logs sem mascaramento. Nem discuta. Seu wiki é para referência e raciocínio, não para chaves ou dados brutos.
• Classificação: Aplique uma simples tag de triagem no front matter — verde (público-interno), âmbar (restrito-interno), vermelho (vai para outro lugar). Agentes nunca veem vermelho. Âmbar é controlado por diretório.

2) Topologia do repositório e metadados

• Um repositório kb por unidade de negócio (ou um único mono-kb se você tiver menos de 100 engenheiros). Fragmentar demais mata a descoberta; fragmentar de menos sobrecarrega os responsáveis.
• Layout de pastas por domínio: platform/, app/, data/, sec/, ops/, product/. Dentro de cada um, pastas por serviço com um esqueleto padrão: overview.md, runbook.md, metrics.md, limits.md, faq.md.
• Front matter: Title, tags, owners (handles do Git), last_verified_at, TTL_days, sensitivity. Seu CI pode impor a presença e a atualidade desses campos.

3) Contribuição e revisão

• Só via PR: Humanos e agentes propõem mudanças via PR. Nada de commits diretos em main. Exija pelo menos uma aprovação humana para qualquer alteração em runbooks ou limites.
• Checks de CI: Lint de Markdown, verificação ortográfica, checagem de links quebrados, scan básico de regex para PII e um job de “frescor de documento” que sinaliza last_verified_at desatualizado. Falhe o build em caso de alertas vermelhos.
• SLA por tier: PRs de Tier 0 (incidentes, segurança) têm alvo de review em 4 horas; Tier 1 (críticos ao produto) em 24 horas; Tier 2 semanal.

4) Armazenamento e indexação: o híbrido vence o vetorial puro

• Primário: GitHub ou GitLab com branches protegidos, espelhados para S3 diariamente. Mantenha o repositório do wiki desacoplado dos seus repos de código.
• Busca: Use um índice híbrido: um índice invertido (OpenSearch, Meilisearch) para lookup exato mais um store vetorial (Qdrant, Weaviate) para semântica. Mescle os scores em tempo de consulta para o melhor dos dois mundos.
• Ingestão: Observe diffs do Git; fragmente o Markdown alterado em blocos de 300–500 tokens com 10–15% de sobreposição; gere embeddings e faça upsert. Isso evita reindexar o mundo a cada commit.

5) Interface dos agentes: ler, citar e escrever como engenheiro

• Política de retrieval: Top-k=8 candidatos híbridos, depois reordene com cross-encoder para 3–5 trechos. Force os agentes a citar caminhos de arquivo e intervalos de linhas nas respostas. Registre as citações.
• Atualizações via PRs: Quando um agente detectar deriva (por exemplo, um 429 de uma API de fornecedor contradizendo limites documentados), ele abre um PR com um diff mínimo e links para as evidências. Humanos revisam; o CI aplica frescor.
• Higiene de memória: Dê aos agentes um scratchpad de curto prazo (Redis com TTL de 24–72 horas) para contexto efêmero. Memória durável vive no Git após review.

6) Identidade, permissões e raio de impacto

• AuthN/AuthZ: SSO via OIDC no seu provedor Git; CODEOWNERS para portões por domínio; branches protegidos para main; bots com escopo apenas nos repos kb.
• Acesso por diretório, não por arquivo, para manter a complexidade tolerável. Se você precisa de ACL por documento, o seu problema é classificação, não ferramenta.
• RBAC para agentes: Contas de serviço separadas por agente, com escrita limitada a branches de rascunho. Todo PR de agente se rotula com o workflow chamador e o ID de execução.

7) Ferramental para humanos e máquinas

• Markdown (GFM) com headings, tabelas e diagramas mermaid. Evite embeds proprietários. Mantenha imagens ao lado dos docs com texto alternativo descritivo para ajudar pipelines de OCR/LLM.
• Site estático para humanos: Docusaurus ou MkDocs-Material publicados em um domínio interno. Rápido, pesquisável e versionado.
• Disciplina de diagramas: Prefira diagramas baseados em texto versionados no Git em vez de exports PNG. Agentes conseguem fazer diff e atualizar texto; eles não editam sua captura de tela.

8) Qualidade, detecção de deriva e telemetria

• Métrica de cobertura: Acompanhe a “cobertura de conhecimento” como (# de serviços Tier 0/1 com runbooks e limites atuais) dividido pelo total de serviços Tier 0/1. Mire 90%+ em 60 dias.
• Sondas automatizadas de deriva: Jobs leves que consultam APIs críticas de fornecedores por limites/endpoints e comparam com os docs. Abra um PR quando divergirem além de um limiar (por exemplo, 10%).
• Analytics de busca: Registre consultas fracassadas e buscas sem resultado no site estático e na camada de agentes; transforme as top 20 em docs a cada sprint.

9) Custo e desempenho: números que você defende

• Exemplo de escala: 5.000 páginas Markdown com média de 800 tokens, fragmentadas em blocos de 400 tokens ≈ 10.000 chunks.
• Armazenamento: 10.000 vetores × 3 KB ≈ 30 MB de vetores; com índice HNSW e metadados, reserve 100–150 MB.
• Latência: Busca híbrida em 10–100k chunks normalmente retorna em 30–70 ms em hardware comum. Rerank adiciona 10–25 ms de CPU. RAG fim a fim abaixo de 200 ms é alcançável on‑prem.
• Custo de embedding: Se você hospedar um modelo de embedding pequeno, uma GPU classe T4 consegue embedar 10–20k chunks em minutos; somente CPU é mais lento, mas barato para jobs noturnos. Embeddings gerenciados custam de centavos a dólares por reindexação — ainda negligenciável nessa escala.

Uma arquitetura de referência pragmática

• Authoring: Repositório GitHub/GitLab (kb) → PRs (humanos + agentes) → CI (lint, scan de PII, frescor, links quebrados) → main protegida.
• Publicar: Build de site estático para domínio interno com busca por palavra‑chave embutida.
• Indexar: Serviço de ingestão observa diffs do repo → fragmenta/normaliza → gera embeddings → upsert para Qdrant (semântico) e OpenSearch (lexical).
• Servir: API de retrieval combina lexical + vetorial → rerank opcional → retorna trechos ranqueados + citações → consumidores agente/humano.
• Governar: Sondas de deriva + analytics de busca → PRs para fechar gaps → dashboards de cobertura/frescor.

Segurança e compliance: propositalmente sem glamour

• Nenhum segredo no wiki. Trate conhecimento classificado como vermelho como não‑wiki e aponte para seu cofre ou sistema de tickets.
• Guardrails de PII: Regexes no CI pegam vazamentos óbvios; scans periódicos de DLP capturam o resto. Falhe o build em caso de ocorrências.
• Backups: Espelho noturno em S3 com retenção imutável e replicação entre regiões. Teste restaurações trimestralmente.
• Retenções legais: Etiquete commits associados a investigações; evite garbage collection de branches relacionados.

Falhas comuns (e como evitá‑las)

• Deixar agentes fazer commit em main: Faça toda mudança de agente passar por PR com revisão humana. Isso preserva a confiança.
• Tentar modelar permissões no nível de arquivo: É uma armadilha. Use escopo por diretório e classifique melhor.
• “Vamos sincronizar do Notion depois”: Conectores degradam e impõem rate limits. Migre documentos críticos para Markdown agora; deixe um banner de descontinuação lá.
• Diagramas somente binários e PDFs: Se um LLM não consegue fazer diff, não consegue manter. Prefira ativos texto‑primeiro. Rode OCR em PDFs legados e anote com texto alternativo.
• Indexar cada commit globalmente: Observe diffs; só re‑embed chunks alterados. Isso mantém custo e latência previsíveis.

Um rollout 30‑60‑90 dias que não vai descarrilar a entrega

Dias 0–30: Levante a espinha dorsal

• Crie repo(s) kb, escolha o gerador de site estático, aplique checks de CI (lint, scan de PII, frescor) e defina front matter e esqueleto de pastas.
• Instrumente a busca híbrida (OpenSearch + Qdrant) e uma API simples de retrieval. Não superotimize o ranking ainda.
• Migre runbooks e limites de Tier 0 para seus top 10 serviços. Nomeie responsáveis e defina SLAs.

Dias 31–60: Conecte agentes e detecção de deriva

• Habilite “PRs de agente” com uma conta de bot de escopo limitado. Exija citações para qualquer mudança escrita por agente.
• Adicione sondas de deriva para duas dependências externas (por exemplo, limites do provedor de auth, paginação da API de billing). Conecte as sondas para abrir PRs automaticamente em caso de divergência.
• Publique dashboards de uso: % de cobertura, % de frescor, top buscas fracassadas.

Dias 61–90: Escale e fortaleça

• Expanda para serviços de Tier 1 e docs de plataforma. Mire 90% de cobertura em Tier 0/1.
• Adicione reranking e ajuste os pesos de blending. Busque retrieval fim a fim abaixo de 200 ms.
• Rode um exercício de red team: tente inserir PII no wiki e burlar o CI. Corrija os achados.

Onde times nearshore ajudam (e onde não)

Se você está sem capacidade, um time nearshore disciplinado pode dar o pontapé inicial nisso sem sequestrar seu roadmap. No Brazil você tem 6–8 horas de sobreposição com os fusos dos EUA, workflows nativos de Git e engenheiros que vivem em CI. Eles são úteis para o trabalho sem glamour: migração de docs, encanamento de CI, sondas de deriva e pipelines de indexação. Mantenha a propriedade e a revisão com seus líderes de domínio; não terceirize a voz dos seus runbooks.

Quando não fazer isso

• Se 90% do seu conhecimento são capturas de tela e PDFs de fornecedores e você não consegue se comprometer com texto‑primeiro daqui em diante, você vai nadar contra a maré. Resolva isso antes.
• Se você não tem cultura de revisão, um wiki em Git vira cemitério tão rápido quanto seu Notion virou. Designe responsáveis e aplique SLAs.
• Se sua principal restrição é acesso a documentos dirigido por compliance em nível por usuário e por arquivo, aceite um CMS mais pesado com ACL por documento e integre com agentes com cautela.

O ponto estratégico: unificar a verdade humana e a verdade dos agentes

A maioria das equipes constrói, sem querer, dois grafos de conhecimento: um para pessoas (páginas bonitas) e outro para máquinas (índices e prompts). É daí que nascem alucinações e deriva. Um wiki em texto puro, apoiado em Git, colapsa essa distância. Humanos propõem e revisam; agentes citam e abrem PR. Todos veem a mesma verdade, com os mesmos guardrails, usando o mesmo workflow que você já confia para código.

Principais lições

• Texto puro + Git dá auditabilidade, velocidade e compatibilidade com LLM sem comprar outra plataforma.
• Mantenha segredos e PII fora; classifique docs e restrinja por diretório com CODEOWNERS e branches protegidos.
• Use uma stack de busca híbrida (lexical + vetorial) alimentada por um pipeline de ingestão atento a diffs; busque retrieval abaixo de 200 ms.
• Force agentes a citar fontes e enviar PRs; nunca deixe que façam commit em main.
• Meça cobertura e frescor, adicione sondas de deriva e transforme buscas fracassadas em docs a cada sprint.
• Comece com runbooks e limites de Tier 0; atinja 90% de cobertura em 60–90 dias sem descarrilar a entrega.