feat(v1.5.2): Execute database migrations and complete setup
- Execute all 6 migrations on Desk CRM production database - Create missing tables: cr_lsps, cr_agent_lsps, cr_lsp_usage - Create archive tables: cr_*_usage_archive (4 tables) - Create system tables: cr_migrations, cr_maintenance_log - Make all scripts executable (chmod +x) - Total cr_* tables: 38 Migration files: - 001_initial_schema.sql - 002_add_lsps.sql - 003_add_relationships.sql - 004_add_telemetry.sql - 005_add_archive_tables.sql - 006_add_maintenance_log.sql Scripts: - session-init.sh, session-end.sh - inject-context.sh, inject-agent-context.sh - record-usage.sh, db-backup.sh, sync-to-mysql.sh Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
211
docs/README.md
Executable file
211
docs/README.md
Executable file
@@ -0,0 +1,211 @@
|
||||
# Boas Práticas SDK Claude Code Descomplicar®
|
||||
|
||||
> **Guias de Referência para Refactoring de Skills, Agents, Plugins e Hooks**
|
||||
|
||||
## Documentos Disponíveis
|
||||
|
||||
| # | Documento | Descrição | Linhas | Prioridade |
|
||||
|---|-----------|-----------|--------|------------|
|
||||
| 0 | [STANDARDS.md](STANDARDS.md) | **Regras oficiais do ecossistema** - documento mestre | ~477 | **Crítica** |
|
||||
| 1 | [SKILL-BEST-PRACTICES.md](SKILL-BEST-PRACTICES.md) | Guia completo para criação de skills de alta qualidade | ~600 | Alta |
|
||||
| 2 | [AGENT-BEST-PRACTICES.md](AGENT-BEST-PRACTICES.md) | Guia para agentes especializados | ~471 | Alta |
|
||||
| 3 | [03-GUIA-HOOKS.md](03-GUIA-HOOKS.md) | **NOVO** - Guia completo de hooks (12 eventos, scripts, debugging) | ~1184 | Alta |
|
||||
| 4 | [GUIA-PLUGINS-CLAUDE-CODE.md](GUIA-PLUGINS-CLAUDE-CODE.md) | Guia de arquitectura e estrutura de plugins | ~1167 | Alta |
|
||||
|
||||
---
|
||||
|
||||
## Resumo Executivo
|
||||
|
||||
### Skills - Pontos Críticos
|
||||
|
||||
| Factor | Impacto |
|
||||
|--------|---------|
|
||||
| **Descrição optimizada** | 20% → 72% taxa de activação |
|
||||
| **Keywords específicas** | +5 keywords = melhor discovery |
|
||||
| **Tamanho <500 linhas** | Performance e manutenibilidade |
|
||||
| **Progressive disclosure** | Eficiência de tokens |
|
||||
|
||||
### Agents - Pontos Críticos
|
||||
|
||||
| Factor | Impacto |
|
||||
|--------|---------|
|
||||
| **Mapeamento MCPs** | Capacidades disponíveis |
|
||||
| **Colaborações definidas** | Delegação eficiente |
|
||||
| **Limites explícitos** | Evita scope creep |
|
||||
| **Skills preloaded** | Contexto especializado |
|
||||
|
||||
### Hooks - Pontos Críticos
|
||||
|
||||
| Factor | Impacto |
|
||||
|--------|---------|
|
||||
| **12 eventos disponíveis** | Controlo total do ciclo de vida |
|
||||
| **PreToolUse blocking** | Validação antes de execução |
|
||||
| **Async para side-effects** | Não bloqueia Claude |
|
||||
| **Agent hooks** | Multi-turn com tool access |
|
||||
|
||||
### Plugins - Pontos Críticos
|
||||
|
||||
| Factor | Impacto |
|
||||
|--------|---------|
|
||||
| **Progressive disclosure** | Metadata → Body → Resources |
|
||||
| **Namespacing** | Evita colisões de comandos |
|
||||
| **Versionamento semver** | Gestão de breaking changes |
|
||||
| **CHANGELOG obrigatório** | Rastreabilidade completa |
|
||||
|
||||
---
|
||||
|
||||
## Taxas de Sucesso por Optimização
|
||||
|
||||
### Skills
|
||||
|
||||
```
|
||||
Sem optimização ████░░░░░░░░░░░░ 20%
|
||||
Descrição opt. ██████████░░░░░░ 50%
|
||||
+ Keywords ██████████████░░ 72%
|
||||
+ Hooks avaliação ████████████████ 84%
|
||||
```
|
||||
|
||||
### Agents
|
||||
|
||||
```
|
||||
Sem relacionamentos ██████░░░░░░░░░░ 30%
|
||||
+ MCPs mapeados ██████████░░░░░░ 55%
|
||||
+ Skills integradas █████████████░░░ 75%
|
||||
+ Colaborações ████████████████ 90%
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Estrutura Skill
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: Capacidade. Use when [triggers].
|
||||
---
|
||||
|
||||
# Título
|
||||
[Instruções <500 linhas]
|
||||
```
|
||||
|
||||
### Estrutura Agent
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: agent-slug
|
||||
description: Especialização. Use for [triggers].
|
||||
model: sonnet
|
||||
tools: [lista]
|
||||
---
|
||||
|
||||
# Nome
|
||||
[Persona + Workflow + Limites]
|
||||
```
|
||||
|
||||
### Estrutura Hook
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"PreToolUse": [{
|
||||
"matcher": "Bash",
|
||||
"hooks": [{
|
||||
"type": "command",
|
||||
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
|
||||
}]
|
||||
}]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Estrutura Plugin
|
||||
|
||||
```
|
||||
plugin-name/
|
||||
├── .claude-plugin/plugin.json # Manifesto
|
||||
├── skills/ # Skills bundled
|
||||
├── agents/ # Agents bundled
|
||||
├── commands/ # Comandos /plugin:cmd
|
||||
├── hooks/hooks.json # Hooks do plugin
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist Rápido
|
||||
|
||||
### Nova Skill
|
||||
|
||||
- [ ] Description com triggers e keywords
|
||||
- [ ] SKILL.md <500 linhas
|
||||
- [ ] Exemplos input/output
|
||||
- [ ] Limites definidos
|
||||
- [ ] Testada 3+ cenários
|
||||
|
||||
### Novo Agent
|
||||
|
||||
- [ ] MCPs mapeados por tipo (primary/recommended/available)
|
||||
- [ ] Skills associadas
|
||||
- [ ] Colaborações definidas
|
||||
- [ ] Workflow documentado
|
||||
- [ ] Limites explícitos
|
||||
|
||||
### Novo Hook
|
||||
|
||||
- [ ] Evento correcto (PreToolUse, PostToolUse, etc.)
|
||||
- [ ] Matcher com regex válido
|
||||
- [ ] Script executável (`chmod +x`)
|
||||
- [ ] JSON output válido
|
||||
- [ ] Timeout apropriado
|
||||
- [ ] Async se side-effect
|
||||
|
||||
### Novo Plugin
|
||||
|
||||
- [ ] `.claude-plugin/plugin.json` com campos obrigatórios
|
||||
- [ ] Versão semver correcta
|
||||
- [ ] CHANGELOG.md actualizado
|
||||
- [ ] README.md com contagens
|
||||
- [ ] Namespacing para commands
|
||||
- [ ] Testado em ambiente limpo
|
||||
|
||||
---
|
||||
|
||||
## Eventos de Hook Disponíveis
|
||||
|
||||
| Evento | Bloqueia? | Uso Principal |
|
||||
|--------|-----------|---------------|
|
||||
| SessionStart | Não | Setup ambiente, env vars |
|
||||
| UserPromptSubmit | Sim | Validar/enriquecer prompt |
|
||||
| PreToolUse | Sim | Bloquear comandos perigosos |
|
||||
| PermissionRequest | Sim | Auto-aprovar/negar |
|
||||
| PostToolUse | Não | Format, log, notify |
|
||||
| PostToolUseFailure | Não | Error handling |
|
||||
| SubagentStart | Não | Injectar contexto |
|
||||
| SubagentStop | Sim | Validar resultado |
|
||||
| Stop | Sim | Verificar antes de parar |
|
||||
| PreCompact | Não | Preparar compactação |
|
||||
| SessionEnd | Não | Cleanup, telemetria |
|
||||
|
||||
---
|
||||
|
||||
## Fontes
|
||||
|
||||
### Documentação Oficial
|
||||
- [Claude Code Skills](https://code.claude.com/docs/en/skills)
|
||||
- [Claude Code Hooks](https://code.claude.com/docs/en/hooks)
|
||||
- [Claude Code Hooks Guide](https://code.claude.com/docs/en/hooks-guide)
|
||||
|
||||
### Repositórios
|
||||
- [anthropics/skills](https://github.com/anthropics/skills) (62k stars)
|
||||
- [VoltAgent/awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
|
||||
- [claude-code-hooks-mastery](https://github.com/disler/claude-code-hooks-mastery)
|
||||
|
||||
### Análises
|
||||
- [Claude Skills Deep Dive](https://leehanchung.github.io/blogs/2025/10/26/claude-skills-deep-dive/)
|
||||
- [Complete guide to hooks - Eesel AI](https://www.eesel.ai/blog/hooks-in-claude-code)
|
||||
|
||||
---
|
||||
|
||||
**Última actualização:** 2026-02-04 | Descomplicar®
|
||||
Reference in New Issue
Block a user