O problema
Imagina uma operação com dezenas de projetos de e-commerce rodando em paralelo, múltiplas squads, e todo o conhecimento técnico vivendo na cabeça de meia dúzia de pessoas.
Alguém sabia como resolver aquele bug específico do checkout VTEX IO. Outra pessoa tinha descoberto um workaround pra uma limitação do FastStore. Um terceiro tinha criado um componente que todo mundo precisava mas ninguém sabia que existia. E quando qualquer uma dessas pessoas saía de férias, ficava doente ou pedia demissão, o conhecimento ia junto.
Cada projeto novo começava do zero. Os mesmos erros se repetiam. Os mesmos problemas eram resolvidos de novo, por pessoas diferentes, de formas diferentes. O onboarding de um dev novo demorava semanas porque não existia nenhum lugar onde ele pudesse olhar e entender como as coisas funcionavam. A resposta pra quase tudo era “pergunta pro calango”.
Eu via isso acontecer todo dia e pensava: isso não escala. Uma operação desse tamanho não pode depender da memória das pessoas.
O que eu estava vendo (e que ninguém nomeava)
Uma das minhas muitas obsessões é Systems Thinking. E o que eu via na Cadastra era um problema clássico de fluxo de informação - não de pessoas.
Donella Meadows fala de leverage points: pontos onde uma intervenção muda o comportamento do sistema inteiro. Um dos mais poderosos é o fluxo de informação. O problema não é que o conhecimento não existe - ele existe, está sendo gerado todo dia por cada dev que resolve um problema. O problema é que ele não tem caminho pra chegar aonde precisa chegar. O calango que descobriu o workaround sabe dele. O calango do projeto seguinte não. A informação existe no sistema mas está presa - sem canal, sem fluxo, sem estrutura que a transporte.
Se você olha pra conhecimento organizacional como um estoque (no sentido de sistemas dinâmicos), ele tem entradas e saídas. As entradas são tudo que a operação aprende no dia a dia. As saídas são turnover, mudança de tecnologia, memória que se degrada com o tempo. Na maioria das operações, as saídas são automáticas e constantes - gente sai, tecnologia muda, calango esquece. Mas as entradas pro estoque documentado dependem de esforço deliberado. O resultado é previsível: o estoque se esvazia com o tempo. A organização paga pra reaprender o que já sabia.
Os silos de conhecimento que todo mundo reclama não são falha de comunicação - são consequência da estrutura. Se não existe caminho pra o conhecimento do time de VTEX IO chegar ao time de FastStore, o silo não é um bug: é o sistema funcionando exatamente como foi (não) desenhado.
A decisão
Ninguém me pediu pra fazer isso. Não era uma task, não tinha ticket no Jira, não tinha prazo. Eu simplesmente comecei a construir.
A primeira versão era uma pasta com uns markdowns. Depois virou um Astro Starlight com estrutura pensada, hospedado internamente pra empresa. Depois ganhou scripts de automação, pipeline de sync com os projetos, integração com Jira, templates de documentação, e se tornou a referência técnica de muitos na operação.
A arquitetura como intervenção
A estrutura que desenhei não é uma organização de pastas - é uma decisão sobre como conhecimento flui. Cada diretório é um canal:
cadastra-docs/
├── solutions/ # Soluções reutilizáveis (componentes, hooks, integrações)
├── platform/ # Guias por plataforma (VTEX IO, FastStore)
├── projects/ # Implementações documentadas por cliente
├── process/ # Fases, checklists, workflows, experimentos AI
├── troubleshooting/ # Erros conhecidos e soluções
├── templates/ # Templates de documentação
└── scripts/ # Automação (MD→DOCX, sync pipeline, Jira)A organização é por tipo de conhecimento, não por time. Isso é intencional. Se fosse por time (squad-vtex/, squad-faststore/), estaria replicando os silos na documentação. Organizar por solutions/ e platform/ cria caminhos transversais - qualquer dev de qualquer squad encontra o que precisa sem precisar saber quem fez.
Cada solução documentada tem um campo source que linka direto ao código-fonte. Cada projeto tem sua arquitetura, dependências e decisões registradas. Checklists diferenciados para B2B e B2C, pra FastStore e VTEX IO. E a pipeline de sync automática que puxa documentação direto dos repositórios existe por uma razão específica: reduzir a fricção de entrada. Se documentar exige abrir outro sistema, logar em outro lugar, lembrar de fazer - não acontece. Se a documentação é puxada automaticamente do repositório onde o dev já trabalha, a barreira cai.
Nonaka e Takeuchi descrevem quatro movimentos do conhecimento: ele nasce tácito (na cabeça do calango), é externalizado (escrito), combinado (conectado a outros documentos) e internalizado (quando outro calango lê, aplica e desenvolve entendimento próprio). A maioria das bases de conhecimento só suporta a externalização - “escreve aí”. O cadastra-docs foi pensado pra suportar os quatro: templates que facilitam a externalização, a estrutura de diretórios e os links source que fazem a combinação, o formato prático e acionável que facilita a internalização, e a própria existência de um contexto compartilhado que melhora a socialização entre devs.
O que mudou
Antes do cadastra-docs, a resposta pra “como funciona X?” era “pergunta pro calango”. Agora é “olha na docs”.
Projetos novos partem de templates e checklists prontos. Soluções que antes eram reinventadas toda semana agora são encontradas, reutilizadas e evoluídas. O onboarding que levava semanas passou a levar dias. E quando alguém resolve um problema novo, a solução não morre com aquela pessoa - ela vai pra docs.
O que eu não previ foi o efeito composto. Quanto mais gente usa e encontra valor, mais gente contribui de volta. Quanto mais gente contribui, mais a base se torna útil. É um loop de reforço - e uma vez que ele começa a girar no sentido positivo, é difícil de parar. O contrário também é verdade: bases de conhecimento que nascem mal estruturadas entram no loop inverso (ninguém encontra nada → ninguém confia → ninguém contribui → a base apodrece). A diferença entre os dois destinos é estrutural, não motivacional.
A base se tornou tão central que serviu como fundação para o AIvengers Initiative - os 28 documentos técnicos do experimento nasceram ali. Sem a infraestrutura de documentação, aquele experimento simplesmente não teria acontecido. Esse é talvez o melhor exemplo do que significa construir infraestrutura de conhecimento: ela viabiliza coisas que não existiriam sem ela - coisas que você não consegue nem imaginar no momento em que está construindo.
Tecnologias
- Astro Starlight - site de documentação auto-gerado
- Node.js - scripts de automação (MD→HTML, MD→DOCX com branding Cadastra, sync)
- Pandoc - conversão de documentos para Google Docs
- Jira API - integração com dashboards e relatórios
- Claude AI + MCP - context engineering para desenvolvimento assistido
O que aprendi
A parte mais difícil de criar uma base de conhecimento não é técnica - é cultural. Convencer as pessoas a documentar, a confiar que o tempo investido em escrever vale mais do que o tempo economizado depois. No começo era só eu escrevendo. Aos poucos, quando os devs começaram a encontrar respostas que antes exigiam interromper alguém, a adesão veio naturalmente. O loop de reforço começou a girar.
O erro mais comum que eu vejo em iniciativas de documentação é tratar conhecimento como um artefato estático - um documento que você escreve, arquiva e pronto. Conhecimento é um fluxo. Ele precisa de manutenção, de canais, de estrutura que sustente o movimento. Se você constrói um repositório, você tem uma estante. Se você constrói um sistema com fluxos, feedback e auto-reforço, você tem uma infraestrutura de aprendizado organizacional.
O que eu fiz no cadastra-docs não foi “documentar projetos”. Foi uma intervenção na estrutura de como a operação gera, retém e aplica o que sabe. Mudei os canais por onde a informação se move, as regras de como ela é capturada, e as condições pra que o sistema se auto-alimente. A documentação em si é só o artefato visível. A mudança real é estrutural.