Se você já herdou documentação incompleta, inconsistente e desatualizada, você conhece o problema: as equipes criam documentos com boas intenções, mas sem uma revisão rigorosa, a clareza se perde. Parâmetros de API ficam indocumentados. Respostas de erro carecem de orientação. Exemplos quebram silenciosamente. A terminologia varia entre os arquivos.
Claude Code Skills resolvem isso sistematicamente. Esses fluxos de trabalho baseados em IA revisam todo o seu repositório de documentação, identificam lacunas e inconsistências e aplicam correções diretamente. Você descreve o que precisa ser revisado, e o Claude gera uma auditoria estruturada, aplica melhorias e valida a completude, tudo a partir do seu terminal.
A documentação técnica abrange especificações de API, guias do usuário, guias de implantação e notas de lançamento. O Claude Code automatiza a revisão de tudo isso. Especificamente para a documentação de API, combine-o com o Apidog para validação visual e pontuação de completude.
Compreendendo os Claude Code Skills para Documentação
O Que São Documentação Skills?
Claude Code Skills são fluxos de trabalho de IA personalizados e reutilizáveis que estendem as capacidades de documentação do Claude Code. Pense neles como auditores de documentação inteligentes que podem:
- Ler todo o seu repositório de documentação e entender o contexto
- Fazer referências cruzadas de especificações com implementações e guias
- Identificar seções ausentes, linguagem pouco clara e inconsistências
- Sugerir melhorias específicas com localizações de arquivos e números de linha
- Aplicar correções diretamente aos seus arquivos e validar as alterações
Ao contrário dos linters tradicionais que verificam a sintaxe, as skills aproveitam o raciocínio do Claude para entender problemas semânticos – descrições vagas, documentação de erro ausente, exemplos inconsistentes.
Como as Skills Funcionam
As skills operam através de vários mecanismos:
1. Comandos Invocáveis pelo Usuário
# Executa uma skill com um comando de barra
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples
2. Ferramentas Permitidas
As skills especificam quais ferramentas podem usar:
Bash: Executa comandos de validaçãoRead,Write,Edit: Gerencia arquivos de documentaçãoGlob,Grep: Busca em documentosWebFetch: Recupera referências externasTask: Gera subtarefas para revisões complexas
3. Arquivos de Planejamento
As skills mantêm o estado usando arquivos markdown para rastrear o progresso da revisão, problemas identificados e correções aplicadas.
Por Que as Skills Se Destacam na Revisão de Documentação
A revisão tradicional de documentação é manual e inconsistente. As skills trazem inteligência e escala:
- Compreensão Holística: Revisa todos os arquivos, captura padrões entre arquivos
- Padrões Consistentes: Aplica os mesmos critérios de qualidade a cada arquivo
- Sugestões Contextuais: Entende por que algo está errado, não apenas que está
- Automação: Pode revisar continuamente conforme a documentação evolui
- Velocidade: Analisa centenas de páginas em minutos versus horas de revisão manual
Capacidades Centrais de Revisão de Documentação
1. Análise de Completude
Prompt: "Audite a documentação da API para completude. Verifique cada endpoint para: parâmetros, exemplos de requisição, todas as respostas de erro e limitação de taxa."
Claude gera:
Ausente do endpoint POST /users:
- [ ] Descrições dos parâmetros do corpo da requisição
- [ ] Documentação da resposta de erro (400, 401, 409)
- [ ] Informações sobre limitação de taxa
- [ ] Requisitos de segurança/autenticação
2. Detecção de Consistência
Prompt: "Revise /docs/ para consistência de terminologia. Sinalize quaisquer termos que apareçam várias vezes com significados diferentes."
Claude identifica:
Terminologia inconsistente encontrada:
- "API key" vs "access token" vs "auth token" (use um)
- "endpoint" vs "route" vs "method" (use um)
- "user object" vs "user resource" (use um)
3. Validação de Referência Cruzada
Prompt: "Compare a especificação OpenAPI em /api/openapi.yaml com a documentação em /docs/api/. Sinalize quaisquer endpoints no código não documentados ou documentados mas não no código."
Claude detecta:
Discrepâncias encontradas:
- POST /api/webhooks documentado mas não em openapi.yaml
- PATCH /api/users existe no código mas está ausente na documentação
- Esquema de resposta alterado mas exemplo não atualizado
4. Avaliação de Clareza
Prompt: "Revise para clareza. Sinalize descrições vagas, termos indefinidos e instruções ambíguas."
Claude identifica:
Problemas de clareza:
- Linha 45: "Defina a configuração para valores apropriados" - que valores?
- Linha 120: "user object" usado sem definição de esquema
- Linha 200: "campos obrigatórios" - quais?
5. Validação de Exemplo
Prompt: "Revise todos os exemplos de código. Teste-os contra o esquema de API atual. Sinalize exemplos quebrados ou desatualizados."
Claude atualiza:
Exemplos atualizados:
- Exemplo curl: Formato de resposta alterado, payload atualizado
- Exemplo Python: Usando parâmetro obsoleto, corrigido
- Exemplo JavaScript: Faltando tratamento de erros, adicionado
Anatomia de uma Skill de Documentação
Estrutura de Diretórios
As skills de documentação residem em .claude/skills/ com esta estrutura:
.claude/
├── skills/
│ ├── docs-completeness/
│ │ ├── SKILL.md # Manifesto da Skill
│ │ ├── planning.md # Progresso da revisão
│ │ └── criteria.md # Lista de verificação de qualidade
│ ├── api-validation/
│ │ ├── SKILL.md
│ │ └── schemas/ # Esquemas de API
│ └── consistency-check/
│ └── SKILL.md
└── skills.md # Índice de todas as skills
O Manifesto SKILL.md
Cada skill de documentação começa com um frontmatter YAML:
---
name: docs-completeness
version: "1.0.0"
description: Revisa a documentação para completude e clareza
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Glob
- Edit
hooks:
SessionStart:
- matcher: command
command: "echo '[Docs Review] Iniciando auditoria de documentação...'"
Stop:
- matcher: command
command: "echo '[Docs Review] Auditoria completa. Revise as descobertas acima.'"
---
# Skill de Completude da Documentação
Revisa a documentação técnica para completude e clareza.
## Uso
```bash
/docs-completeness # Auditoria completa do repositório
/docs-completeness --api-only # Somente docs da API
/docs-completeness --section api/endpoints.md # Arquivo específico
Instruções para o Claude
Quando invocado:
- Detecção de escopo → Determinar arquivos alvo ou repositório completo
- Análise de completude → Verificar cada seção contra a lista de verificação
- Coleta de problemas → Reunir todos os problemas com referências de localização
- Priorização → Classificar por impacto (ausente vs. pouco claro vs. inconsistente)
- Geração de relatório → Gerar descobertas estruturadas
- Sugestões de correção → Oferecer melhorias específicas
- Validação → Verificar correções antes de aplicar
Criando Sua Primeira Skill de Documentação
Mãos à obra: Construiremos uma ferramenta útil para auditar a documentação da API em busca de lacunas, garantindo que seja abrangente e pronta para desenvolvedores. Pense nisso como seu executor pessoal de documentos.
Passo 1: Configure a Pasta da Skill
Bootstrap a estrutura com um comando simples. As skills do Claude vivem em um local dedicado para fácil descoberta.
Bash
mkdir -p .claude/skills/api-docs-reviewPasso 2: Escreva o Manifesto da Skill
Crie .claude/skills/api-docs-review/SKILL.md:
---
name: api-docs-review
version: "1.0.0"
description: Revisa a documentação da API para completude
user-invocable: true
allowed-tools:
- Read
- Write
- Grep
- Edit
---
# Skill de Revisão da Documentação da API
Audita a documentação da API para completude, clareza e precisão.
## Critérios de Revisão
Cada endpoint deve ter:
**Informações Básicas**
* Descrição clara do que o endpoint faz
* Método HTTP e caminho
* Requisitos de autenticação
**Documentação da Requisição**
* Todos os parâmetros de caminho com tipos e descrições
* Todos os parâmetros de consulta com valores padrão e restrições
* Esquema do corpo da requisição (para POST/PUT/PATCH)
* Requisitos do cabeçalho Content-Type
* Exemplo de requisição (curl ou específico da linguagem)
**Documentação da Resposta**
* Resposta de sucesso (200/201) com esquema e exemplo
* Todas as respostas de erro (400, 401, 403, 404, 409, 429, 500) com exemplos
* Informações sobre limitação de taxa
* Cabeçalhos de resposta (se relevantes)
**Adicional**
* Endpoints ou guias relacionados
* Histórico de versões, se aplicável
* Avisos de depreciação (se obsoleto)
## Instruções
Quando invocado:
1. **Escaneie arquivos de endpoint** em /docs/api/
2. **Verifique cada endpoint** contra os critérios de revisão
3. **Registre itens ausentes** com referências específicas de arquivo/linha
4. **Identifique problemas de clareza** (descrições vagas, termos indefinidos)
5. **Sinalize problemas de consistência** (deriva de terminologia, diferenças de formato)
6. **Gere lista de verificação** de correções necessárias
7. **Ofereça para aplicar correções** com exemplos
Formato do relatório:
ENDPOINT: POST /api/users Arquivo: docs/api/users.md Status: 65% Completo
Ausente:
- [ ] Documentação da resposta de erro (400, 401, 409)
- [ ] Informações sobre limitação de taxa
- [ ] Definição do esquema do corpo da requisição
Problemas:
- Linha 45: "user object" indefinido - adicionar link para o esquema
- Linha 60: Exemplo desatualizado - formato de resposta alterado
Correções disponíveis: Sim (perguntar para aplicar)
Passo 3: Registre a Skill
Adicione em .claude/skills.md:
# Skills de Documentação Disponíveis
## Documentação da API
### /api-docs-review
Audita a documentação da API para completude contra critérios padrão.
- **Versão**: 1.0.0
- **Uso**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **Quando usar**: Antes do lançamento da API, após alterações no código
- **Tempo**: 5-10 minutos para API de tamanho médio
Passo 4: Teste a Skill
# No Claude Code
/api-docs-review
O Claude agora auditará sua documentação de API sistematicamente.
Padrões Avançados de Documentação
Padrão 1: Rastreamento de Documentação Versionada
As skills podem rastrear a qualidade da documentação entre as versões:
## Histórico de Versões
### v2.0.0 [2026-01-22]
Completude: 95% ✅
- Todos os endpoints documentados
- Respostas de erro completas
- Exemplos atualizados
- Endpoints /v1 obsoletos marcados
### v1.0.0 [2025-12-01]
Completude: 70%
- Documentação de erro ausente
- Exemplos desatualizados
- Sem avisos de depreciação
O Claude detecta melhorias ao longo do tempo.
Padrão 2: Validação da Especificação da API Contra o Código
As skills podem validar se as especificações OpenAPI correspondem à implementação:
## Validação de Especificação
Compare /api/openapi.yaml com o código:
1. **Escaneie a implementação** para todas as rotas
2. **Verifique a especificação OpenAPI** para cada rota
3. **Sinalize endpoints** ausentes
4. **Verifique se os parâmetros** correspondem à implementação
5. **Atualize exemplos** para corresponder ao esquema atual
Resultado: Especificação 100% sincronizada com o código
Automatizando com CI/CD
Pipeline de Validação de Documentação
Configure verificações automatizadas em cada atualização de documentação:
# .github/workflows/docs-check.yml
name: Verificação de Documentação
on:
push:
paths:
- 'docs/**'
- 'api/openapi.yaml'
pull_request:
paths:
- 'docs/**'
- 'api/openapi.yaml'
jobs:
validate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Instalar Apidog CLI
run: npm install -g apidog-cli
- name: Validar Especificação OpenAPI
run: |
apidog lint api/openapi.yaml
apidog check-completeness api/openapi.yaml --min-score 85
- name: Verificar links quebrados
run: |
npm install -g markdown-link-check
find docs -name "*.md" -exec markdown-link-check {} \;
- name: Verificar se os exemplos são válidos
run: |
# Testar se os exemplos curl funcionam
bash scripts/test-curl-examples.sh
- name: Comentar no PR
if: failure()
uses: actions/github-script@v7
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: '❌ A validação da documentação falhou. Revise os logs do fluxo de trabalho.'
})
Cenário do Mundo Real: Completude da Documentação da API
Vamos auditar um conjunto de documentação de API realista para completude e aplicar melhorias.
O Cenário
Você tem documentação de API REST com 6 meses de idade. Está parcialmente completa, mas falta documentação de erro, é pouco clara em alguns pontos e tem exemplos desatualizados.
A Auditoria
Prompt para o Claude: "Audite a documentação em /docs/api/. Para cada endpoint, verifique: descrição, parâmetros de requisição, exemplo de resposta e todas as respostas de erro. Priorize as correções por impacto."
RESULTADOS DA AUDITORIA
=============
CRÍTICO (Docs de erro ausentes):
├── POST /api/users - Respostas de erro 400, 401, 409 ausentes
├── POST /api/auth/login - Resposta 429 (limite de taxa) ausente
└── DELETE /api/resources/{id} - Resposta 403 (proibido) ausente
ALTO (Problemas de clareza):
├── users.md:45 - "user object" indefinido
├── auth.md:60 - "Defina a expiração para o valor apropriado" - muito vago
└── resources.md:30 - Descrição ausente do formato do cursor de paginação
MÉDIO (Exemplos desatualizados):
├── products.md:120 - Exemplo cURL retorna formato antigo
├── orders.md:80 - Exemplo do SDK Python usa parâmetro obsoleto
└── webhooks.md:60 - Exemplo Node.js sem tratamento de erros
CONSISTÊNCIA:
├── "API key" vs "access token" - 5 instâncias inconsistentes
├── Formato do corpo da requisição - 3 estilos diferentes entre endpoints
└── Esquema de resposta de erro - 2 variações em vez de 1
Correções prioritárias: 15 no total
Esforço estimado: 2-3 horas manual, 15 minutos com Claude Code
As Melhorias
Aplicando correções sistematicamente:
Antes - POST /api/users (Incompleto):
## Criar Usuário
POST /api/users
Cria um novo usuário.
**Parâmetros:**
- name: Nome do usuário
- email: E-mail do usuário
**Resposta:**
```json
{
"id": "usr_123",
"name": "Alice",
"email": "alice@example.com"
}
**Depois - POST /api/users (Completo):**
```markdown
## Criar Usuário
`POST /api/users`
Cria uma nova conta de usuário com os detalhes fornecidos. O e-mail deve ser único.
### Autenticação
Requer chave de API no cabeçalho `Authorization`: `Bearer SUA_CHAVE_API`
### Parâmetros da Requisição
| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-------------|
| `name` | string | Sim | Nome completo (2-100 caracteres) |
| `email` | string | Sim | E-mail válido (deve ser único) |
| `role` | string | Não | Papel: `admin`, `developer`, `viewer`. Padrão: `viewer` |
### Exemplo de Requisição
```bash
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer sk_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer"
}'
Resposta (201 Created)
{
"id": "usr_abc123",
"name": "Alice Smith",
"email": "alice@example.com",
"role": "developer",
"created_at": "2026-01-22T10:30:00Z"
}
Respostas de Erro
400 Bad Request - Entrada inválida
{
"error": "validation_error",
"message": "Formato de e-mail inválido",
"field": "email",
"request_id": "req_xyz789"
}
401 Unauthorized - Chave de API ausente/inválida
{
"error": "unauthorized",
"message": "Chave de API inválida",
"request_id": "req_xyz789"
}
409 Conflict - E-mail já existe
{
"error": "conflict",
"message": "Usuário com este e-mail já existe",
"request_id": "req_xyz789"
}
429 Too Many Requests - Limite de taxa excedido
{
"error": "rate_limited",
"message": "Muitas requisições. Tente novamente em 60 segundos.",
"retry_after": 60,
"request_id": "req_xyz789"
}
Limitação de Taxa
100 requisições por minuto por chave de API. Veja Limites de Taxa.
**Melhorias aplicadas:**
- Adicionado requisitos de autenticação
- Documentado todos os parâmetros com restrições
- Sucesso completo + todas as respostas de erro
- Exemplo cURL pronto para produção
- Informações sobre limitação de taxa
- Formatação consistente
Integrando Claude com Apidog para Documentação de API Superior
💡 Dica Profissional: Utilize o Claude para revisões perspicazes de documentos narrativos, enquanto o Apidog garante que suas especificações de API estejam sólidas e preenche automaticamente as lacunas com exemplos práticos.
Prompt Sugerido para Claude:"Examine /docs/api/ para clareza geral e engajamento. Em seguida, faça uma verificação cruzada da completude do arquivo /api/openapi.yaml usando o Apidog. Destaque quaisquer inconsistências ou elementos ausentes, para que eu possa resolvê-los diretamente no Apidog antes de prosseguir."
Bash
# Passo 1: Revisão Inicial de Prosa via Claude
> /docs-completeness # Gera sugestões para linguagem e estrutura mais claras
# Passo 2: Validação da Especificação da API no Apidog
apidog check-completeness api/openapi.yaml # Sinaliza problemas como esquemas incompletos ou respostas ausentes
# Passo 3: Geração Automática de Conteúdo com IA do Apidog
# (Via UI do Apidog: Configurações → AI → Gerar descrições, exemplos e resumos automaticamente)
# Passo 4: Verificação Final de Harmonia com Claude
> /consistency-check # Garante que docs e spec estejam perfeitamente alinhadosIsso cria um fluxo de trabalho onde o Apidog lida com a validação estruturada da especificação e o Claude Code cuida da qualidade da prosa.
Melhores Práticas para Revisão de Documentação
Conheça Seu Público
Adapte a profundidade da documentação aos leitores:
| Público | Estilo | Exemplo |
|---|---|---|
| Desenvolvedores | Exemplos de código em várias linguagens | cURL, Python, JS |
| DevOps | Etapas de implantação, configuração | Exemplos de YAML do Kubernetes |
| Equipes de Produto | Fluxos de trabalho de alto nível, diagramas | Fluxos de recursos com capturas de tela |
| Suporte | Solução de problemas, problemas comuns | "Erro 429 significa..." |
Priorize a Clareza
Escreva na voz ativa, estruture para leitura rápida:
❌ Antes: "A requisição é submetida via POST. A resposta conterá o usuário."
✅ Depois: "Envie uma requisição POST para criar um usuário. A API retorna o novo usuário."
Sempre Inclua Exemplos
Conceitos abstratos precisam de ancoragem. Cada endpoint de API precisa de:
# ✅ Pronto para copiar e colar
curl -X GET https://api.example.com/v1/users/usr_123 \
-H "Authorization: Bearer SUA_CHAVE_API"
Armadilhas Comuns
| Armadilha | Solução |
|---|---|
| Excesso de jargão | Defina os termos no primeiro uso |
| Exemplos desatualizados | Teste em CI/CD |
| Documentação de erro ausente | Documente todos os códigos de erro |
| Formatação inconsistente | Use modelos |
| Links quebrados | Verifique em CI/CD |
Conclusão
As Claude Code Skills transformam a revisão de documentação técnica de um processo manual tedioso em um fluxo de trabalho inteligente e automatizado. Você descreve o que precisa ser revisado, e o Claude audita todo o seu repositório de documentação, identifica lacunas e inconsistências e aplica correções, tudo isso mantendo os padrões de qualidade.
Combinado com o Apidog para validação de especificação de API, você alcança uma cobertura abrangente da documentação.