jezweb/claude-skills

Gerador de Documentação de Projeto

Gere documentação estruturada do projeto analisando o código-fonte. Produz documentação que reflete o código real, não uma arquitetura aspiracional.

Quando Usar

• Novo projeto precisa de documentação inicial
• Documentação está ausente ou desatualizada
• Integrando alguém ao código-fonte
• Atualização pós-refatoração

Fluxo de Trabalho

1. Detectar Tipo de Projeto

Escaneie a raiz do projeto para determinar o tipo de projeto:

Indicador	Tipo de Projeto
wrangler.jsonc / wrangler.toml	Cloudflare Worker
vite.config.ts + src/App.tsx	React SPA
astro.config.mjs	Site Astro
next.config.js	App Next.js
package.json com hono	API Hono
src/index.ts com Hono	Servidor API
drizzle.config.ts	Possui camada de banco de dados
schema.ts ou schema/	Possui esquema de banco de dados
pyproject.toml / setup.py	Projeto Python
Cargo.toml	Projeto Rust

2. Perguntar o Que Gerar

Quais documentos devo gerar?
1. ARCHITECTURE.md — visão geral do sistema, stack, estrutura de diretórios, fluxos principais
2. API_ENDPOINTS.md — rotas, métodos, parâmetros, formatos de resposta, autenticação
3. DATABASE_SCHEMA.md — tabelas, relacionamentos, migrações, índices
4. Todos os acima

Ofereça apenas documentos que correspondam ao projeto. Não ofereça API_ENDPOINTS.md para um site estático. Não ofereça DATABASE_SCHEMA.md se não houver banco de dados.

3. Escanear o Código-fonte

Para cada documento solicitado, leia os arquivos-fonte relevantes:

ARCHITECTURE.md — escaneie:

• package.json / pyproject.toml (stack, dependências)
• Pontos de entrada (src/index.ts, src/main.tsx, src/App.tsx)
• Arquivos de configuração (wrangler.jsonc, vite.config.ts, tsconfig.json)
• Estrutura de diretórios (2 níveis principais)
• Módulos principais e suas exportações

API_ENDPOINTS.md — escaneie:

• Arquivos de rota (src/routes/, src/api/, ou inline no index)
• Arquivos de middleware (autenticação, CORS, logging)
• Tipos de requisição/resposta ou esquemas Zod
• Padrões de tratamento de erro

DATABASE_SCHEMA.md — escaneie:

• Arquivos de esquema Drizzle (src/db/schema.ts, src/schema/)
• Arquivos de migração (drizzle/, migrations/)
• Arquivos SQL brutos, se presentes
• Arquivos de seed, se presentes

4. Gerar Documentação

Escreva cada documento em docs/ (crie o diretório se não existir). Se o projeto já tiver documentação lá, ofereça atualizar em vez de sobrescrever.

Para projetos pequenos sem diretório docs/, escreva na raiz do projeto.

Modelos de Documento

ARCHITECTURE.md

# Arquitetura

## Visão Geral
[Um parágrafo: o que este projeto faz e como está estruturado]

## Stack
| Camada | Tecnologia | Versão |
|--------|------------|--------|
| Runtime | [ex.: Cloudflare Workers] | — |
| Framework | [ex.: Hono] | [versão] |
| Banco de Dados | [ex.: D1 (SQLite)] | — |
| ORM | [ex.: Drizzle] | [versão] |
| Frontend | [ex.: React 19] | [versão] |
| Estilização | [ex.: Tailwind v4] | [versão] |

## Estrutura de Diretórios
[Árvore anotada — 2 níveis principais com comentários sobre propósito]

## Fluxos Principais
### [Fluxo 1: ex.: "Autenticação do Usuário"]
[Passo a passo: requisição → middleware → handler → banco de dados → resposta]

### [Fluxo 2: ex.: "Pipeline de Processamento de Dados"]
[Passo a passo pelo sistema]

## Configuração
[Arquivos de configuração principais e o que controlam]

## Implantação
[Como implantar, variáveis de ambiente necessárias, comandos de build]

API_ENDPOINTS.md

# Endpoints da API

## URL Base
[ex.: `https://api.exemplo.com` ou relativa `/api`]

## Autenticação
[Método: Bearer token, cookie de sessão, chave de API, nenhum]
[De onde vêm os tokens, como obter]

## Endpoints

### [Grupo: ex.: Usuários]

#### `GET /api/users`
- **Autenticação**: Obrigatória
- **Parâmetros**: `?pagina=1&limite=20`
- **Resposta**: `{ usuarios: Usuario[], total: numero }`

#### `POST /api/users`
- **Autenticação**: Obrigatória (admin)
- **Corpo**: `{ nome: string, email: string }`
- **Resposta**: `{ usuario: Usuario }` (201)
- **Erros**: 400 (validação), 409 (email duplicado)

[Repita para cada endpoint]

## Formato de Erro
[Formato padrão da resposta de erro]

## Limites de Taxa
[Se aplicável]

DATABASE_SCHEMA.md

# Esquema do Banco de Dados

## Mecanismo
[ex.: Cloudflare D1 (SQLite), PostgreSQL, MySQL]

## Tabelas

### `usuarios`
| Coluna | Tipo | Restrições | Descrição |
|--------|------|------------|-----------|
| id | TEXT | PK | UUID |
| email | TEXT | UNIQUE, NOT NULL | Email do usuário |
| nome | TEXT | NOT NULL | Nome de exibição |
| criado_em | TEXT | NOT NULL, DEFAULT now | Timestamp ISO |

### `posts`
[Mesmo formato]

## Relacionamentos
[Chaves estrangeiras, padrões de junção, regras de cascata]

## Índices
[Índices não primários e por que existem]

## Migrações
- Gerar: `npx drizzle-kit generate`
- Aplicar local: `npx wrangler d1 migrations apply DB --local`
- Aplicar remoto: `npx wrangler d1 migrations apply DB --remote`

## Dados de Seed
[Referência ao script de seed, se existir]

Regras de Qualidade

1. Documente o que existe, não o que está planejado — leia o código real, não invente endpoints ou tabelas
2. Inclua versões — extraia de package.json/arquivos de bloqueio, não da memória
3. Mostre formas de resposta reais — copie de tipos TypeScript ou esquemas Zod no código
4. Mantenha escaneável — tabelas em vez de parágrafos, blocos de código em vez de prosa
5. Não duplique CLAUDE.md — se a informação de arquitetura já estiver em CLAUDE.md, mova-a para ARCHITECTURE.md ou faça referência a ela
6. Sinalize lacunas — se você encontrar rotas não documentadas ou tabelas sem propósito claro, anote-as com <!-- TODO: documentar propósito -->

Atualizando Documentação Existente

Se a documentação já existir:

1. Leia o documento existente
2. Diferencie do código-fonte atual
3. Mostre ao usuário o que mudou (novos endpoints, tabelas removidas, stack atualizado)
4. Aplique atualizações preservando quaisquer notas ou seções escritas à mão

Nunca sobrescreva silenciosamente conteúdo personalizado que o usuário adicionou à sua documentação.