59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Catálogo de Problemas por Domínio
|
|
|
|
## Skills e Orchestrator
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| YAML inválido no SKILL.md | Alta | `python -c "import yaml; yaml.safe_load(open('SKILL.md').read())"` |
|
|
| `name` ou `description` duplicados no YAML | Média | Grep por `^name:` no arquivo — deve ter 1 ocorrência |
|
|
| skill-installer falha silenciosamente | Média | Usar `--force` e ler output completo |
|
|
| scan_registry.py bug com sets/dicts | Baixa | Atualizar registry manualmente via JSON |
|
|
| Skill no .claude mas não em skills/ | Média | Sempre instalar via skill-installer, não copiar manual |
|
|
|
|
## APIs e Integrações
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| Token/API key expirado | Alta | Verificar validade antes de executar |
|
|
| Rate limit atingido | Média | Implementar retry com backoff exponencial |
|
|
| Endpoint mudou (breaking change) | Baixa | Fixar versão da API, checar changelog antes |
|
|
| HMAC-SHA256 inválido em webhooks | Média | Testar com payload de exemplo antes de ir live |
|
|
| Credencial hardcoded commitada | Baixa mas crítica | `.env` obrigatório + `.gitignore` configurado |
|
|
|
|
## Arquivos e Paths
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| Path não existe | Alta | `os.path.exists()` antes de qualquer operação |
|
|
| Permissão negada | Média | Verificar com `os.access(path, os.W_OK)` |
|
|
| Encoding errado (pt-BR com acentos) | Alta | `open(f, encoding='utf-8')` explícito sempre |
|
|
| ZIP corrompido | Baixa | Verificar com `zipfile.is_zipfile()` após geração |
|
|
| Arquivo aberto por outro processo | Baixa | Fechar handles explicitamente com `with` |
|
|
|
|
## ZIPs e Builds do Ecossistema
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| ecosystem-completo.zip desatualizado | Alta | Executar build_ecosystem.py após cada nova skill |
|
|
| Skill numerada fora de ordem | Média | Verificar contagem total antes de atribuir número |
|
|
| ZIP muito grande (>50MB) | Baixa | Excluir __pycache__, .pyc, node_modules |
|
|
|
|
## Git
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| Commit na branch errada | Alta | `git branch --show-current` antes de commits |
|
|
| Uncommitted changes perdidos | Média | `git status` antes de operações destrutivas |
|
|
| Merge conflict | Média | `git pull --rebase` antes de push |
|
|
| Push de secrets | Baixa mas crítica | `git diff --staged` antes de commit |
|
|
|
|
## Python / Scripts
|
|
|
|
| Problema | Frequência | Solução Preventiva |
|
|
|----------|-----------|-------------------|
|
|
| ModuleNotFoundError | Alta | `pip install -r requirements.txt` primeiro |
|
|
| Python 2 vs 3 | Baixa | Usar `python3` explicitamente |
|
|
| Subprocess sem timeout | Média | Sempre `subprocess.run(..., timeout=30)` |
|
|
| JSON decode error | Média | Tratar `json.JSONDecodeError` explicitamente |
|
|
| UnicodeDecodeError | Alta | `encoding='utf-8', errors='replace'` em files |
|