Acquire Codebase Knowledge

ANÁLISE EDITORIAL

Acquire Codebase Knowledge é uma Agent Skill para entrar em um repositório existente sem transformar suposição em documentação. Ela orienta o agente a levantar o que realmente está nos arquivos e produzir sete documentos separados sobre stack, estrutura, arquitetura, convenções, integrações, testes e preocupações técnicas.

A versão auditada é a 1.3, publicada no repositório oficial github/awesome-copilot, commit 55b952d. Em 13 de agosto de 2026, durante a janela editorial das 16h em America/Sao_Paulo, a API oficial do GitHub registrava 37.789 estrelas. O repositório declara licença MIT.

Imagem editorial exclusiva do Bastidores da IA. Não é captura de tela, interface real nem prova de que um repositório foi auditado.

O que esta Skill faz de verdade

O SKILL.md auditado define um contrato de saída incomum por ser bem específico. Ao terminar, precisam existir exatamente sete arquivos em docs/codebase/: STACK.md, STRUCTURE.md, ARCHITECTURE.md, CONVENTIONS.md, INTEGRATIONS.md, TESTING.md e CONCERNS.md. Cada afirmação deve apontar para arquivo, configuração ou saída de terminal. Lacunas recebem [TODO]. Decisões que dependem da intenção da equipe recebem [ASK USER].

O fluxo começa pelo inventário técnico e pelos documentos que declaram intenção, como README, PRD, TRD, roadmap, especificação e design. A ordem importa. Primeiro ele registra o que o projeto diz que pretende ser. Depois confronta essa intenção com manifests, diretórios, pontos de entrada, dependências, integrações e testes. A entrega final precisa destacar divergências entre intenção e realidade, sem escolher silenciosamente qual lado está certo.

A pasta inclui sete templates, duas referências e um scanner Python. A referência de checkpoints transforma cada documento em perguntas verificáveis. A referência de detecção de stack ajuda quando o repositório tem vários manifests ou tecnologias pouco familiares.

Para quem serve

Serve para quem precisa assumir manutenção de um sistema, preparar onboarding técnico, documentar uma arquitetura existente ou descobrir o que há em um repositório antes de planejar mudanças. É útil quando o conhecimento está espalhado entre código, configuração, histórico Git e pessoas que já não participam diariamente do projeto.

Ela não duplica a Skill Code Review and Quality. A revisão de código examina uma mudança, classifica achados e ajuda na decisão de merge. Acquire Codebase Knowledge estabelece a linha de base do repositório inteiro. Também não duplica Find Skills, cuja função é localizar capacidades instaláveis em um catálogo, nem Create PRD, que transforma necessidades em requisitos. Aqui o objeto é a realidade técnica já existente.

O uso faz mais sentido quando há tempo para conferir evidências. Em uma correção estreita, pedir sete documentos pode custar mais do que ajuda. A própria descrição oficial manda não ativar a Skill para manutenção rotineira, bug pontual ou edição limitada, a menos que o usuário peça descoberta em nível de repositório.

Compatibilidade e pré-requisitos

O frontmatter declara compatibilidade multiplataforma, Python 3.8 ou mais recente e Git. A coleção foi criada para o ecossistema GitHub Copilot e segue a estrutura de Agent Skills. A documentação oficial do GitHub sobre Agent Skills explica que uma Skill usa um arquivo SKILL.md e pode incluir scripts, referências e outros recursos.

A instalação documentada pelo repositório usa GitHub CLI 2.90.0 ou mais recente. Outros clientes que entendem Agent Skills podem conseguir carregar o conteúdo manualmente, mas isso não garante que caminhos, comandos, variáveis ou permissões se comportem da mesma forma. Antes de prometer portabilidade, confirme como o cliente resolve o diretório da Skill, executa Python e expõe o terminal.

O repositório alvo também precisa estar disponível localmente. O fluxo depende de leitura de arquivos e do histórico Git. Em um ZIP sem a pasta .git, as seções de commits recentes e arquivos de alta alteração não terão a mesma evidência. Em monorepos, o agente precisa identificar workspaces, pacotes e aplicações separadamente, em vez de tratar o manifest da raiz como toda a arquitetura.

Instalação recomendada

A lista oficial de Skills registra este comando:

gh skills install github/awesome-copilot acquire-codebase-knowledge

O comando acessa a rede e grava arquivos no ambiente configurado pelo GitHub CLI. Execute primeiro em uma conta e máquina de teste, confirme a origem do repositório e revise a pasta instalada antes de autorizar o agente a usar o conteúdo. Não copie apenas o SKILL.md se o objetivo for executar o fluxo completo, pois ele referencia templates, checkpoints e o scanner.

O ZIP do Bastidores tem outro propósito. Ele preserva somente a documentação redistribuível para leitura e comparação. O scanner foi excluído. Quem quiser a instalação funcional deve abrir o repositório oficial, conferir o commit fixado, revisar o script e usar o método oficial no ambiente correto.

Configuração antes do primeiro uso

Escolha um repositório de teste que não contenha segredos, dados pessoais, dumps, chaves, certificados ou artefatos de cliente. Mesmo um inventário somente de leitura pode expor informações quando o relatório repete trechos de manifests, nomes de arquivos, variáveis de ambiente de exemplo, integrações ou histórico de commits.

Defina um diretório de saída claro. O fluxo oficial usa docs/codebase/ e o scanner sugere docs/codebase/.codebase-scan.txt. Isso cria arquivos no repositório. Se a tarefa inicial for apenas entendimento, autorize a leitura primeiro e decida depois se a documentação deve ser gravada, versionada ou mantida fora da branch principal.

Também delimite o foco. A Skill aceita pedidos como “arquitetura apenas” ou “testes e riscos”. Mesmo nesse modo, a fase inicial continua completa, mas os documentos fora do foco podem manter seções com [TODO]. Esse contrato evita preencher lacunas com texto plausível só para entregar sete arquivos visualmente completos.

Por fim, combine o que é permitido no terminal. Ler arquivos é uma permissão. Executar o scanner é outra. Rodar testes, instalar dependências, consultar serviços externos ou editar documentos são ações separadas. O agente deve pedir autorização quando o efeito ultrapassar o escopo acordado.

Primeiro uso seguro

Um pedido inicial útil é explícito sobre leitura, saída e limites:

Mapeie este repositório para onboarding técnico.
Comece somente com leitura.
Não execute scripts, testes ou instalação de dependências sem pedir.
Separe intenção declarada de realidade observada.
Marque desconhecidos como [TODO] e decisões humanas como [ASK USER].
Cite o caminho de cada evidência.

Antes de aceitar a documentação, escolha três afirmações importantes e siga os caminhos citados. Se ARCHITECTURE.md disser que existe uma fila assíncrona, procure a dependência, a configuração e o ponto de publicação ou consumo. Se TESTING.md disser que há testes de integração, confirme o framework, a localização e como eles são executados. Se CONCERNS.md marcar um arquivo como frágil por alta alteração, confira o histórico Git.

O resultado esperado não é uma narrativa elegante sobre como o sistema deveria funcionar. É um mapa que reduz o tempo de descoberta e deixa claro onde a evidência termina. Um documento mais curto com caminhos corretos é melhor do que uma arquitetura completa baseada em nomes de pastas.

Permissões e riscos

A auditoria estática do scanner Python oficial confirmou que ele percorre diretórios, lê manifests e modelos como .env.example, procura marcadores TODO, FIXME e HACK, calcula métricas simples, detecta CI, contêineres, configuração de segurança e sinais de desempenho. Ele também chama git log e git rev-parse por subprocesso e grava o relatório no caminho informado.

A revisão não encontrou importação de biblioteca de rede no script. Isso não transforma o arquivo em seguro por definição. Código de terceiro precisa ser avaliado no commit escolhido, e o ambiente de execução pode conter hooks, aliases, filtros, submódulos ou arquivos sensíveis. O controle local desta curadoria não autorizou a execução do scanner baixado. Por isso, esta página não afirma que o script foi testado em runtime.

Há risco de vazamento por documentação. Nomes de serviços internos, endpoints, variáveis, caminhos, comentários e mensagens de commit podem ser sensíveis mesmo sem incluir uma chave. Se o agente usa um modelo remoto, verifique política de dados, contrato, retenção e classificação da informação antes de enviar o repositório ou o relatório.

Existe também risco de falsa precisão. Contar linhas não mede complexidade. Arquivo com muita alteração não é automaticamente defeituoso. Ausência de teste detectado não prova que o sistema não foi testado por outro processo. Cada sinal precisa de contexto e confirmação humana.

Erros comuns

O README diz uma coisa e o código mostra outra

Registre os dois lados. README representa intenção ou documentação disponível; código e configuração mostram o estado observado. Não “corrija” a divergência escolhendo silenciosamente uma versão. Marque a decisão como [ASK USER] quando depender do rumo desejado pela equipe.

Os sete documentos foram criados, mas parecem genéricos

Procure listas de evidência. Cada afirmação material precisa apontar para arquivos concretos. Troque frases como “usa arquitetura limpa” por observações verificáveis sobre camadas, dependências e fluxo de dados. Se não houver evidência, use [TODO].

O scanner gerou informação demais

O relatório é ponto de partida, não a entrega final. Use os checkpoints para escolher o que sustenta cada documento. Não copie manifests inteiros, segredos, dados de cliente ou listas sem relação com onboarding. Prefira resumo e caminho de evidência.

O agente documentou build e arquivos gerados como convenção

A Skill manda excluir diretórios como dist, build, generated, .next e __pycache__ da leitura de padrões. Convenções vêm do código-fonte. Artefatos compilados podem ser úteis para entrega, mas não devem definir como o projeto é escrito.

A execução falha fora de um clone Git

O scanner pode continuar produzindo partes do inventário, mas histórico recente e churn ficam sem base. Registre essa limitação. Não invente commits, autores ou áreas frágeis para preencher o template.

Versão auditada e download local

O pacote local foi montado a partir do commit 55b952d2f9bd5b092d2f4b87fdbcf205a1a5ccc5. O último commit que alterou a pasta da Skill é b8f38227480c9f3fe04d6496d4fcab9a880e5a15. A versão declarada é 1.3 e a licença é MIT.

O ZIP contém 12 arquivos textuais: SKILL.md, LICENSE, ORIGEM.md, duas referências Markdown e sete templates Markdown. O arquivo scripts/scan.py foi excluído por ser executável. Não há binário, instalador, dependência, token, credencial ou dado de projeto. Tamanho: 16.171 bytes. SHA-256: 99097b1797a655694e72fd566c352d6f2cff362eefdadc7380b3b0f5e11c4ce7.

O download local serve para auditoria, leitura e comparação de versões. Ele não substitui a instalação oficial e não executa o workflow completo. Para usar o scanner, abra o link separado do repositório, revise o código fixado e faça a instalação no ambiente de teste aprovado.

Resultado esperado e limite final

Uma boa execução entrega sete documentos que uma pessoa nova consegue usar para localizar dependências, pontos de entrada, fronteiras, integrações, estratégia de testes e riscos conhecidos. As perguntas [ASK USER] revelam onde a documentação depende de decisão da equipe. Os [TODO] impedem que desconhecidos virem fatos.

O limite final é importante: Acquire Codebase Knowledge documenta o que consegue observar, não certifica a arquitetura, a segurança ou a qualidade do sistema. O scanner reúne sinais, e o agente interpreta arquivos. Nenhum dos dois substitui os responsáveis pelo domínio, medições específicas, teste real ou revisão de segurança.

Use a Skill para reduzir tempo de descoberta e tornar lacunas visíveis. Depois, trate a documentação como código: revise, versione, atualize quando a arquitetura mudar e remova informações sensíveis antes de compartilhar.

Fontes primárias

• Pasta oficial da Skill no commit auditado.
• SKILL.md oficial, versão 1.3.
• Scanner Python excluído do pacote local.
• Checkpoints oficiais de investigação.
• Referência oficial de detecção de stack.
• Catálogo oficial com comando de instalação.
• Licença MIT do repositório.
• Documentação oficial do GitHub sobre Agent Skills.