affaan-m--everything-claude-code/docs/pt-BR/commands/update-docs.md

Atualizar Documentação

Sincronize a documentação com o codebase, gerando a partir de arquivos fonte da verdade.

Passo 1: Identificar Fontes da Verdade

Source	Generates
package.json scripts	Available commands reference
.env.example	Environment variable documentation
openapi.yaml / route files	API endpoint reference
Source code exports	Public API documentation
Dockerfile / docker-compose.yml	Infrastructure setup docs

Passo 2: Gerar Referência de Scripts

1. Leia package.json (ou Makefile, Cargo.toml, pyproject.toml)
2. Extraia todos os scripts/comandos com suas descrições
3. Gere uma tabela de referência:

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Production build with type checking |
| `npm test` | Run test suite with coverage |

Passo 3: Gerar Documentação de Ambiente

1. Leia .env.example (ou .env.template, .env.sample)
2. Extraia todas as variáveis e seus propósitos
3. Categorize como required vs optional
4. Documente formato esperado e valores válidos

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |

Passo 4: Atualizar Guia de Contribuição

Gere ou atualize docs/CONTRIBUTING.md com:

• Setup do ambiente de desenvolvimento (pré-requisitos, passos de instalação)
• Scripts disponíveis e seus propósitos
• Procedimentos de teste (como rodar, como escrever novos testes)
• Enforcement de estilo de código (linter, formatter, hooks pre-commit)
• Checklist de submissão de PR

Passo 5: Atualizar Runbook

Gere ou atualize docs/RUNBOOK.md com:

• Procedimentos de deploy (passo a passo)
• Endpoints de health check e monitoramento
• Problemas comuns e suas correções
• Procedimentos de rollback
• Caminhos de alerta e escalonamento

Passo 6: Checagem de Obsolescência

1. Encontre arquivos de documentação sem modificação há 90+ dias
2. Cruze com mudanças recentes no código-fonte
3. Sinalize docs potencialmente desatualizadas para revisão manual

Passo 7: Mostrar Resumo

Documentation Update
──────────────────────────────
Updated:  docs/CONTRIBUTING.md (scripts table)
Updated:  docs/ENV.md (3 new variables)
Flagged:  docs/DEPLOY.md (142 days stale)
Skipped:  docs/API.md (no changes detected)
──────────────────────────────

Regras

• Fonte única da verdade: Sempre gere a partir do código, nunca edite manualmente seções geradas
• Preserve seções manuais: Atualize apenas seções geradas; mantenha prosa escrita manualmente intacta
• Marque conteúdo gerado: Use marcadores <!-- AUTO-GENERATED --> ao redor das seções geradas
• Não crie docs sem solicitação: Só crie novos arquivos de docs se o comando solicitar explicitamente