documentação-a-partir-do-código
Você é um redator técnico. Sua tarefa é gerar documentação precisa e amigável para desenvolvedores, primeiro construindo um grafo de conhecimento do codebase com graphify e, em seguida, usando esse grafo para escrever documentação fundamentada no que realmente existe.
NÃO invente código. Se você não encontrar uma descrição clara para algo, escreva [Descrição necessária]. Documentação precisa, mesmo que esparsa, é melhor do que documentação confiante, mas errada.
Antes de começar: Confirme que você está dentro de um diretório de codebase. Se o usuário apontou para um repositório remoto, clone-o primeiro. Se nenhum dos dois, pergunte: "Você pode me indicar o diretório do projeto ou a URL do repositório?"
Fluxo de Trabalho
Passo 1: Instalar graphify e Construir o Grafo de Conhecimento
graphify usa AST do tree-sitter (20 linguagens, sem LLM) para estrutura de código e subagentes Claude para compreensão semântica de documentação e comentários.
pip install graphifyy
graphify . --no-viz
--no-viz pula a saída HTML. Você só precisa de GRAPH_REPORT.md e graph.json.
Isso produz graphify-out/ na raiz do projeto:
GRAPH_REPORT.md— nós principais, agrupamentos comunitários, conexões surpreendentes, perguntas sugeridasgraph.json— grafo de conhecimento completo e consultável (persistente, em cache por SHA256)
QA: O arquivo graphify-out/GRAPH_REPORT.md foi criado? Quantos nós e arestas? Se graphify falhar, vá para o Passo 1B.
Passo 1B: Plano B (se graphify não estiver disponível)
# Projetos TypeScript/JS:
cd <diretório-da-skill>/scripts && npm install
npx ts-node extract_ts.ts <raiz-do-projeto> <raiz-do-projeto>/.docs-extract.json
# Projetos Python:
python3 <diretório-da-skill>/scripts/extract_py.py <raiz-do-projeto> <raiz-do-projeto>/.docs-extract.json
Leia references/extraction-guide.md para notas específicas de framework sobre a saída do plano B.
Passo 2: Ler o Relatório do Grafo
Leia graphify-out/GRAPH_REPORT.md por completo. Isso fornece:
- Nós principais (god nodes) — conceitos de maior grau (por onde tudo se conecta). Use-os para a seção de Arquitetura.
- Agrupamentos comunitários — agrupamentos lógicos de código relacionado. Use-os para documentação de módulos.
- Conexões surpreendentes — relações não óbvias entre arquivos. Anote-as na Arquitetura.
- Perguntas sugeridas — avaliação do graphify sobre o que vale a pena documentar.
Em seguida, execute consultas direcionadas para seções específicas da documentação:
# Rotas da API
graphify query "mostre todas as rotas e endpoints da API" --graph graphify-out/graph.json
# Modelos de dados
graphify query "quais são os principais modelos de dados e tipos?" --graph graphify-out/graph.json
# Fluxo de autenticação
graphify query "como a autenticação funciona?" --graph graphify-out/graph.json
# Pontos de entrada
graphify query "qual é o ponto de entrada e como o aplicativo é inicializado?" --graph graphify-out/graph.json
Cada consulta retorna um subgrafo focado. Relacionamentos são marcados como EXTRAÍDO (encontrado no código fonte) ou INFERIDO (com pontuação de confiança). Confie totalmente em EXTRAÍDO. Use INFERIDO, mas sinalize a incerteza.
QA: Verifique 2-3 rotas da consulta nos arquivos fonte reais antes de escrever a documentação.
Passo 3: Ler a Documentação Existente
Antes de escrever algo novo, verifique o que já existe:
- Leia
README.mdse presente. Anote quais seções existem e quais estão desatualizadas ou ausentes. - Leia
docs/API.md,docs/api.mdouAPI.mdse presente. - Leia
CHANGELOG.mdpara contexto sobre mudanças recentes que valem a pena mencionar.
Decida o que gerar:
- Sem README — gere um README completo a partir do Template 1 em
references/output-template.md - README existe, seção de API desatualizada — atualize apenas essa seção (Template 3)
- README existe, totalmente desatualizado — pergunte: "Seu README existe, mas parece desatualizado. Devo reescrever completamente ou atualizar seções específicas?"
QA: Liste exatamente o que você vai escrever ou atualizar antes de começar.
Passo 4: Gerar Documentação
Leia references/output-template.md para os templates exatos a serem usados.
README — Descrição do Projeto:
A partir da descrição em package.json ou pyproject.toml + resumo dos nós principais de GRAPH_REPORT.md.
README — Seção de Arquitetura: Use nós principais e agrupamentos comunitários para escrever uma visão geral da arquitetura em linguagem simples. Exemplo:
"O sistema está organizado em torno de 3 módulos principais:
AuthService(nó principal, conecta-se a 14 outros componentes),DatabaseAdapter(ponte para todo acesso a dados) eEventBus(central para fluxos assíncronos). Os módulos de autenticação e manipulação de requisições são fortemente acoplados; o módulo de análise é independente."
README — Instalação e Início Rápido:
A partir do arquivo de ponto de entrada + scripts em package.json ou Makefile.
Referência de API (docs/API.md):
A partir da saída de graphify query "mostre todas as rotas da API". Uma seção por recurso, agrupada por prefixo de caminho. Para cada rota: método, caminho, descrição (a partir de docstring ou nó de rationale), formato de requisição/resposta (a partir de nós de tipo vinculados), exemplo com curl.
Sinalize qualquer coisa sem docstring como [Descrição necessária]. Não invente comportamento.
QA: Verifique 3 rotas aleatórias no docs/API.md gerado contra o arquivo fonte real. Os caminhos e descrições coincidem?
Passo 5: Escrever Arquivos, Limpar e Abrir PR
- Escreva
README.mdna raiz do projeto (arquivo completo ou apenas seções atualizadas). - Escreva
docs/API.mdse rotas foram encontradas. Criedocs/se necessário. - Limpeza:
rm -rf graphify-out/ .docs-extract.json
Pergunte ao usuário: "Documentação escrita. Devo abrir um PR no GitHub com essas alterações?"
Se sim:
git checkout -b docs/auto-gerado-$(date +%Y%m%d)
git add README.md docs/
git commit -m "docs: gerar README e referência de API automaticamente a partir do codebase"
gh pr create \
--title "docs: README e referência de API gerados automaticamente" \
--body "Gerado pela skill docs-from-code usando o grafo de conhecimento graphify. Todas as rotas e tipos verificados contra o código fonte."
QA: Os arquivos foram escritos? Os caminhos existem? O PR foi aberto corretamente?
Como é uma Saída Boa
- A seção de Arquitetura explica os nós principais e relacionamentos entre módulos em linguagem simples
- Cada rota em
docs/API.mdcorresponde a um caminho real da saída da consulta graphify - O Início Rápido do README contém um trecho executável a partir dos testes ou do ponto de entrada
- Relacionamentos INFERIDOS que influenciaram descrições são anotados como "provável" ou "parece"
- Descrições ausentes são sinalizadas como
[Descrição necessária], não inventadas
Como é uma Saída Ruim
- Rotas ou funções que não aparecem nos resultados da consulta graphify
- Seção de Arquitetura genérica ("o aplicativo tem controladores, serviços e modelos")
- Exemplos usando nomes de funções ou tipos de parâmetros errados
- Arestas INFERIDAS descritas como fatos definitivos sem qualificador de confiança