Base de conhecimento derivada: o que todo arquiteto de Agentforce devia estar montando agora
Um método simples com Claude Code mostra como parar de repetir o mesmo raciocínio caro toda vez que um agente ou uma pessoa nova precisa entender seu contexto de projeto
Salesforce Engineering publicou um jeito prático de usar Claude para transformar documentação espalhada em uma base de conhecimento cruzada, em Markdown, que tanto humanos quanto agentes conseguem consultar sem reprocessar tudo do zero. Isso tem tudo a ver com o que a gente enfrenta em projeto de Agentforce e Data Cloud.
O problema que todo projeto de Agentforce esconde
Quantas vezes você já viu um cliente querer subir um agente de Agentforce e, na primeira reunião de descoberta, perceber que a documentação de processo está espalhada em quinze Google Docs, três threads de Slack e a cabeça de duas pessoas que já saíram da empresa? Isso não é exceção, é a regra. Todo arquiteto que já fez discovery de verdade conhece essa cena, e é exatamente o problema que o time de Agentic Search do Salesforce Engineering resolveu atacar com uma solução deliberadamente simples: nada de vector database, nada de grafo de conhecimento com ontologia rígida. Só Markdown, pastas e um agente Claude fazendo o trabalho pesado de leitura e síntese.
Derived Knowledge Base: a ideia central
O conceito é batizado de Derived Knowledge Base. Você aponta o Claude para os seus documentos brutos (design docs, propostas de iniciativa, threads de Slack, o que for) e ele lê, entende e escreve notas derivadas, curtas, interligadas por conceito e por pessoa.
O ponto chave é a separação de responsabilidade. Os documentos originais ficam intocados em uma pasta Sources/, e o agente escreve e reescreve continuamente as notas em Concepts/ e People/, criando cross-links no formato [[conceito]]. Cada nota de conceito vira uma unidade de conhecimento com uma seção de fontes, permitindo rastrear de onde aquela informação veio, mesmo quando fontes mais novas contradizem as antigas.
Isso resolve, na prática, o que toda base de conhecimento corporativa tenta e falha em resolver: manter rastreabilidade sem transformar a manutenção da própria base em um segundo projeto.
A justificativa importa mais que a arquitetura
O que me chamou atenção não foi a arquitetura técnica (é literalmente pasta e arquivo texto), mas a justificativa por trás dela. O time cita o bitter lesson de Richard Sutton: estruturas rígidas de organização, tags e ontologias definidas na força bruta tendem a virar mais um artefato para manter, e acabam ficando desatualizadas tão rápido quanto a documentação que elas tentam organizar. Prosa em linguagem natural carrega nuance que taxonomia fixa não carrega, e é justamente essa nuance que um agente precisa para raciocinar sobre contexto de projeto sem repetir, do zero, o mesmo trabalho de investigação toda vez que alguém (humano ou agente) pergunta "como funciona X aqui".
Isso conversa direto com o que a gente vive todo dia em projeto Salesforce. Quantas vezes o mesmo raciocínio caro (entender por que uma automação foi desenhada de um jeito específico, por que aquela regra de negócio existe, quem tomou a decisão e com base em quê) é refeito porque a explicação nunca foi capturada em um lugar vivo, só documentada uma vez e esquecida em um Confluence que ninguém mais abre?
O que isso muda para arquitetura de Agentforce
Se você está desenhando agentes que precisam de contexto de projeto (não só de dados transacionais, mas de decisões, histórico e trade-offs), vale considerar esse padrão como camada complementar ao seu modelo de dados tradicional:
- Fontes brutas permanecem imutáveis e auditáveis, sem virar gargalo de governança
- O agente assume o trabalho de síntese, não de arquivamento, o que é uma inversão útil de responsabilidade
- Cross-links por conceito criam uma malha de conhecimento que cresce organicamente, sem exigir modelagem antecipada de ontologia
- Contradições entre fontes antigas e novas ficam visíveis, em vez de mascaradas por uma única "verdade" congelada
Nada disso substitui Data Cloud, Knowledge ou os mecanismos de grounding que a gente já usa em Agentforce. Mas resolve uma lacuna real: o conhecimento de por que as coisas são como são, que normalmente vive na cabeça de arquiteto sênior e desaparece quando ele sai do projeto.
Estrutura rígida demais para o que é, por natureza, orgânico e mutável tende a custar mais para manter do que o problema que resolve.
Vale a leitura completa do post original no Salesforce Engineering Blog para quem quer entender os detalhes de implementação com Claude Code. Mas o recado arquitetural já está dado: pare de tratar documentação de projeto como artefato estático. Trate como base viva, que se atualiza com o mesmo esforço de leitura que você já faz todo dia.
Todo projeto Salesforce acumula um tipo de conhecimento que nunca vira artefato: o raciocínio por trás das decisões. Por que esse objeto foi modelado assim, por que aquela automação existe, por que o time descartou uma abordagem óbvia em favor de outra mais complexa. Isso mora na cabeça de quem arquitetou e evapora quando a pessoa sai do projeto ou quando um agente precisa "entender" o contexto para agir com autonomia.
Com Agentforce, esse problema deixa de ser só organizacional e vira arquitetural. Um agente que consulta seu org sem uma base de conhecimento derivada e bem estruturada vai reconstruir esse raciocínio do zero a cada interação, gastando tokens, tempo e previsibilidade para chegar em conclusões que já deveriam estar documentadas. Isso não escala e custa caro, literalmente.
O método com Claude Code é relevante porque ataca a causa, não o sintoma: em vez de pedir para o agente inferir contexto toda vez, você constrói uma camada de conhecimento derivada, versionada e reutilizável, tanto para humanos quanto para agentes consumirem.
- Onboarding deixa de depender de tribal knowledge e passa a ter uma fonte estruturada e consultável.
- Agentes ficam mais previsíveis porque operam sobre contexto explícito, não sobre inferência recalculada a cada prompt.
- Decisões arquiteturais viram documentação viva, não tribal knowledge perdido em threads de Slack ou na memória de quem já saiu do projeto.
Para arquitetos, isso é infraestrutura de decisão. Quem não montar essa base agora vai continuar pagando o mesmo raciocínio caro repetidas vezes, só que agora multiplicado pela escala dos agentes que estão sendo construídos em cima do seu org.
Todo projeto de Salesforce carrega uma base de conhecimento invisível que existe só na cabeça de duas ou três pessoas. Você já viu esse filme: alguém novo entra no time, ou você tenta plugar um agente de Agentforce numa automação, e a primeira pergunta é sempre a mesma. "Por que isso foi feito assim?" A resposta normalmente exige uma arqueologia de threads no Slack, decisões antigas de sprint e um arquiteto cansado repetindo o mesmo raciocínio pela enésima vez.
O que o post descreve com Claude Code é basicamente disciplina aplicada a um problema que a gente sempre tratou como custo inevitável. Documentação derivada, gerada a partir do próprio código e das decisões reais do projeto, não é novidade como conceito. A diferença é que agora existe ferramenta madura o suficiente para manter isso vivo sem virar um projeto paralelo de manutenção que ninguém prioriza.
Para quem arquiteta soluções com Agentforce, isso deixa de ser luxo de time maduro e vira pré-requisito. Um agente que precisa tomar decisão contextualizada não pode depender de prompt engineering heroico toda vez. Ele precisa de uma base estruturada, versionada, que reflita o estado real do projeto e não a intenção original que morreu há três sprints.
Minha ressalva é a de sempre: método bom sem prática vira slide bonito. A pergunta que fica é se times vão de fato instituir esse hábito de manter a base viva, ou se vai ser mais um artefato criado com entusiasmo no início do projeto e abandonado no primeiro sprint apertado. Arquitetura de conhecimento exige a mesma governança que arquitetura de dados. Sem isso, você só trocou o raciocínio caro repetido por humano pelo raciocínio caro repetido por agente.
Não espere ter tempo livre para documentar. Isso nunca vai acontecer. O jeito é transformar a documentação em subproduto do trabalho que você já faz.
- Escolha um projeto real em andamento, de preferência um que tenha decisões arquiteturais que você já explicou verbalmente mais de uma vez (por que optou por Data Cloud em vez de integração direta, por que o agente usa determinado modelo de raciocínio, por que a topic foi desenhada daquele jeito).
- Peça para o Claude Code (ou assistente equivalente) observar seu processo enquanto você resolve um problema específico do projeto. Não peça um resumo genérico. Peça que ele registre o raciocínio, as alternativas descartadas e o motivo de cada decisão técnica.
- Transforme esse output em artefato versionado, não em conversa perdida no histórico do chat. Salve como markdown no repositório do projeto, junto com o código e as configs do agente. Isso já é meio caminho andado para virar contexto reaproveitável por outro humano ou por outro agente.
- Separe decisão de implementação. Documentação técnica de "como configurar" já existe em abundância. O que falta é o "por que decidimos assim", que é exatamente o que se perde quando a pessoa que decidiu sai do projeto ou o agente perde contexto de sessão.
- Repita o processo a cada decisão arquitetural relevante, não só no fechamento do projeto. Base de conhecimento derivada não é documentação retroativa, é captura contínua enquanto o raciocínio ainda está fresco.
- Use esse acervo para onboarding, tanto de gente quanto de agente. Se um novo arquiteto ou uma nova instância de Agentforce consegue entender o contexto do projeto lendo esse material, em vez de te interromper de novo, você provou que o método funciona.
O ganho real aqui não é ter "mais documentação". É parar de pagar o mesmo custo cognitivo toda vez que alguém, humano ou agente, precisa entender o que você já resolveu na cabeça meses atrás.
- Base derivada só funciona se alguém assumir a curadoria contínua. Sem dono definido, ela vira mais um artefato abandonado depois da euforia inicial.
- Gerar documentação com Claude Code a partir do histórico de decisões exige que esse histórico exista de forma minimamente estruturada. Se seu repositório de commits, PRs e discussões é bagunçado, o modelo vai sintetizar bagunça com aparência de organização.
- Existe um risco real de a base derivada capturar o raciocínio errado de forma tão bem escrita que ninguém questiona depois. Clareza não é sinônimo de acerto arquitetural.
- Agentes e pessoas novas vão confiar no que está documentado. Se a base não é atualizada quando a arquitetura muda, você cria uma fonte de verdade que mente com convicção.
- O método reduz retrabalho de raciocínio, mas não substitui revisão humana de decisões críticas de arquitetura. Automatizar a captura de contexto não é o mesmo que automatizar o julgamento sobre esse contexto.
- Times que tratam isso como projeto pontual em vez de prática recorrente vão ver o valor cair rápido. Base de conhecimento derivada é processo, não entregável único.
- Em ambientes com múltiplos agentes Agentforce operando em paralelo, inconsistência entre bases derivadas de diferentes squads pode gerar decisões conflitantes que ninguém percebe até dar problema em produção.
Este conteúdo foi reescrito e analisado editorialmente em português a partir de informações públicas da fonte indicada.