Introdução à base de código

Nível: PODEROSO
Categoria: Engenharia
Área: Documentação / Experiência do Desenvolvedor

Visão geral

Analise uma base de código e gere documentação de integração para engenheiros, líderes técnicos e prestadores de serviços. Esta habilidade é otimizada para a coleta rápida de informações e resultados de integração repetíveis.

Recursos principais

• Descoberta da arquitetura e da pilha de tecnologias a partir de sinais do repositório
• Inventário dos principais arquivos e configurações para novos colaboradores
• Configuração local e geração de orientações para tarefas comuns
• Estruturação da documentação com foco no público-alvo
• Estruturação de listas de verificação para depuração e contribuições

Quando usar

• Ao integrar um novo membro da equipe ou prestador de serviços
• Reestruturação de documentação de projeto desatualizada após grandes refatorações
• Preparação de documentação interna de transferência de responsabilidades
• Criação de um pacote padronizado de integração para serviços

Introdução rápida

# 1) Coletar informações sobre a base de código
python3 scripts/codebase_analyzer.py /caminho/para/repositório

# 2) Exportar resultados em formato legível por máquina
python3 scripts/codebase_analyzer.py /caminho/para/o/repositório --json

# 3) Usar o modelo para elaborar os documentos de integração
# Consulte references/onboarding-template.md

Fluxo de trabalho recomendado

1. Execute o script scripts/codebase_analyzer.py no repositório de destino.
2. Capture os principais indicadores: número de arquivos, linguagens detectadas, arquivos de configuração, estrutura de nível superior.
3. Preencha o modelo de integração em references/onboarding-template.md.
4. Adapte a profundidade da saída de acordo com o público-alvo:
   • Júnior: configuração + diretrizes
   • Sênior: arquitetura + questões operacionais
   • Prestador de serviços: responsabilidades definidas + limites de integração

Modelo de documento de integração

O modelo detalhado e exemplos de seções estão disponíveis em:

• references/onboarding-template.md
• references/output-format-templates.md

Armadilhas comuns

• Escrever documentação sem validar os comandos de configuração em um ambiente limpo
• Misturar análises aprofundadas da arquitetura com documentação voltada para prestadores de serviços
• Omitir etapas de solução de problemas e verificação
• Permitir que os documentos de integração fiquem desatualizados em relação ao estado atual do repositório

Melhores práticas

1. Mantenha as instruções de configuração executáveis e com prazo definido.
2. Documente o “porquê” das principais decisões arquitetônicas.
3. Atualize a documentação no mesmo PR (pull request) em que ocorrem mudanças de comportamento.
4. Trate os documentos de integração como ativos operacionais dinâmicos, e não como entregas pontuais.