docs
Propósito
Gerenciador do ciclo de vida da documentação. Gera a documentação inicial do projeto, mantém os documentos sincronizados com as alterações de código, produz referências de API e gera changelogs automaticamente. Resolve o problema número 1 da documentação: documentos que existem, mas estão desatualizados.
Gatilhos
- Chamado por
scaffoldFase 7 para geração inicial de documentação - Chamado por
cookpós-Fase 7 para atualizar documentos após implementação de funcionalidades - Chamado por
launchpré-deploy para garantir que os documentos estejam atualizados /rune docs init— geração de documentação pela primeira vez/rune docs update— sincronizar documentos com alterações recentes de código/rune docs api— gerar documentação de API/rune docs changelog— gerar changelog automaticamente a partir do histórico do git
Chamadas (saída)
scout(L2): escanear o código-fonte em busca de alvos de documentação (rotas, exports, componentes, configurações)doc-processor(L3): gerar exportações PDF/DOCX se solicitadogit(L3): ler o histórico de commits para geração de changelog
Chamado Por (entrada)
scaffold(L1): Fase 7 — gerar documentos iniciais para novo projetocook(L1): pós-implementação — atualizar documentos para módulos alteradoslaunch(L1): pré-deploy — verificar se os documentos estão atualizadosmcp-builder(L2): gerar documentação do servidor MCP- Usuário:
/rune docsinvocação direta
Modos
Modo Init — /rune docs init
Geração de documentação pela primeira vez para um projeto.
Modo Update — /rune docs update
Sincronização incremental — atualiza apenas os documentos afetados por alterações recentes de código.
Modo API — /rune docs api
Gerar ou atualizar a documentação da API especificamente.
Modo Changelog — /rune docs changelog
Gerar changelog automaticamente a partir do histórico de commits do git.
Etapas Executáveis
Modo Init
Etapa 1 — Escanear o Código-Fonte
Invocar rune:scout para extrair:
- Nome do projeto, descrição, stack tecnológica
- Estrutura de diretórios e arquivos-chave
- Pontos de entrada (main, index, app)
- Superfície da API pública (exports, rotas, componentes)
- Arquivos de configuração (.env.example, padrões de configuração)
- Documentos existentes (se houver — fazer merge, não sobrescrever)
Etapa 2 — Gerar README.md
Estrutura:
# [Nome do Projeto]
[Descrição em uma linha]
## Início Rápido
[3-5 comandos para começar: instalar, configurar, iniciar]
## Funcionalidades
[Lista com marcadores extraída do código — rotas, componentes, capacidades]
## Stack Tecnológica
[Detectado a partir de package.json, requirements.txt, Cargo.toml, etc.]
## Estrutura do Projeto
[Diretórios principais com descrições em uma linha]
## Configuração
[Variáveis de ambiente do .env.example com descrições]
## Desenvolvimento
[Comandos de servidor dev, teste, lint, build]
## Referência da API
[Link para API.md se aplicável, ou resumo inline]
## Licença
[Detectado a partir do arquivo LICENSE ou package.json]
Etapa 3 — Gerar ARCHITECTURE.md (se o projeto tiver 10+ arquivos)
Estrutura:
# Arquitetura
## Visão Geral
[Diagrama de sistema em texto/mermaid — componentes e fluxo de dados]
> A visão geral da ARQUITETURA pode chamar `rune:diagram` para uma figura de sistema projetada (tipo `architecture`) em vez de Mermaid bruto — `suggested_next: diagram`.
## Decisões-chave
[Padrões detectados: escolha de framework, gerenciamento de estado, banco de dados, abordagem de autenticação]
## Mapa de Módulos
[Cada diretório de nível superior: propósito, arquivos-chave, dependências]
## Fluxo de Dados
[Descrição do ciclo de vida da requisição ou pipeline de dados]
Etapa 4 — Gerar API.md (se rotas/endpoints detectados)
Escaneie os arquivos de rota e extraia:
- Método HTTP + caminho
- Parâmetros da requisição (caminho, query, corpo)
- Forma da resposta
- Requisitos de autenticação
- Respostas de erro
Formate como tabela markdown ou referência compatível com OpenAPI.
Etapa 5 — Relatório
Apresente os documentos gerados ao usuário com um resumo:
- Arquivos gerados: [lista]
- Cobertura: [o que está documentado vs o que existe]
- Lacunas: [áreas de código sem documentação — sugerir próximos passos]
Modo Update
Etapa 1 — Detectar Alterações
Ler git diff desde a última atualização de documentos (rastreada via git log nos arquivos de doc ou .rune/docs-sync.json).
Identificar:
- Novos arquivos/módulos → precisam de novas seções de doc
- Funções/rotas alteradas → precisam de atualizações de doc
- Código deletado → precisa de remoção da doc
- Nova configuração → precisa de atualização da doc de configuração
Etapa 2 — Atualizar Seções Afetadas
Para cada área alterada:
- Ler o código alterado
- Encontrar a seção de documentação correspondente
- Atualizar a documentação para corresponder ao código atual
- Se a seção de documentação não existir → criá-la
- Se o código foi deletado → remover ou marcar como obsoleto na documentação
Etapa 3 — Gerar Entrada de Changelog
Delegar a rune:git changelog para produzir uma entrada de changelog a partir dos commits desde a última atualização de documentos.
Etapa 4 — Passagem de Consistência entre Documentos
A consistência entre documentos evita o segundo problema mais comum de documentação: documentos que existem, mas se contradizem.
Após atualizar qualquer documento, verifique a consistência em toda a documentação do projeto:
| Verificação | Arquivos | O que Comparar |
|---|---|---|
| Números de versão | README, CLAUDE.md, package.json, CHANGELOG | Todos devem corresponder à versão atual |
| Listas de funcionalidades | README, landing page, CLAUDE.md | Mesmas funcionalidades listadas (podem diferir no nível de detalhe) |
| Estatísticas | README, CLAUDE.md, landing page, dashboard | Número de habilidades, contagem de testes, contagem de sinais devem corresponder |
| Comandos | README, CLAUDE.md, docs/ | Mesmos comandos com os mesmos flags |
| Stack tecnológico | README, ARCHITECTURE.md, CLAUDE.md | Referências consistentes a frameworks/bibliotecas |
Consistência entre Docs:
- [x] README.md ↔ CLAUDE.md: versões correspondem, comandos correspondem
- [x] README.md ↔ docs/index.html: estatísticas correspondem, funcionalidades correspondem
- [ ] README.md diz "62 habilidades" mas CLAUDE.md diz "59" → CORRIGIR CLAUDE.md
Corrigir inconsistências imediatamente — não apenas relatá-las. Atualizar o documento desatualizado para corresponder à fonte da verdade (normalmente o código ou o documento mais recentemente atualizado).
Etapa 5 — Relatório
Mostrar ao usuário: o que foi atualizado, o que foi adicionado, o que foi sinalizado para revisão. Incluir resultados da Consistência entre Documentos.
Modo API
Etapa 1 — Detectar Framework de API
| Framework | Padrão de Rota | Padrão de Arquivo |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
Etapa 2 — Extrair Endpoints
Para cada rota detectada:
- Método (GET, POST, PUT, DELETE, PATCH)
- Caminho (com parâmetros destacados)
- Requisição: parâmetros, query, forma do corpo (de schemas Zod, tipos TypeScript, modelos Pydantic)
- Resposta: forma (do tipo de retorno ou helper de resposta)
- Autenticação: necessária? (detectar middleware como
authMiddleware,@UseGuards) - Descrição: de JSDoc/docstring se disponível
Etapa 3 — Gerar Referência da API
Formato como markdown:
# Referência da API
## Autenticação
[Descrição do mecanismo de autenticação]
## Endpoints
### `POST /api/auth/login`
**Descrição**: Autenticar usuário e retornar tokens
**Autenticação**: Nenhuma
**Corpo da Requisição**:
| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| email | string | sim | Email do usuário |
| password | string | sim | Senha do usuário |
**Resposta** (200):
```json
{ "token": "string", "refreshToken": "string" }
Erros:
- 401: Credenciais inválidas
- 422: Erro de validação
#### Etapa 4 — Saída
Salvar em `docs/API.md` ou local específico do projeto. Se OpenAPI for solicitado, gerar `openapi.yaml`.
### Modo Changelog
#### Etapa 1 — Delegar ao Git
Invocar `rune:git changelog` para agrupar commits por tipo e formatar como Keep a Changelog.
#### Etapa 2 — Aprimorar
Adicionar contexto ao changelog bruto:
- Vincular números de PR a descrições reais
- Agrupar alterações relacionadas sob cabeçalhos de funcionalidades
- Destacar alterações de quebra (breaking changes) de forma proeminente
#### Etapa 3 — Saída
Anexar ou atualizar `CHANGELOG.md`.
## Formato de Saída
### Saída do Modo Init
Arquivos gerados na raiz do projeto:
- `README.md` — Início Rápido, Funcionalidades, Stack Tecnológica, Estrutura, Configuração, Comandos de Desenvolvimento
- `ARCHITECTURE.md` — Diagrama de Visão Geral, Decisões-chave, Mapa de Módulos, Fluxo de Dados (se 10+ arquivos)
- `docs/API.md` — Referência de endpoint com método, caminho, parâmetros, resposta, autenticação (se rotas detectadas)
### Saída do Modo Update
Seções de documentação modificadas com resumo das alterações:
Relatório de Atualização de Documentos:
- Atualizado: [lista de seções de documentos modificadas]
- Adicionado: [novas seções para novo código]
- Sinalizado: [seções desatualizadas referenciando código deletado]
- Changelog: [entrada anexada a CHANGELOG.md]
### Saída do Modo API
`docs/API.md` — referência markdown por endpoint:
METHOD /path/:param
Descrição: [de JSDoc/docstring] Autenticação: [necessária/nenhuma] Requisição: [tabela de parâmetros, query, corpo] Resposta: [forma com códigos de status] Erros: [códigos de erro e descrições]
### Saída do Modo Changelog
`CHANGELOG.md` — formato Keep a Changelog agrupado por: Adicionado, Corrigido, Alterado, Removido.
## Restrições
1. DEVE gerar documentos a partir do código real — nunca inventar funcionalidades ou APIs que não existem
2. DEVE preservar documentos existentes — atualizar seções, não sobrescrever arquivos inteiros
3. DEVE detectar documentos desatualizados — sinalizar seções que referenciam código deletado/alterado
4. DEVE incluir Início Rápido em todo README — usuários precisam começar a usar em < 2 minutos
5. NÃO DEVE gerar documentos para código que ainda não existe (a menos que esteja criando documentos de especificação explicitamente)
6. Documentos de API DEVEM corresponder às assinaturas reais das rotas — documentação de API errada é pior do que nenhuma documentação
## Retornos
| Artefato | Formato | Localização |
|----------|---------|-------------|
| README.md | Markdown | raiz do projeto |
| ARCHITECTURE.md | Markdown | raiz do projeto (se 10+ arquivos) |
| Referência da API | Markdown | `docs/API.md` |
| Entrada de Changelog | Markdown (Keep a Changelog) | `CHANGELOG.md` |
| Relatório de atualização de documentos | Markdown | inline (saída do chat) |
**Barreira de escopo:** Documenta apenas o que existe no código-fonte — nunca inventa funcionalidades, endpoints ou APIs.
## Pontos Críticos
| Modo de Falha | Gravidade | Mitigação |
|---|---|---|
| Inventar endpoints de API que não existem | CRÍTICO | Restrição 1: escanear arquivos de rota reais, não adivinhar |
| Sobrescrever seções de README escritas pelo usuário | ALTA | Restrição 2: fazer merge, não sobrescrever — detectar seções personalizadas |
| Documentos desatualizados após alterações de código | ALTA | Modo Update detecta diffs e atualiza seções afetadas |
| Documentos de API com formas de requisição/resposta erradas | ALTA | Extrair de tipos Zod/Pydantic/TypeScript, não da memória |
| Seção de Início Rápido ausente | MÉDIA | Restrição 4: todo README tem Início Rápido |
| Changelog com links de PR órfãos | BAIXA | Validar se os números de PR existem antes de vincular |
| Inconsistência entre documentos (README diz X, CLAUDE.md diz Y) | ALTA | Etapa 7: Passagem de Consistência entre Documentos — verificar estatísticas, versões e listas de funcionalidades em todos os documentos |
| Atualizar um documento mas não outros (desvio de estatísticas) | ALTA | Após qualquer atualização de documento, verificar todos os documentos relacionados para estatísticas desatualizadas — especialmente README ↔ CLAUDE.md ↔ landing page |
## Feito Quando
### Modo Init
- Código-fonte escaneado com scout
- README.md gerado com Início Rápido, Funcionalidades, Stack Tecnológica, Estrutura
- ARCHITECTURE.md gerado (se 10+ arquivos)
- API.md gerado (se rotas detectadas)
- Relatório de cobertura apresentado ao usuário
### Modo Update
- Alterações desde a última atualização de documentos detectadas
- Seções de documentos afetadas atualizadas
- Entrada de changelog gerada
- Relatório de atualização apresentado ao usuário
### Modo API
- Framework de API detectado
- Todos os endpoints extraídos com método, caminho, requisição, resposta
- Referência da API gerada em markdown
- Salva em docs/API.md
### Modo Changelog
- Commits agrupados por tipo
- Formatados como Keep a Changelog
- CHANGELOG.md atualizado
## Perfil de Custo
~2000-5000 tokens de entrada, ~1000-3000 tokens de saída. Sonnet — documentação requer compreensão de padrões de código, mas não raciocínio arquitetural profundo.