Gerador de Contexto do Projeto
Cria ou atualiza .claude/docs/project.md — a referência concisa do projeto que Claude carrega em toda conversa. Diferente de um README (escrito para humanos), o project.md é escrito para Claude: denso, factual, sem prosa de marketing.
Por que esta skill existe
.claude/docs/project.md é automaticamente carregado em toda conversa com Claude via CLAUDE.md. Quando está ausente ou desatualizado, Claude desperdiça turnos redescobrindo a stack de tecnologia, comandos de teste e arquitetura. Esta skill automatiza essa descoberta e produz um arquivo de referência enxuto e preciso.
Fluxo de Trabalho
Etapa 1: Analisar o código-fonte
Execute uma análise estruturada em três fases para coletar fatos do projeto. Rotule cada fato com um nível de confiança: [confirmed] (lido diretamente da fonte), [inferred-high] (forte evidência), [inferred-low] (evidência parcial) ou [unknown].
Consulte references/analysis-methodology.md para ações detalhadas das ferramentas, padrões de glob/grep e modelos de registro.
Fase 1 — Metadados do Projeto: Faça glob para arquivos de gerenciador de pacotes, templates de ambiente, configurações de CI e arquivos da toolchain. Extraia: nome do projeto, linguagem, versão do Python, dependências (com finalidades), scripts/comandos, variáveis de ambiente, estágios de CI, marcadores de teste.
Fase 2 — Varredura de Arquitetura: Faça glob para todos os arquivos fonte. Identifique pontos de entrada, construa o grafo de importações, classifique módulos (núcleo/folha/orquestrador) e identifique o padrão arquitetural. Leia arquivos de configuração referenciados pelo código fonte.
Fase 3 — Fontes de Dados e Infraestrutura: Identifique fontes externas de dados (bases de dados, APIs, arquivos), destinos de saída (arquivos, uploads, APIs), estrutura de testes e hierarquia de exceções customizadas.
Etapa 2: Fazer perguntas esclarecedoras
Após a análise, pergunte ao usuário sobre itens [inferred-low] e [unknown]. Mantenha o foco — não pergunte sobre coisas que você já sabe. Lacunas comuns:
- Propósito do projeto: Qual problema ele resolve? (se não for óbvio pelo código)
- Fontes de dados: Quais sistemas alimentam dados? O que recebe saída?
- Implantação: Como/onde isso é executado? (local, agendado, nuvem)
Se o código-base for direto, você pode precisar apenas de 1-2 perguntas — ou nenhuma.
Etapa 3: Gerar project.md
Escreva o arquivo usando a estrutura abaixo. Se .claude/docs/project.md já existir, confirme com o usuário antes de sobrescrever.
Estrutura de Saída
O project.md gerado deve seguir esta estrutura. Escale a profundidade de acordo com o projeto — projetos pequenos podem pular seções, projetos complexos podem adicionar subseções.
# {Nome do Projeto} — Contexto do Projeto
{Descrição de uma frase: o que é, o que faz, tecnologia chave.}
## Stack de Tecnologia
- **{Linguagem/Runtime}** — {restrição de versão, se conhecida}
- **{Framework}** — {para que é usado}
- **{Biblioteca Chave}** — {propósito}
- ...lista com marcadores, negrite o nome da ferramenta, anote o propósito
## Layout do Projeto
```text
{árvore de diretórios anotada — uma frase curta por entrada}
```
Fluxo de Dados
{diagrama ASCII mostrando pipeline fonte → transformação → saída}
Fontes de Dados
{NOME_DA_FONTE}— {o que fornece}- ...para bases de dados, APIs, arquivos locais, etc.
Marcadores de Teste
{comando de teste}— {o que executa}{nome do marcador}— {o que controla}
Padrões Chave de Arquitetura
- {Nome do padrão} (
{arquivo}): {explicação de uma frase} - ...apenas padrões não óbvios que mereçam destaque
Diretrizes de Escrita
- Denso em vez de verboso. Cada linha deve merecer seu espaço. Claude não precisa de motivação ou contextualização — apenas fatos.
- Específico em vez de genérico. "Execute
uv run pytest -m 'not snowflake'" é melhor que "Execute os testes excluindo dependências externas." - Uma frase por padrão. Padrões de arquitetura devem ser uma linha cada — nome, arquivo, explicação.
- Comandos reais. Copie comandos de teste do
pyproject.tomlou configurações de CI, não versões parafraseadas. - Anote dependências. Não liste apenas
polars— digapolars — DataFrames de alto desempenho. - Fontes de dados são críticas. Claude precisa saber quais sistemas externos existem. Liste toda base de dados, API e arquivo fonte.
- Mantenha abaixo de 100 linhas. Se o project.md ultrapassar ~100 linhas de conteúdo, está detalhado demais — mova especificidades para documentações dedicadas e faça links para elas.
Saída
Salve o arquivo como .claude/docs/project.md (crie o diretório se necessário). Se o arquivo já existir, mostre ao usuário um resumo das diferenças antes de sobrescrever.
Após gerar o project.md, verifique se CLAUDE.md o referencia. Se não, sugira adicionar uma linha como:
Veja [.claude/docs/project.md](.claude/docs/project.md) para detalhes específicos do projeto (stack de tecnologia, arquitetura, marcadores de teste).