Disclaimer
Este texto foi inicialmente concebido pela IA Generativa em função da transcrição de um vídeo do canal Dev Eficiente, apresentado por Alberto Souza. Se preferir acompanhar por vídeo, é só dar o play.
Introdução
Quero começar com duas perguntas. A primeira: você usa agentes de código, tipo Claude Code, Cursor ou Codex? Se sim, e eu imagino que sim, vem a segunda: você já leu a documentação oficial da ferramenta que utiliza?
Fiz uma enquete informal com as pessoas ao meu redor, e a resposta se repetiu: usam bastante, consideram a ferramenta um combustível de produtividade, dizem que ela potencializou o que conseguem entregar. E não leram a documentação. Algo nessa combinação não encaixa, e é sobre isso que quero conversar neste post.
A analogia do carro
A sensação que eu tenho observando esse padrão é muito parecida com a minha relação com o meu carro. Eu sei dirigir, aprendi faz tempo. Mas se o carro quebra, eu sei resolver? Não sei nada. Eu só sei dirigir. E pior: eu nunca li o manual. De vez em quando acho que o carro não tem uma função que, quando vou procurar a solução, está escrita lá.
E, no meu caso, está tudo bem. Eu não trabalho com carros. Saber mais ou menos sobre o carro pode me tirar de uma situação desconfortável, mas não funciona como alavanca para a minha vida. Ninguém vai me avaliar, me julgar ou me pagar mais ou menos pelo quanto eu entendo de carro.
Com uma pessoa desenvolvedora, a conta é outra. Você pode sim ser avaliado pelo quanto conhece os agentes de código que utiliza: quais são os casos de uso, quais configurações existem, como abordar um projeto do zero versus um código que já existe, o que fazer quando a base de código cresce. Imagine usar um Claude Code da vida dentro de um projeto grande, com múltiplos módulos, um legado no sentido de conhecimento acumulado. Como você abordaria esse código? Se o seu conhecimento sobre a ferramenta é só empírico, ou vem só de posts na internet, a resposta que você dá para essa pergunta tem teto.
Um exemplo do mundo real
Pesquisei no Google por melhores práticas com Claude Code. O primeiro link, pelo menos para mim, foi a documentação oficial. O segundo foi uma postagem no Reddit com mais de vinte comentários, de alguém contando o cenário da equipe: usam bastante o Claude Code, a qualidade do código é boa, o código roda, os testes passam. Mas, conforme a base cresce e novos recursos são adicionados em cima de código gerado por IA, as coisas ficam bagunçadas, fica difícil entender o que está acontecendo, código morto se acumula e as soluções começam a sair superdimensionadas. A pessoa então conta que começou a usar o CLAUDE.md e uma pasta de regras para dar mais estrutura, mas que ainda está descobrindo o que funciona.
Duas leituras são possíveis. Talvez a pessoa tenha lido a documentação oficial e esteja tentando extrapolar o que está lá. Ou talvez não tenha lido. O texto não cita as fontes consultadas, então não dá para saber, e o ponto aqui não é julgar o autor. O ponto é o padrão: a documentação oficial diz, logo no início, que o CLAUDE.md é o arquivo de contexto básico da ferramenta, carregado no startup e enviado em toda requisição que o Claude Code faz para os modelos, com todo um mecanismo de caching na infraestrutura para não reprocessar isso a cada chamada. Quando alguém relata que "começou a usar o CLAUDE.md" depois de meses de uso intenso, a pergunta natural é: qual foi o repertório teórico consultado até ali?
O mar de fontes secundárias
Seguindo na mesma pesquisa, depois da documentação vem uma enxurrada de conteúdo derivado: ebooks de melhores práticas, listas de 24 dicas, 7 recursos essenciais, tutorial completo, guia definitivo. Enquanto isso, a documentação oficial tem, inclusive, um capítulo chamado melhores práticas. Tem uma seção sobre como configurar a ferramenta em um monorepo ou em uma base de código grande. Explica como criar plugins, sem precisar de post de blog nenhum. Explica como funciona a janela de contexto, o que é carregado de partida, como ela vai enchendo, como funciona o mecanismo de compactação, como funciona o caching na infraestrutura, o que você paga e o que é reaproveitado.
Ou seja: boa parte das perguntas que aparecem em threads e posts já tem resposta na fonte primária. E as fontes secundárias, por definição, são menos confiáveis do que a documentação, porque são a interpretação de alguém sobre o que está lá.
Para que serve a teoria
Dentro do Dev + Eficiente temos um curso chamado Máquina de Aprender, que fala sobre aprendizagem efetiva, e uma ideia de lá ajuda a enquadrar essa discussão. Uma teoria deriva de alguma prática, ou de uma observação muito atenta de alguma prática. Quem escreve, escreve porque fez alguma coisa ou porque observou várias pessoas fazendo, e relata aquilo em texto. Para quê? Para que você leia e consiga chegar a níveis parecidos com quem estava praticando, de maneira mais eficiente, sem precisar passar por todos os problemas pelos quais a pessoa ou a equipe anterior passou.
Quando você vai escolher uma fonte teórica, eu costumo sugerir a análise por duas dimensões. A primeira é o quão fácil ela é de consumir: tem gente que prefere vídeo, tem gente que prefere texto, e isso é legítimo. A segunda é a confiabilidade da fonte. E, quando o assunto é uma ferramenta, a fonte mais confiável disponível para a maioria das pessoas é a documentação oficial.
Existem fontes acima dela, vale dizer. Se você tiver acesso ao código-fonte, ele é mais confiável do que a documentação, porque a documentação explica o que está no código. E se você conhecesse pessoalmente quem construiu a ferramenta, essa pessoa talvez fosse uma fonte ainda melhor. Para quase todo mundo, porém, o teto de confiabilidade acessível é a documentação.
Se você abre mão da fonte de confiabilidade máxima no seu repertório, duas coisas podem acontecer: você deixa conhecimento na mesa, ou deixa de confrontar um conhecimento que chegou até você de maneira equivocada. Isso vale inclusive para este texto. Quando eu explico algo sobre o Claude Code, como você sabe que eu não entendi errado? Você pode dar valor ao que eu digo, mas a confirmação vem do confronto com a fonte oficial.
Confrontando fontes para criar conexões
Esse confronto entre fontes, aliás, é onde o aprendizado fica mais interessante. Um exemplo: o blog da OpenAI publicou este ano um texto chamado Harness Engineering: Leveraging Codex in an Agent-First World. É o relato de uma ferramenta construída internamente em que a equipe decidiu não escrever nada à mão: infraestrutura, código, tudo foi feito via agentes. O texto conta como eles foram refinando o contexto, iterando sobre ele e quais práticas foram usando ao longo do caminho.
Ler um relato como esse e confrontá-lo com o que está na documentação oficial da ferramenta que você utiliza faz a sua cabeça criar conexões novas. O relato traz a experiência de uma equipe em um contexto específico; a documentação traz o comportamento garantido da ferramenta. É no cruzamento dos dois que você forma um entendimento que nem o post sozinho nem a documentação sozinha entregariam.
Conclusão
Não estamos falando de uma ferramenta que aparece ocasionalmente no seu dia. Estamos falando de algo que boa parte das pessoas desenvolvedoras usa o tempo inteiro, para um monte de coisas. Se a ferramenta tem esse peso no seu trabalho, deixar de ler a documentação oficial é provavelmente desperdiçar conhecimento e, eventualmente, ser menos eficiente do que você poderia ser, porque existem recursos e comportamentos descritos lá que você nem sabe que existem. Como eu com o meu carro, com a diferença de que ninguém me paga pelo que eu sei sobre carros.
A sugestão prática é simples: reserve um tempo para ler a documentação oficial da ferramenta que você usa todos os dias. Analise suas fontes teóricas pelas duas dimensões, facilidade de consumo e confiabilidade, e garanta que a fonte de confiabilidade máxima esteja no seu repertório.
Dev + Eficiente
Desenvolva software de alta qualidade e domine Engenharia de IA com o Dev + Eficiente. Cursos práticos, acesso vitalício, comunidade ativa e acesso a vagas remotas exclusivas em diversas empresas de tecnologia. Sua jornada para se tornar um dev mais eficiente pode começar agora.
Top comments (0)