Commit Archaeologist: por que este código existe

ANÁLISE EDITORIAL

Commit Archaeologist reconstrói por que um trecho de código provavelmente existe usando somente o histórico Git local. Em vez de parar no último autor mostrado por git blame, a Skill procura o commit que introduziu a região atual, acompanha mudanças posteriores, separa autoria presente de autoria histórica, identifica arquivos que mudaram repetidamente ao lado do alvo e reúne pistas de intenção encontradas nas mensagens dos commits.

A versão auditada é a 1.0.0, publicada em Shubhamsaboo/awesome-llm-apps e fixada no commit 9848ec842c5f559ad42654288cc6a38db6b175fb. Em 10 de setembro de 2026, o repositório estava público, não arquivado, sob licença Apache-2.0 e mostrava 136.897 estrelas. Estrelas pertencem ao repositório amplo, que reúne muitos aplicativos e Skills, e não medem isoladamente o uso desta Skill.

O pacote local contém cinco arquivos textuais: SKILL.md, scripts/archaeologist.py, references/reading-git-history.md, LICENSE e ORIGEM.md. Não inclui repositórios, históricos Git, resultados, dependências, binários, executáveis compilados, chaves, tokens ou credenciais.

Ilustração editorial exclusiva do Bastidores da IA. Não é captura de tela, repositório real, histórico analisado, prova de autoria, selo, certificação nem material oficial do projeto.

O que esta Skill faz

A Skill recebe o caminho de um repositório Git local e o caminho de um arquivo rastreado. Opcionalmente, aceita um intervalo atual de linhas no formato 40-72. Em modo de arquivo, usa o histórico com acompanhamento de renomeações. Em modo de linhas, usa o rastreamento de patches do Git para descobrir quais commits moldaram a região selecionada.

O script devolve uma estrutura JSON com a região analisada, o commit introdutor dentro do histórico selecionado, a linha do tempo em ordem cronológica, arquivos que aparecem repetidamente nas mesmas mudanças, autores atuais e históricos em contagens separadas, além de sinais como referência a issue, revert, workaround, temporary e TODO. A instrução original fixada transforma esses campos em um relatório curto de origem, evolução, evidência de intenção e risco de mudança.

Para quem serve

Serve a desenvolvedores e revisores que encontraram um bloco estranho, uma condição defensiva, uma compatibilidade antiga ou um workaround antes de um refactor. Também ajuda quem entrou recentemente em um projeto e precisa entender se um detalhe veio de uma correção, de uma reversão, de uma migração ou de uma decisão explícita registrada no histórico.

Ela é especialmente útil antes de mexer em código sensível. Um teste que sempre muda com a função, uma migração alterada nos mesmos commits ou uma mensagem que cita uma limitação externa pode revelar uma restrição que o código atual, visto sozinho, não explica. A Skill não substitui leitura do código, testes ou conversa com responsáveis. Ela organiza evidências para que a decisão comece melhor informada.

Compatibilidade e limites

O script declara Python 3.8 ou posterior e usa somente biblioteca padrão. O ambiente também precisa ter Git no PATH, acesso de leitura ao repositório local e histórico suficiente para a pergunta. O arquivo precisa estar rastreado no HEAD. Caminhos fora da raiz do repositório são rejeitados.

Histórico raso, blobs ausentes, arquivos copiados, grandes reescritas e algumas renomeações podem interromper a ancestralidade. O modo por linhas pode começar depois da criação do arquivo. Por isso, o commit mais antigo da seleção deve ser chamado de introdução da região, não automaticamente de criação original do arquivo.

A Skill analisa um arquivo ou uma região. Ela não é um mapa completo de arquitetura, não consulta pull requests automaticamente e não lê discussões externas. Quando a mensagem do commit é vaga, o resultado só mostra o que mudou e com quem mudou. O motivo continua incerto.

Pré-requisitos

Use uma cópia local autorizada do repositório. Confirme que o diretório contém .git, que o arquivo está rastreado e que o histórico necessário está disponível. Em clones rasos, busque mais histórico somente se a política do projeto e a rede permitirem. Não aponte para pastas irmãs nem para outro projeto por conveniência.

Defina uma pergunta estreita. “Por que esta validação existe?” é melhor que “explique o projeto inteiro”. Registre o arquivo, a função ou bloco e o intervalo atual de linhas. Se a região mudou desde a pergunta original, revise os números antes de executar.

Leia também o guia de interpretação incluído pela origem. Ele é parte funcional do método, pois define como distinguir fato, correlação e inferência.

Instalação com revisão

Baixe o ZIP documental desta página e compare o SHA-256 com dd0bac33a1c2534830edb5cd2b0456077e021fd7c2d46106f706ea4141772449. Extraia em uma pasta de teste e leia os cinco arquivos. Compare SKILL.md, o script e a referência com a pasta original no commit auditado.

Depois, copie a pasta para o diretório de Skills aceito pelo seu agente. A instalação grava arquivos localmente, mas não instala pacote Python e não altera o repositório que será analisado. O arquivo archaeologist.py é código fonte textual. Revise-o antes do primeiro uso, como faria com qualquer automação local.

Configuração antes do primeiro uso

Não há chave de API, conta ou serviço externo para configurar. A configuração real é de escopo. Informe o caminho exato do repositório, o arquivo rastreado e, quando necessário, as linhas atuais. A origem orienta pedir somente o dado ausente e não varrer repositórios vizinhos.

Escolha o modo. Para a evolução completa de um arquivo, omita --lines. Para uma função ou bloco atual, use um intervalo inclusivo. Acrescente --json quando quiser a saída estruturada. Sem essa opção, o script imprime um resumo humano com introdução, linha do tempo, co-alterações repetidas e sinais de intenção.

Primeiro uso seguro

Comece em um repositório de teste conhecido. A forma indicada pela Skill é python3 scripts/archaeologist.py /caminho/do/repositorio src/cache.py --lines 40-72 --json. Em Windows, use o comando Python disponível no ambiente e passe caminhos corretamente citados. Não transforme o exemplo em execução automática sobre todos os arquivos.

O resultado esperado inclui region, introduced_by, timeline, co_changed, authors e intent_signals. Confira se o arquivo e o intervalo normalizados correspondem ao alvo. Depois, abra os commits mais relevantes com Git e leia os diffs. O JSON é um índice de investigação, não a conclusão final.

Como interpretar a linha do tempo

O script ordena os commits do mais antigo para o mais recente e classifica mensagens por palavras como feat, fix, refactor, revert e hotfix. A classificação é heurística. Um commit com “refactor” no assunto não prova que o comportamento foi preservado, assim como um “fix” não comprova que a causa raiz foi resolvida.

A documentação do git log explica o histórico de commits, enquanto a opção de linha -L acompanha a evolução de uma faixa ou função. Leia assunto, corpo, diff e arquivos alterados em conjunto. Preserve reverts e workarounds no relato, pois eles costumam carregar contexto relevante.

Autoria sem conclusões falsas

A documentação do git blame deixa claro que o comando anota linhas com a revisão que as modificou por último. Isso responde quem tocou nas linhas sobreviventes, não necessariamente quem desenhou o comportamento. O Commit Archaeologist mantém separadas a contagem de linhas atuais e a contagem de commits na seleção.

Uma frase segura é “as linhas atuais são atribuídas a esta pessoa pelo blame”. Outra é “este commit introduziu a região dentro do histórico selecionado”. Dizer que alguém decidiu a arquitetura exige mensagem, issue ou discussão que sustente a conclusão. Mesmo assim, registre a fonte e o nível de confiança.

Arquivos companheiros e pistas de acoplamento

Para cada commit da seleção, o script usa informações equivalentes às produzidas por git diff-tree e reúne os arquivos alterados. Só entram em co_changed os arquivos que cruzam um limiar de repetição. Uma ocorrência isolada não é apresentada como padrão.

Testes, esquemas, migrações e configurações que mudam repetidamente com o alvo são boas pistas de acoplamento. Ainda assim, correlação não prova dependência. Mudanças de formatação, geração de código ou commits muito grandes podem criar associações sem significado. O próximo passo é abrir os arquivos e confirmar a relação no código.

Resultado esperado

O relatório final deve começar com uma síntese de uma ou duas frases e confiança alta, média ou baixa. Depois, deve registrar origem, linha do tempo, arquivos companheiros, evidências de intenção e riscos para a próxima alteração. Hashes curtos ajudam a leitura, desde que continuem identificáveis.

Confiança alta exige linguagem explícita de restrição mais mudanças que a sustentem, ou uma reversão que diga claramente qual comportamento foi restaurado. Confiança média cabe quando mensagens, arquivos e sequência concordam sem declarar a razão. Confiança baixa é a escolha correta diante de histórico curto, assuntos genéricos, reescritas amplas ou pistas conflitantes.

Permissões e riscos

O script inicia processos locais do Git e lê metadados, conteúdo rastreado, blame, mensagens e listas de arquivos. Ele valida que o alvo fica dentro do repositório e não executa comandos de escrita. A inspeção do código auditado confirmou que não há chamada de rede, gravação no repositório, checkout, reset, commit, push ou alteração de configuração.

Mesmo uma ferramenta somente leitura pode expor informações na saída. Nomes, e-mails de autores, assuntos de commits, caminhos e referências a issues podem ser sensíveis. Não cole o JSON integral em sistemas públicos sem revisão. Repositórios privados devem continuar no ambiente autorizado.

O risco mais importante é epistemológico: transformar pista em certeza. Uma co-alteração não prova dependência. Um autor no blame não prova autoria original. Uma palavra “temporary” não confirma que a restrição ainda vale. A Skill é boa justamente quando suas ressalvas permanecem visíveis no relatório.

Erros comuns e como corrigir

“repository path is not a directory”: confira o caminho e as aspas. Use a raiz ou uma subpasta dentro de um repositório acessível.

“not a git repository”: confirme a presença do histórico local. Uma pasta apenas com arquivos exportados não basta.

“file is not tracked at HEAD”: use o caminho relativo correto e verifique com git ls-files. Arquivos novos ou ignorados não têm histórico rastreado.

Intervalo inválido: informe números positivos no formato A-B, com início menor ou igual ao fim. O final não pode ultrapassar o número de linhas atuais.

Origem parece recente demais: compare modo de linhas e modo de arquivo. Reescritas e cópias podem quebrar a cadeia. Relate que a ancestralidade anterior ficou incerta.

Nenhuma pista de intenção: isso significa apenas que as mensagens selecionadas não trazem os padrões reconhecidos. Leia diffs, issues citadas e documentação. Não invente um motivo.

Timeout do Git: o script limita cada comando a 30 segundos. Reduza o escopo, garanta que os objetos estão locais ou analise uma região menor. Não aumente o limite sem entender o tamanho e a política do repositório.

O que o teste editorial confirmou

A auditoria executou o próprio archaeologist.py contra o arquivo SKILL.md no clone local do commit fixado. A saída identificou Matt Van Horn nas linhas atuais, encontrou um commit introdutor, registrou a referência #974 como sinal e não inventou co-alterações repetidas quando havia somente um commit na linha do tempo. Esse último ponto é importante porque o histórico do projeto registra uma correção específica para impedir que uma ocorrência única parecesse um padrão.

O teste também confirmou a separação entre os campos. authors mostrou linhas atuais e commits históricos em contagens distintas. introduced_by preservou hash, data, autor e assunto. timeline trouxe arquivos alterados, categoria heurística e corpo da mensagem. intent_signals registrou a referência encontrada sem convertê-la em explicação automática.

Isso valida o caminho básico, a serialização JSON e as principais cautelas do método. Não valida todos os formatos de repositório, históricos com objetos ausentes, submódulos, filtros parciais ou arquivos com ancestralidade interrompida. Em produção, repita um teste pequeno no projeto real e guarde a mensagem de erro integral quando o Git não conseguir reconstruir a seleção.

Quando não usar

Não use esta Skill quando a pergunta pede apenas uma lista de commits, um blame cru ou o conteúdo atual do arquivo. Os comandos Git correspondentes são mais diretos. Também não use para reescrever, apagar ou compactar histórico. A ferramenta foi desenhada para investigação somente leitura.

Evite usar um único intervalo para explicar arquitetura de todo o projeto. Nesse caso, comece por documentação, estrutura de módulos e fluxos atuais. Depois aplique arqueologia somente aos pontos cujo histórico pode esclarecer uma decisão de risco.

Não use o resultado como avaliação de desempenho individual. Contagens de blame e commits não medem responsabilidade, qualidade ou autoria intelectual. Mudanças podem ter sido revisadas, pareadas, geradas mecanicamente ou aplicadas por outra pessoa. O relatório deve permanecer sobre o código e suas evidências, não sobre julgamento de pessoas.

Versão, licença e pacote auditado

O frontmatter declara Commit Archaeologist 1.0.0, autoria de Matt Van Horn e licença Apache-2.0. A origem foi fixada no commit 9848ec842c5f559ad42654288cc6a38db6b175fb. A licença do repositório no commit permite redistribuição sob suas condições.

O ZIP local tem cinco arquivos textuais, 13.896 bytes e SHA-256 dd0bac33a1c2534830edb5cd2b0456077e021fd7c2d46106f706ea4141772449. O script foi testado em um repositório Git local e retornou JSON válido. Esse teste confirma funcionamento básico no ambiente usado, não garante que todo histórico incompleto ou incomum será reconstruído.

Checklist antes de avançar

• Confirme repositório, arquivo e intervalo atuais.
• Compare o hash do ZIP e leia os cinco arquivos.
• Comece com uma pergunta estreita e um repositório autorizado.
• Separe autoria atual, autoria histórica, correlação e inferência.
• Abra os commits relevantes e valide os arquivos companheiros.
• Redija a conclusão com nível de confiança e lacunas explícitas.
• Não modifique código até receber autorização separada.

Fontes oficiais consultadas

• Repositório Shubhamsaboo/awesome-llm-apps.
• Commit fixado da auditoria.
• Script archaeologist.py auditado.
• Documentação oficial do subprocess em Python.
• Documentação oficial do argparse.
• Documentação oficial do git log.
• Documentação oficial do git blame.
• Documentação oficial do git diff-tree.
• Especificação Agent Skills.

Para explorar outras ferramentas revisadas com download documental, consulte o catálogo de Skills do Bastidores da IA.