Automação com Hooks, Rules e Skills — Gatilhos no Workflow de IA

Usuário pede: "implemente o endpoint de billing"
         │
         ▼
┌─────────────────────────────────────────┐
│ 1. RULES avaliadas                      │
│    → .claude/rules/backend.md carregado │
│       (porque o arquivo é .go)          │
│                                         │
│ 2. IA implementa o código              │
│                                         │
│ 3. HOOK onEdit disparado               │
│    → executa: go fmt ./...             │
│    → executa: go vet ./...             │
│                                         │
│ 4. Usuário diz "commit"                │
│    → SKILL commit/ carregado           │
│    → skill executa: git status         │
│    → skill gera mensagem de commit     │
│                                         │
│ 5. HOOK onCommit disparado             │
│    → executa: go test ./...            │
│    → se falhar: commit bloqueado       │
└─────────────────────────────────────────┘

// .claude/settings.json
{
  "hooks": {
    "onEdit": "pnpm lint:fix",
    "onCommit": "pnpm vitest run",
    "onFinish": "pnpm build"
  }
}

Fluxo de uma edição:

1. IA edita src/api/users.ts
         │
         ▼
2. HOOK onEdit disparado
   → shell: pnpm lint:fix src/api/users.ts
         │
         ├── SUCESSO → continua
         │
         └── FALHOU → IA recebe o output do erro
                      → IA corrige automaticamente
                      → hook roda de novo
                      → loop até passar

// .claude/settings.json — projeto TypeScript
{
  "hooks": {
    "onEdit": "pnpm lint:fix --no-error-if-unmatched",
    "onCommit": "pnpm vitest run && pnpm build",
    "onFinish": "echo 'Session ended at $(date)' >> .claude/session-log.txt"
  }
}

// .claude/settings.json — projeto Go
{
  "hooks": {
    "onEdit": "cd backend/api && go fmt ./... && go vet ./...",
    "onCommit": "cd backend/api && go test ./...",
    "onFinish": "cd backend/api && go build -o bin/api ."
  }
}

// .claude/settings.json — projeto full-stack
{
  "hooks": {
    "onEdit": "pnpm lint:fix && cd backend/api && go fmt ./...",
    "onCommit": "pnpm vitest run && pnpm build && cd backend/api && go test ./...",
    "onFinish": "pnpm build"
  }
}

#!/bin/bash
# .claude/hooks/pre-commit.sh

echo "🔍 Running pre-commit checks..."

# Lint
pnpm lint:fix
if [ $? -ne 0 ]; then
  echo "❌ Lint failed"
  exit 1
fi

# Tests
pnpm vitest run
if [ $? -ne 0 ]; then
  echo "❌ Tests failed"
  exit 1
fi

# Build
pnpm build
if [ $? -ne 0 ]; then
  echo "❌ Build failed"
  exit 1
fi

echo "✅ All checks passed"

// .claude/settings.json
{
  "hooks": {
    "onCommit": "bash .claude/hooks/pre-commit.sh"
  }
}

.claude/
├── rules/
│   ├── global.md              # Sempre carregado
│   ├── backend.md             # Carregado para backend/**
│   ├── frontend.md            # Carregado para src/**
│   ├── tests.md               # Carregado para **/*.test.ts
│   ├── database.md            # Carregado para **/*schema*
│   └── security.md            # Carregado para **/*auth*

---
# .claude/rules/backend.md

# Quando carregar esta rule
paths:
  - "backend/**/*.go"
  - "backend/**/*.mod"
  - "backend/**/*.sum"

# Tags opcionais para organização
tags:
  - go
  - backend
---

## Go Conventions

- Go 1.23, framework Gin
- Sempre rodar `go fmt` antes de commitar
- Usar table-driven tests
- Error handling: sempre wrappar com `fmt.Errorf("context: %w", err)`
- Nunca usar `panic` em código de produção
- Usar `context.Context` como primeiro parâmetro de funções que fazem I/O

## Database
- MongoDB driver v2 (nunca v1)
- Redis para cache-aside pattern
- Transações apenas quando necessário (MongoDB replica set)

## API
- Handlers em `internal/handlers/`
- Repositories em `internal/repository/`
- Models em `internal/models/`
- Nunca lógica de negócio em handlers

IA edita: backend/api/internal/handlers/user.go
         │
         ▼
Claude Code avalia paths de todas as rules:
  .claude/rules/global.md     → paths: (nenhum)     → SEMPRE carrega ✅
  .claude/rules/backend.md    → paths: backend/**/*.go → MATCH ✅
  .claude/rules/frontend.md   → paths: src/**          → não match ❌
  .claude/rules/tests.md      → paths: **/*.test.ts    → não match ❌
  .claude/rules/security.md   → paths: **/*auth*       → não match ❌
         │
         ▼
Contexto da IA: global.md + backend.md
(2 rules carregadas de 5)

---
# .claude/rules/frontend.md
paths:
  - "src/**/*.tsx"
  - "src/**/*.ts"
  - "src/**/*.css"
  - "src/app/**"
---

## React / Next.js
- Sempre usar <Link> do Next.js para navegação interna
- Componentes em PascalCase, arquivos em kebab-case
- Server Components por default, 'use client' só quando necessário
- Tailwind CSS v4 — não usar classes do v3 depreciadas
- Imagens: sempre usar next/image

## Testes
- Vitest (nunca Jest)
- Testing Library para componentes
- vi.fn() para mocks

---
# .claude/rules/tests.md
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "tests/**"
---

## Test Conventions
- Sempre usar Vitest: import { describe, it, expect, vi } from 'vitest'
- Nomes descritivos em português: it('retorna 400 sem email')
- Testar comportamento, não implementação
- Usar vi.fn() para mocks
- Nunca testar detalhes internos de componentes

---
# .claude/rules/database.md
paths:
  - "**/*schema*"
  - "**/*migration*"
  - "**/*model*"
---

## Database Rules
- Nunca dropar tabelas/collections sem confirmação
- Migrations sempre reversíveis (up + down)
- Índices devem ser criados em migrations, não manualmente
- Nunca expor _id ou __v em responses da API

---
# .claude/rules/global.md
# Sem paths = sempre carregado
---

## Global Rules
- 2 espaços de indentação
- Aspas simples em TypeScript
- Trailing commas
- Conventional Commits: feat:, fix:, refactor:, chore:, docs:
- Nunca commitar .env, credenciais ou secrets
- Nunca usar console.log em produção (apenas warn/error)

.claude/
├── skills/
│   ├── commit/
│   │   └── SKILL.md
│   ├── review-pr/
│   │   └── SKILL.md
│   ├── deploy/
│   │   └── SKILL.md
│   ├── generate-tests/
│   │   └── SKILL.md
│   └── migrate-db/
│       └── SKILL.md

# .claude/skills/commit/SKILL.md

## Description
When the user says "commit", "faz commit", "/commit", or stages changes.

## Trigger
Auto-triggers when staging changes or when user explicitly invokes.

## Steps
1. Run `git status` to see all changes
2. Run `git diff --cached` to see staged changes
3. Run `git log --oneline -5` to understand commit style
4. Analyze the nature of changes:
   - New feature → feat(scope): description
   - Bug fix → fix(scope): description
   - Refactor → refactor(scope): description
   - Documentation → docs(scope): description
   - Configuration → chore(scope): description
5. Draft commit message:
   - Subject ≤ 50 chars
   - Body only when "why" isn't obvious
   - Follow Conventional Commits format
6. Run pre-commit checks:
   - pnpm lint:fix
   - pnpm format
   - pnpm vitest run
7. If all pass, stage and commit
8. If any fail, fix and retry from step 6

.claude/skills/deploy/
├── SKILL.md              # Instruções
├── deploy-checklist.md   # Checklist de deploy
└── scripts/
    └── pre-deploy.sh     # Script de verificação

# .claude/skills/deploy/SKILL.md

## Description
When the user says "deploy", "faz deploy", "/deploy".

## Steps
1. Read @.claude/skills/deploy/deploy-checklist.md
2. Verify each item in the checklist
3. Run: bash .claude/skills/deploy/scripts/pre-deploy.sh
4. If all checks pass, run: pnpm build && vercel --prod
5. Notify user of deployment URL

┌──────────────────────────────────────────────────────────┐
│                    CICLO DE VIDA                         │
│                                                          │
│  Usuário abre sessão                                     │
│  ├── CLAUDE.md carregado (regras globais do projeto)     │
│  ├── .claude/rules/global.md carregado                   │
│  │                                                       │
│  Usuário: "edite src/api/users.ts"                       │
│  ├── .claude/rules/frontend.md carregado (path match)    │
│  ├── .claude/rules/database.md carregado (path match)    │
│  ├── IA edita o arquivo                                  │
│  ├── HOOK onEdit: pnpm lint:fix (executado)              │
│  │                                                       │
│  Usuário: "commit"                                       │
│  ├── SKILL commit/ carregado sob demanda                 │
│  ├── Skill executa: git status, git diff                 │
│  ├── Skill gera mensagem de commit                       │
│  ├── HOOK onCommit: pnpm vitest run (executado)          │
│  ├── Se testes passam → commit feito                     │
│  └── Se testes falham → IA corrige → hook roda de novo   │
└──────────────────────────────────────────────────────────┘

# 1. Criar estrutura
mkdir -p .claude/rules .claude/skills/commit .claude/skills/review-pr

# 2. CLAUDE.md na raiz
cat > CLAUDE.md << 'EOF'
# Project
## Commands: pnpm dev, pnpm lint:fix, pnpm vitest run
## Rules: Vitest never Jest, Conventional Commits
EOF

# 3. Rules globais
cat > .claude/rules/global.md << 'EOF'
---
# Sem paths = sempre carregado
---
2-space indent, single quotes, trailing commas.
Never commit .env or secrets.
EOF

# 4. Rules por stack
# (crie backend.md, frontend.md, tests.md conforme seu projeto)

# 5. Hooks
cat > .claude/settings.json << 'EOF'
{
  "hooks": {
    "onEdit": "pnpm lint:fix",
    "onCommit": "pnpm vitest run && pnpm build"
  }
}
EOF

# 6. Skill de commit
cat > .claude/skills/commit/SKILL.md << 'EOF'
## Description
When the user says "commit" or stages changes.
## Steps
1. git status && git diff --cached
2. Draft Conventional Commit message
3. Run pnpm lint:fix && pnpm vitest run
4. If green, commit
EOF

# 7. Adicionar ao .gitignore (se necessário)
echo ".claude.local.md" >> .gitignore