Communitygithub.com

Rune-kit/rune

Gera e mantém automaticamente a documentação do projeto. Cria README, documentação de API, documentação de arquitetura, changelogs e os mantém sincronizados com as alterações de código. A skill de "documentação nunca desatualizada".

O que é rune?

Esta skill gerencia todo o ciclo de vida da documentação de projetos de software. Ela resolve o problema mais comum de documentação: documentos que existem, mas estão desatualizados. Ao ser acionada, a skill escaneia o código-fonte real para extrair informações precisas sobre nomes de projetos, estrutura de diretórios, endpoints de API, configurações e muito mais, gerando arquivos como `README.md`, `ARCHITECTURE.md`, `docs/API.md` e `CHANGELOG.md`. Suporta os modos Init (para projetos novos), Update (para sincronização incremental), API (para documentação específica de endpoints) e Changelog (a partir do histórico do Git). A skill impõe regras rigorosas para nunca inventar funcionalidades ou APIs que não existem, sempre preservar documentação existente (fazendo merge, não sobrescrevendo) e realizar uma verificação de consistência entre documentos para garantir que versões, listas de recursos e comandos estejam alinhados entre todos os arquivos de documentação. Ela é chamada por skills de scaffolding (`scaffold`), de implementação (`cook`), de lançamento (`launch`) e diretamente pelo usuário através de comandos como `/rune docs init`.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Rune-kit/rune/tree/HEAD/skills/docs

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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 scaffold Fase 7 para geração inicial de documentação
  • Chamado por cook pós-Fase 7 para atualizar documentos após implementação de funcionalidades
  • Chamado por launch pré-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 solicitado
  • git (L3): ler o histórico de commits para geração de changelog

Chamado Por (entrada)

  • scaffold (L1): Fase 7 — gerar documentos iniciais para novo projeto
  • cook (L1): pós-implementação — atualizar documentos para módulos alterados
  • launch (L1): pré-deploy — verificar se os documentos estão atualizados
  • mcp-builder (L2): gerar documentação do servidor MCP
  • Usuário: /rune docs invocaçã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:

  1. Ler o código alterado
  2. Encontrar a seção de documentação correspondente
  3. Atualizar a documentação para corresponder ao código atual
  4. Se a seção de documentação não existir → criá-la
  5. 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çãoArquivosO que Comparar
Números de versãoREADME, CLAUDE.md, package.json, CHANGELOGTodos devem corresponder à versão atual
Listas de funcionalidadesREADME, landing page, CLAUDE.mdMesmas funcionalidades listadas (podem diferir no nível de detalhe)
EstatísticasREADME, CLAUDE.md, landing page, dashboardNúmero de habilidades, contagem de testes, contagem de sinais devem corresponder
ComandosREADME, CLAUDE.md, docs/Mesmos comandos com os mesmos flags
Stack tecnológicoREADME, ARCHITECTURE.md, CLAUDE.mdReferê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

FrameworkPadrão de RotaPadrão de Arquivo
Expressrouter.get/post/put/deleteroutes/*.ts, *.router.ts
FastAPI@app.get/post/put/deleterouters/*.py, main.py
NestJS@Get/@Post/@Put/@Delete*.controller.ts
Next.js Appexport async function GET/POSTapp/**/route.ts
Next.js Pagesexport default function handlerpages/api/**/*.ts
SvelteKitexport function GET/POSTsrc/routes/**/+server.ts
Honoapp.get/post/put/deletesrc/*.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.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas