Pitch: Loro Knowledge Studio: um acervo de contexto em markdown e git, e o processo de trabalho que ele viabiliza · aipi

Nosso limite cognitivo não acompanha a produtividade e a quantidade de memória que um datacenter armazena. Devemos nos proteger de algo que chamo de "Buraco de IA". Como ideias são baratas, e rompemos a barreira do código, produzir se tornou barato. Mas 99% do que pensamos é baseado nas nossas emoções a partir do nosso cotidiano. Nossos pensamentos não são fatos, são só pensamentos. Precisamos filtrar o que realmente importa. E responder a mesma velocidade que pensamos deixa pontas soltas e chegamos num buraco que gera um desgaste físico e mental. Devemos colocar um limite nisso.

Toda reunião tem um intervalo que ninguém mede: o tempo entre a coisa importante ser dita e ela virar documento. Nesse intervalo o conteúdo não é perdido por falta de ferramenta, é perdido por falta de estrutura para receber. Depois pedimos para a IA construir sobre o vazio e reclamamos do resultado.

Passei semanas atacando isso e saíram duas coisas. Uma é técnica: se o conhecimento da empresa mora em markdown versionado, o agente não precisa de integração nenhuma — o sistema de arquivos já é a API. A outra é um processo de trabalho que só existe porque a primeira existe: quatro pessoas numa videoconferência, e o resultado sólido saindo enquanto a conversa acontece.

Chamo isso de Knowledge Studio, e vou definir o nome antes de usá-lo, porque nome sem definição é marketing.

O que é um Knowledge Studio

Um repositório de conhecimento que satisfaz três propriedades. Não é um wiki, não é um data lake, não é um "segundo cérebro". É um wrapper ao seu harness. Uma espécie de IDE de contexto.

Fonte única da verdade legível por pessoa e por máquina sem tradução. O que eu leio no editor é literalmente o que entra no contexto do modelo. Sem chunk, sem embedding, sem camada intermediária que eu não consigo auditar.
Evolução por revisão, não por escrita livre. Mudar o conhecimento é abrir pull request. Quem aprova está no CODEOWNERS. Wiki que qualquer um edita e ninguém revisa não é fonte da verdade, é rascunho compartilhado.
Estúdio, não arquivo. É lugar de produzir, não de guardar. O acervo existe para que dali saia apresentação, planilha, especificação, proposta — inclusive durante a reunião que está gerando o material.

A terceira propriedade é a que justifica a palavra "studio", e é a que muda o processo de trabalho. Volto nela no fim.

O que não usei

Nada de banco vetorial, embeddings, RAG, servidor ou schema. A stack é: markdown, git e um agente de linha de comando. Essa escolha não é minimalismo estético, ela tem três consequências práticas:

Diff legível. Mudança de conhecimento aparece como diff de texto. Um git log conta a história intelectual do domínio.
Revisão que já existe. Pull request, CODEOWNERS, aprovação. Não precisei inventar workflow de governança, herdei o do GitHub.
Zero infraestrutura para manter. O acervo é uma pasta. Roda no notebook, sobrevive a mudança de stack e não depende de nenhum fornecedor continuar existindo.

Anatomia do acervo

acervo/
├── AGENTS.md              # as regras do loop — o "prompt de sistema" versionado
├── INDEX.md               # mapa, regenerado pelo agente
├── inbox/                 # entrada crua: transcrições, notas, .txt, .pptx
├── processed/             # cru já consumido (nunca apagado)
├── reunioes/  notas/      # registro estruturado, fonte efêmera
├── contextos/<dominio>/
│   ├── context.md         # FONTE OFICIAL DA VERDADE
│   ├── CHANGELOG.md       # histórico datado, append-only
│   └── anexos/            # artefatos gerados
├── .github/CODEOWNERS     # quem aprova mudança em cada contexto
└── .brain/state.json      # o que já foi processado (idempotência)

O context.md tem seções fixas e numeradas: 0 Sumário · 1 Visão geral · 2 Como funciona · 3 Fluxos principais · 4 Quem participa e sistemas · 5 Decisões e fatos · 6 Hotspots. Títulos fixos não são burocracia, são contrato de parsing: o agente sabe onde escrever sem precisar interpretar a estrutura, e um grep sabe onde procurar.

O modelo é DDD (mas o documento não fala DDD)

A pasta se chama contextos/ de propósito. Cada diretório é um subdomínio com sua própria fonte da verdade, e o desenho todo vem emprestado do Domain-Driven Design:

Um context.md por subdomínio, não um wiki por área. A fronteira é o domínio de negócio, não o organograma. Isso importa porque organograma muda a cada trimestre e domínio, não.
Linguagem ubíqua. O context.md é escrito com as palavras que o negócio usa. Se o time fala "caução", o documento fala caução, e o código deveria falar também. É esse arquivo que expõe divergência de vocabulário entre áreas, que é onde nascem metade dos bugs de integração.
Decomposição recursiva quando o domínio vira composto. A regra do loop é literal: se um domínio virar composto, ele é quebrado em contextos/<dominio>/<sub>/, com a mesma estrutura, e o pai passa a ser overview mais índice. A hierarquia vai até três níveis, cada segmento um slug minúsculo.
Domínio × prática. Há duas naturezas de contexto e o molde é escolhido pelo caminho. Domínio é negócio, o quê. Prática é forma de trabalho, o como, e vive sob engenharia/. Mesmas seções, conteúdo de natureza diferente.
Context map na seção 4. "Quem participa e sistemas" é exatamente o mapa de atores e sistemas que tocam aquele domínio, incluindo as fronteiras com os vizinhos.
Ownership por contexto. CODEOWNERS diz quem aprova mudança em cada subdomínio. Bounded context com dono, não com comitê.

E aqui está a parte contraintuitiva: o AGENTS.md proíbe o documento de usar o vocabulário do DDD. É regra dura. Não pode escrever "DDD", "subdomínio" como jargão de estrutura, "reestruturação", "quebra", "migração". Nada de mecânica interna do acervo.

O motivo é que o leitor do context.md é o negócio. DDD é o modelo que organiza os arquivos, não o assunto do texto. No minuto em que o documento começa a se descrever, ele para de descrever o domínio, e a pessoa de operações que abriu para entender um fluxo desiste na terceira linha. O DDD fica na topologia das pastas, onde ele trabalha calado.

Na mesma linha, participantes são descritos por arquétipo — produto, negócio, engenharia — e não por cargo ou área. Convergência para um resultado, não para uma caixinha.

O mecanismo que faz a coisa funcionar: hotspot

Esse é o detalhe de design de que mais gosto, e o que evita o destino natural de todo wiki.

Ideia não vira arquivo. Nunca. Dúvida em aberto, contradição entre duas fontes, hipótese em estudo: tudo isso é registrado como hotspot dentro da seção 6 do próprio context.md:

> [!HOTSPOT] H-3 — cobrança de multa depois do fim do contrato
> Duas fontes divergem sobre quem responde pela multa.
> Sem decisão registrada.

O que isso resolve:

Não existe pasta de ideias mortas. Você não acumula 400 documentos que ninguém sabe se ainda valem.
A incerteza é endereçável. H-3 é um ID estável, citado no CHANGELOG e no índice. É o começo da próxima reunião, com nome próprio.
Fato e hipótese não se misturam. Seções 1 a 5 são o que está decidido. Seção 6 é o que está em aberto. Uma hipótese só é promovida a fato por RFC aprovada.
Fato e hipótese não se misturam. Seções 1 a 5 são o que está decidido. Seção 6 é o que está em aberto. Uma hipótese só é promovida a fato por RFC aprovada.
Grafo é bonito, mas humanamente inútil. Máquinas lêem grafos, humanos não.
Fato e hipótese não se misturam. Seções 1 a 5 são o que está decidido. Seção 6 é o que está em aberto. Uma hipótese só é promovida a fato por RFC aprovada.

E RFC aqui não é documento: RFC é branch + pull request. A mudança é aplicada direto no context.md, o corpo do PR é a proposta, o CODEOWNERS define quem aprova, e o merge na main é o momento em que a coisa passa a ser verdade oficial. O agente explicitamente não abre PR. Quem propõe é pessoa.

Leitura barata: o problema real é o orçamento de contexto

Aqui é onde a engenharia aparece. Um acervo com dezenas de domínios não cabe em contexto nenhum, e mesmo que caiba, você paga por token e a atenção do modelo degrada. Então a estrutura foi desenhada para que ler seja barato, com um protocolo explícito no AGENTS.md:

Comece pelo INDEX.md e escolha o domínio pela descrição.
Leia o Sumário (§0) do context.md. A maioria das consultas termina aqui.
Localize IDs (D-… para decisões, H-… para hotspots) com grep e leia só a seção necessária.
O arquivo inteiro é o último recurso, não o primeiro.

A linha do índice carrega metadado suficiente para decidir sem abrir nada:

- [vendas](contextos/vendas/context.md) **(4)** — funil, proposta e negociação
  · atualizado 2026-07-29 · hotspots H-1..H-6

Aquele (4) é maturidade, numa escala de 0 vazio a 4 mapeado+revisado. O agente sabe de antemão se está lendo esqueleto ou coisa revisada, e calibra a confiança.

Os IDs de decisão seguem D-AAAA-MM-DD-<slug>, com a data vindo do CHANGELOG que a originou. Regra dura: nunca inventar a data. É a diferença entre um ID que é ponteiro e um ID que é enfeite.

Vale nomear o que isso é: RAG feito com grep. Recuperação hierárquica sobre texto, onde o índice é escrito por humano e a estrutura de subdomínios substitui o embedding. Perde em busca semântica difusa. Ganha em previsibilidade, custo zero de infra e auditabilidade total do que foi lido.

O loop de ingestão

inbox/ ──▶ classifica ──▶ reunioes/ | notas/
                │
                ├──▶ CHANGELOG.md   (append-only)
                ├──▶ context.md      (§1–5 fato · §6 hotspot)
                └──▶ processed/  +  state.json  +  INDEX.md

Detalhes que fazem diferença na prática:

Idempotência por state.json. Uma lista simples de nomes já consumidos. Rodar o loop duas vezes não duplica nada.
Direcionamento explícito por nome de arquivo. vendas--notas-da-call.md vai direto para o contexto vendas, e o prefixo aceita hierarquia (engenharia/frontend--...). Sem prefixo, o agente classifica pelo conteúdo, e se nenhum contexto couber, ele sugere criar um novo em vez de forçar o encaixe. Classificador que nunca diz "não sei" é classificador que mente.
Cru nunca é apagado, só movido para processed/. Se a síntese saiu errada, a fonte está lá.
inbox/_prompt.md como override. Um arquivo opcional que, se existir, é lido antes do processamento padrão. É o jeito de dizer "nessa rodada, preste atenção em X" sem editar as regras permanentes. Ao terminar, ele é arquivado em .brain/prompt-history/ e removido.

Prompt como código

Os comandos vivem em .claude/commands/*.md, um arquivo por operação: /loro-context, /loro-analyse, /loro-artifact, /loro-ask, /loro-digest, /loro-sync. Cada um é markdown com frontmatter:

---
description: Analisa a reunião ao vivo e escreve investigação + relatório
argument-hint: <dir-da-reuniao>
---
Diretório da reunião: `$ARGUMENTS`
...

Consequência: o comportamento do agente está no mesmo git do conhecimento, com o mesmo diff e a mesma revisão. Mudar como o time processa reunião é um PR. Prompt deixa de ser folclore no Notion de alguém.

Todos os comandos terminam com o mesmo bloco de regras de rigor, e as duas mais importantes são:

Nunca assuma premissa não declarada. O que não está na base é incerteza, e incerteza é registrada como hotspot ou como linha de "incertezas" na resposta. É a defesa contra o modo de falha número um de LLM em documentação: preencher lacuna com plausibilidade.
Varredura delegada. Para ler muitos arquivos, delegue a subagentes com modelo rápido, recebendo só o essencial, e reserve o modelo principal para a síntese. Leitura é barata e paralela, síntese é caro e serial.

A parte da reunião ao vivo

É aqui que o "produzir durante a conversa" deixa de ser figura de linguagem.

A captura é local: áudio em .webm, convertido para WAV mono 16 kHz, transcrito por whisper.cpp com modelo GGML em disco (ggml-large-v3-turbo quando há máquina para isso, ggml-small quando não). Nada sai do computador, e isso não é postura de privacidade, é requisito de conseguir ligar a coisa numa conversa com cliente.

O ponto arquitetural é o que acontece com o arquivo. A transcrição é escrita incrementalmente em reuniao.md, dentro do diretório da reunião:

brainstorming/<tema>/reunioes/<id>/
├── reuniao.md          # transcrição AO VIVO, cresce durante a reunião
├── manifest.json       # metadados — escrito pelo APP, atômico
├── relatorio.md        # prosa provisória, reescrita pelo agente
├── marcadores.jsonl    # estatísticas sem PII
├── auditoria.jsonl     # o que o agente leu e escreveu
└── artefatos/
    └── investigacoes/analise-2026-07-27T1430Z.md

Como reuniao.md é só um arquivo que cresce, o agente pode ser invocado no meio da reunião e ler o que já foi dito. Ele não precisa de stream, socket, webhook ou integração com a plataforma de vídeo. Ele faz Read. É a coisa mais banal do artigo e é a que destrava tudo.

E como ele também sabe ler os context.md do acervo, a análise cruza o que está sendo dito agora com o que já era verdade antes: decisão que contradiz decisão anterior, dúvida que já é o hotspot H-4, número que não fecha com o registrado.

Daí sai o artefato ainda com a reunião aberta: a apresentação, a planilha com os números que acabaram de ser citados, a pergunta que ninguém tinha formulado.

Três disciplinas que fizeram isso parar de quebrar:

Ownership de arquivo é explícito. O manifest.json pertence ao app, que o escreve de forma atômica. O agente tem instrução dura de não editá-lo, porque dois escritores no mesmo arquivo durante uma reunião ao vivo é corrida garantida. O agente escreve nos arquivos dele; o app, nos dele.
Estatística separada de conteúdo. marcadores.jsonl recebe uma linha por evento, e só o tipo e a referência: {"tipo":"decisao","ref":"artefatos/investigacoes/analise-2026-07-27T1430Z.md"}. Nunca texto de transcrição. Dá para medir a reunião sem vazar a reunião.
Trilha de auditoria orientada a evento. auditoria.jsonl registra o que o agente leu e escreveu, nunca o conteúdo. Quando a síntese sai estranha, você sabe exatamente quais arquivos entraram no contexto.

O processo de trabalho que isso viabiliza

Agora a terceira propriedade, a do estúdio. O que muda quando o acervo é produtivo e não só consultável.

A reunião deixa de ser o lugar onde se combina o trabalho e passa a ser onde parte dele acontece. Quatro pessoas numa videoconferência, cada uma com o agente lendo a transcrição que cresce. Alguém pergunta um número, e ele vem do context.md, com o ID da decisão que o registrou. Alguém propõe algo que contradiz uma decisão de três meses atrás, e a contradição aparece na hora, não no code review de dezembro. A apresentação que ia ser feita amanhã sai antes de a chamada cair.

Somos quase ciborgues. Pensamos junto com a máquina, e o pensamento vira artefato quase no instante em que é dito. Mas repare que a parte ciborgue não é a mais interessante. A mais interessante é que fica registrado: o artefato nasce dentro do acervo, referenciado, com trilha de auditoria, e a dúvida que sobrou virou hotspot com número. Velocidade sem esse registro é só a bagunça andando mais rápido.

Três mudanças de ritual que vêm no pacote, e que são mais difíceis que qualquer decisão técnica aqui:

A pauta da reunião passa a ser a lista de hotspots. Você não abre a chamada perguntando "alguém tem assunto?". Você abre em H-3 e H-6.
Ata deixa de existir. O que sai da reunião é diff no context.md mais artefato em anexos/. Ninguém escreve resumo que ninguém lê.
Mudar o conhecimento passa a exigir aprovação. Isso é atrito de propósito. É o que separa "a gente conversou" de "a gente decidiu".

Se eu tivesse que apostar em como empresas vão trabalhar daqui a alguns anos, apostaria nisso: o repositório de contexto como artefato de primeira classe da empresa, versionado, revisado e com dono, ao lado do repositório de código. Não porque é elegante, mas porque é a única base sobre a qual a IA multiplica eficiência em vez de multiplicar bagunça.

O que não funciona bem, honestamente

Se você for fazer algo parecido, esses são os limites que eu já bati:

Busca semântica não existe. grep não acha o conceito que você não sabe nomear. Índice bem escrito compensa muito, mas não tudo.
Fronteira de subdomínio erra, e errar dói. A parte mais difícil não é técnica, é decidir onde um domínio termina. Quando a divisão sai errada, o mesmo assunto aparece em dois context.md e os dois envelhecem em direções diferentes. É o problema clássico de bounded context, e não tem atalho automático.
Escrita concorrente é um problema real. Duas pessoas processando a inbox ao mesmo tempo geram conflito no context.md. Append-only no CHANGELOG ajuda; regeneração de seção não.
O modelo quer virar fato o que é hipótese. A separação fato/hotspot só se sustenta com regra explícita e repetida em todo comando, e ainda assim vaza. Vale revisar isso no PR.
Reescrever seções 0–5 a cada rodada custa token e ocasionalmente perde nuance que estava bem escrita. O CHANGELOG append-only é a rede de proteção.
O gargalo é cultural, não técnico. A parte de código deu uma semana. Fazer um time trocar ata por pull request de conhecimento é outra escala de problema, e eu não tenho essa parte resolvida.
Gravar reunião é decisão de pessoa, não de arquitetura. Local resolve o problema de dado em nuvem de terceiro; não resolve consentimento de quem está na sala, nem LGPD. Isso é processo, e precisa ser combinado antes.

Resumindo

A ideia que sobra: a IA não cria qualidade do nada, ela multiplica o que existe. Sobre base sólida, multiplica eficiência; sobre base bagunçada, multiplica bagunça mais rápido e mais caro. Garbage in, garbage out voltou a ser a frase mais atual da computação.

E a base sólida, no fim, não exigiu nada de exótico: subdomínios em pastas, markdown com seções fixas, IDs estáveis, git como mecanismo de aprovação, e um protocolo de leitura que faz caber no contexto. O agente não precisou de integração porque o sistema de arquivos já era a integração.

A implementação que usei para testar isso chama-se Loro e é open-source (https://github.com/aipi/loro). Menos como produto, mais como argumento executável.