zsp/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-03-30 13:43:26 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(pt-BR): add commands translation

Browse Source
This commit is contained in:
Paulo Victor Gomes
2026-03-21 14:06:49 +01:00
parent 5fb3bca5fd
commit 1ef8bc1e72
18 changed files with 2448 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/pt-BR/commands/build-fix.md Normal file
View File

@@ -0,0 +1,62 @@
# Build e Correção
Corrija erros de build e de tipos incrementalmente com mudanças mínimas e seguras.
## Passo 1: Detectar Sistema de Build
Identifique a ferramenta de build do projeto e execute o build:
| Indicator | Build Command |
|-----------|---------------|
| `package.json` with `build` script | `npm run build` or `pnpm build` |
| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
| `Cargo.toml` | `cargo build 2>&1` |
| `pom.xml` | `mvn compile` |
| `build.gradle` | `./gradlew compileJava` |
| `go.mod` | `go build ./...` |
| `pyproject.toml` | `python -m py_compile` or `mypy .` |
## Passo 2: Parsear e Agrupar Erros
1. Execute o comando de build e capture o stderr
2. Agrupe erros por caminho de arquivo
3. Ordene por ordem de dependência (corrija imports/tipos antes de erros de lógica)
4. Conte o total de erros para acompanhamento de progresso
## Passo 3: Loop de Correção (Um Erro por Vez)
Para cada erro:
1. **Leia o arquivo** — Use a ferramenta Read para ver o contexto do erro (10 linhas ao redor do erro)
2. **Diagnostique** — Identifique a causa raiz (import ausente, tipo errado, erro de sintaxe)
3. **Corrija minimamente** — Use a ferramenta Edit para a menor mudança que resolve o erro
4. **Rode o build novamente** — Verifique que o erro sumiu e que nenhum novo erro foi introduzido
5. **Vá para o próximo** — Continue com os erros restantes
## Passo 4: Guardrails
Pare e pergunte ao usuário se:
- Uma correção introduz **mais erros do que resolve**
- O **mesmo erro persiste após 3 tentativas** (provavelmente há um problema mais profundo)
- A correção exige **mudanças arquiteturais** (não apenas correção de build)
- Os erros de build vêm de **dependências ausentes** (precisa de `npm install`, `cargo add`, etc.)
## Passo 5: Resumo
Mostre resultados:
- Erros corrigidos (com caminhos de arquivos)
- Erros restantes (se houver)
- Novos erros introduzidos (deve ser zero)
- Próximos passos sugeridos para problemas não resolvidos
## Estratégias de Recuperação
| Situation | Action |
|-----------|--------|
| Missing module/import | Check if package is installed; suggest install command |
| Type mismatch | Read both type definitions; fix the narrower type |
| Circular dependency | Identify cycle with import graph; suggest extraction |
| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
| Build tool misconfiguration | Read config file; compare with working defaults |
Corrija um erro por vez por segurança. Prefira diffs mínimos em vez de refatoração.

74
docs/pt-BR/commands/checkpoint.md Normal file
View File

@@ -0,0 +1,74 @@
# Comando Checkpoint
Crie ou verifique um checkpoint no seu fluxo.
## Uso
`/checkpoint [create|verify|list] [name]`
## Criar Checkpoint
Ao criar um checkpoint:
1. Rode `/verify quick` para garantir que o estado atual está limpo
2. Crie um git stash ou commit com o nome do checkpoint
3. Registre o checkpoint em `.claude/checkpoints.log`:
```bash
echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
```
4. Informe que o checkpoint foi criado
## Verificar Checkpoint
Ao verificar contra um checkpoint:
1. Leia o checkpoint no log
2. Compare o estado atual com o checkpoint:
- Arquivos adicionados desde o checkpoint
- Arquivos modificados desde o checkpoint
- Taxa de testes passando agora vs antes
- Cobertura agora vs antes
3. Reporte:
```
CHECKPOINT COMPARISON: $NAME
============================
Files changed: X
Tests: +Y passed / -Z failed
Coverage: +X% / -Y%
Build: [PASS/FAIL]
```
## Listar Checkpoints
Mostre todos os checkpoints com:
- Nome
- Timestamp
- Git SHA
- Status (current, behind, ahead)
## Fluxo
Fluxo típico de checkpoint:
```
[Start] --> /checkpoint create "feature-start"
|
[Implement] --> /checkpoint create "core-done"
|
[Test] --> /checkpoint verify "core-done"
|
[Refactor] --> /checkpoint create "refactor-done"
|
[PR] --> /checkpoint verify "feature-start"
```
## Argumentos
$ARGUMENTS:
- `create <name>` - Criar checkpoint nomeado
- `verify <name>` - Verificar contra checkpoint nomeado
- `list` - Mostrar todos os checkpoints
- `clear` - Remover checkpoints antigos (mantém os últimos 5)

40
docs/pt-BR/commands/code-review.md Normal file
View File

@@ -0,0 +1,40 @@
# Code Review
Revisão completa de segurança e qualidade das mudanças não commitadas:
1. Obtenha arquivos alterados: git diff --name-only HEAD
2. Para cada arquivo alterado, verifique:
**Problemas de Segurança (CRITICAL):**
- Credenciais, chaves de API ou tokens hardcoded
- Vulnerabilidades de SQL injection
- Vulnerabilidades de XSS
- Falta de validação de entrada
- Dependências inseguras
- Riscos de path traversal
**Qualidade de Código (HIGH):**
- Funções > 50 linhas
- Arquivos > 800 linhas
- Profundidade de aninhamento > 4 níveis
- Falta de tratamento de erro
- Statements de console.log
- Comentários TODO/FIXME
- Falta de JSDoc para APIs públicas
**Boas Práticas (MEDIUM):**
- Padrões de mutação (usar imutável no lugar)
- Uso de emoji em código/comentários
- Falta de testes para código novo
- Problemas de acessibilidade (a11y)
3. Gere relatório com:
- Severidade: CRITICAL, HIGH, MEDIUM, LOW
- Localização no arquivo e números de linha
- Descrição do problema
- Correção sugerida
4. Bloqueie commit se houver problemas CRITICAL ou HIGH
Nunca aprove código com vulnerabilidades de segurança!

365
docs/pt-BR/commands/e2e.md Normal file
View File

@@ -0,0 +1,365 @@
---
description: Gere e rode testes end-to-end com Playwright. Cria jornadas de teste, executa testes, captura screenshots/videos/traces e faz upload de artefatos.
---
# Comando E2E
Este comando invoca o agente **e2e-runner** para gerar, manter e executar testes end-to-end usando Playwright.
## O Que Este Comando Faz
1. **Gerar Jornadas de Teste** - Cria testes Playwright para fluxos de usuário
2. **Rodar Testes E2E** - Executa testes em múltiplos navegadores
3. **Capturar Artefatos** - Screenshots, vídeos, traces em falhas
4. **Upload de Resultados** - Relatórios HTML e JUnit XML
5. **Identificar Testes Flaky** - Coloca testes instáveis em quarentena
## Quando Usar
Use `/e2e` quando:
- Testar jornadas críticas de usuário (login, trading, pagamentos)
- Verificar fluxos multi-etapa de ponta a ponta
- Testar interações de UI e navegação
- Validar integração entre frontend e backend
- Preparar para deploy em produção
## Como Funciona
O agente e2e-runner vai:
1. **Analisar o fluxo de usuário** e identificar cenários de teste
2. **Gerar teste Playwright** usando padrão Page Object Model
3. **Rodar testes** em múltiplos navegadores (Chrome, Firefox, Safari)
4. **Capturar falhas** com screenshots, vídeos e traces
5. **Gerar relatório** com resultados e artefatos
6. **Identificar testes flaky** e recomendar correções
## Exemplo de Uso
```
User: /e2e Test the market search and view flow
Agent (e2e-runner):
# E2E Test Generation: Market Search and View Flow
## Test Scenario Identified
**User Journey:** Market Search → View Results → Click Market → View Details
**Test Coverage:**
1. Navigate to markets page
2. Perform semantic search
3. Verify search results
4. Click on first result
5. Verify market details page loads
6. Verify chart renders
## Generated Test Code
```typescript
// tests/e2e/markets/search-and-view.spec.ts
import { test, expect } from '@playwright/test'
import { MarketsPage } from '../../pages/MarketsPage'
import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
test.describe('Market Search and View Flow', () => {
test('user can search markets and view details', async ({ page }) => {
// 1. Navigate to markets page
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Verify page loaded
await expect(page).toHaveTitle(/Markets/)
await expect(page.locator('h1')).toContainText('Markets')
// 2. Perform semantic search
await marketsPage.searchMarkets('election')
// Wait for API response
await page.waitForResponse(resp =>
resp.url().includes('/api/markets/search') && resp.status() === 200
)
// 3. Verify search results
const marketCards = marketsPage.marketCards
await expect(marketCards.first()).toBeVisible()
const resultCount = await marketCards.count()
expect(resultCount).toBeGreaterThan(0)
// Take screenshot of search results
await page.screenshot({ path: 'artifacts/search-results.png' })
// 4. Click on first result
const firstMarketTitle = await marketCards.first().textContent()
await marketCards.first().click()
// 5. Verify market details page loads
await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
const detailsPage = new MarketDetailsPage(page)
await expect(detailsPage.marketName).toBeVisible()
await expect(detailsPage.marketDescription).toBeVisible()
// 6. Verify chart renders
await expect(detailsPage.priceChart).toBeVisible()
// Verify market name matches
const detailsTitle = await detailsPage.marketName.textContent()
expect(detailsTitle?.toLowerCase()).toContain(
firstMarketTitle?.toLowerCase().substring(0, 20) || ''
)
// Take screenshot of market details
await page.screenshot({ path: 'artifacts/market-details.png' })
})
test('search with no results shows empty state', async ({ page }) => {
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Search for non-existent market
await marketsPage.searchMarkets('xyznonexistentmarket123456')
// Verify empty state
await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
await expect(page.locator('[data-testid="no-results"]')).toContainText(
/no.*results|no.*markets/i
)
const marketCount = await marketsPage.marketCards.count()
expect(marketCount).toBe(0)
})
test('can clear search and see all markets again', async ({ page }) => {
const marketsPage = new MarketsPage(page)
await marketsPage.goto()
// Initial market count
const initialCount = await marketsPage.marketCards.count()
// Perform search
await marketsPage.searchMarkets('trump')
await page.waitForLoadState('networkidle')
// Verify filtered results
const filteredCount = await marketsPage.marketCards.count()
expect(filteredCount).toBeLessThan(initialCount)
// Clear search
await marketsPage.searchInput.clear()
await page.waitForLoadState('networkidle')
// Verify all markets shown again
const finalCount = await marketsPage.marketCards.count()
expect(finalCount).toBe(initialCount)
})
})
```
## Rodando os Testes
```bash
# Run the generated test
npx playwright test tests/e2e/markets/search-and-view.spec.ts
Running 3 tests using 3 workers
✓ [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
✓ [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
✓ [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
3 passed (9.1s)
Artifacts generated:
- artifacts/search-results.png
- artifacts/market-details.png
- playwright-report/index.html
```
## Relatório de Teste
```
╔══════════════════════════════════════════════════════════════╗
║ E2E Test Results ║
╠══════════════════════════════════════════════════════════════╣
║ Status: ✅ ALL TESTS PASSED ║
║ Total: 3 tests ║
║ Passed: 3 (100%) ║
║ Failed: 0 ║
║ Flaky: 0 ║
║ Duration: 9.1s ║
╚══════════════════════════════════════════════════════════════╝
Artifacts:
📸 Screenshots: 2 files
📹 Videos: 0 files (only on failure)
🔍 Traces: 0 files (only on failure)
📊 HTML Report: playwright-report/index.html
View report: npx playwright show-report
```
✅ E2E test suite ready for CI/CD integration!
```
## Artefatos de Teste
Quando os testes rodam, os seguintes artefatos são capturados:
**Em Todos os Testes:**
- Relatório HTML com timeline e resultados
- JUnit XML para integração com CI
**Somente em Falha:**
- Screenshot do estado de falha
- Gravação em vídeo do teste
- Arquivo de trace para debug (replay passo a passo)
- Logs de rede
- Logs de console
## Visualizando Artefatos
```bash
# View HTML report in browser
npx playwright show-report
# View specific trace file
npx playwright show-trace artifacts/trace-abc123.zip
# Screenshots are saved in artifacts/ directory
open artifacts/search-results.png
```
## Detecção de Teste Flaky
Se um teste falhar de forma intermitente:
```
⚠️ FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
Test passed 7/10 runs (70% pass rate)
Common failure:
"Timeout waiting for element '[data-testid="confirm-btn"]'"
Recommended fixes:
1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
2. Increase timeout: { timeout: 10000 }
3. Check for race conditions in component
4. Verify element is not hidden by animation
Quarantine recommendation: Mark as test.fixme() until fixed
```
## Configuração de Navegador
Os testes rodam em múltiplos navegadores por padrão:
- ✅ Chromium (Desktop Chrome)
- ✅ Firefox (Desktop)
- ✅ WebKit (Desktop Safari)
- ✅ Mobile Chrome (optional)
Configure em `playwright.config.ts` para ajustar navegadores.
## Integração CI/CD
Adicione ao seu pipeline de CI:
```yaml
# .github/workflows/e2e.yml
- name: Install Playwright
run: npx playwright install --with-deps
- name: Run E2E tests
run: npx playwright test
- name: Upload artifacts
if: always()
uses: actions/upload-artifact@v3
with:
name: playwright-report
path: playwright-report/
```
## Fluxos Críticos Específicos do PMX
Para PMX, priorize estes testes E2E:
**🔴 CRITICAL (Must Always Pass):**
1. User can connect wallet
2. User can browse markets
3. User can search markets (semantic search)
4. User can view market details
5. User can place trade (with test funds)
6. Market resolves correctly
7. User can withdraw funds
**🟡 IMPORTANT:**
1. Market creation flow
2. User profile updates
3. Real-time price updates
4. Chart rendering
5. Filter and sort markets
6. Mobile responsive layout
## Boas Práticas
**DO:**
- ✅ Use Page Object Model para manutenção
- ✅ Use atributos data-testid para seletores
- ✅ Aguarde respostas de API, não timeouts arbitrários
- ✅ Teste jornadas críticas de usuário end-to-end
- ✅ Rode testes antes de mergear em main
- ✅ Revise artefatos quando testes falharem
**DON'T:**
- ❌ Use seletores frágeis (classes CSS podem mudar)
- ❌ Teste detalhes de implementação
- ❌ Rode testes contra produção
- ❌ Ignore testes flaky
- ❌ Pule revisão de artefatos em falhas
- ❌ Teste todo edge case com E2E (use testes unitários)
## Notas Importantes
**CRITICAL para PMX:**
- Testes E2E envolvendo dinheiro real DEVEM rodar apenas em testnet/staging
- Nunca rode testes de trading em produção
- Defina `test.skip(process.env.NODE_ENV === 'production')` para testes financeiros
- Use carteiras de teste com fundos de teste pequenos apenas
## Integração com Outros Comandos
- Use `/plan` para identificar jornadas críticas a testar
- Use `/tdd` para testes unitários (mais rápidos e granulares)
- Use `/e2e` para integração e jornadas de usuário
- Use `/code-review` para verificar qualidade dos testes
## Agentes Relacionados
Este comando invoca o agente `e2e-runner` fornecido pelo ECC.
Para instalações manuais, o arquivo fonte fica em:
`agents/e2e-runner.md`
## Comandos Rápidos
```bash
# Run all E2E tests
npx playwright test
# Run specific test file
npx playwright test tests/e2e/markets/search.spec.ts
# Run in headed mode (see browser)
npx playwright test --headed
# Debug test
npx playwright test --debug
# Generate test code
npx playwright codegen http://localhost:3000
# View report
npx playwright show-report
```

120
docs/pt-BR/commands/eval.md Normal file
View File

@@ -0,0 +1,120 @@
# Comando Eval
Gerencie o fluxo de desenvolvimento orientado por evals.
## Uso
`/eval [define|check|report|list] [feature-name]`
## Definir Evals
`/eval define feature-name`
Crie uma nova definição de eval:
1. Crie `.claude/evals/feature-name.md` com o template:
```markdown
## EVAL: feature-name
Created: $(date)
### Capability Evals
- [ ] [Description of capability 1]
- [ ] [Description of capability 2]
### Regression Evals
- [ ] [Existing behavior 1 still works]
- [ ] [Existing behavior 2 still works]
### Success Criteria
- pass@3 > 90% for capability evals
- pass^3 = 100% for regression evals
```
2. Peça ao usuário para preencher os critérios específicos
## Verificar Evals
`/eval check feature-name`
Rode evals para uma feature:
1. Leia a definição de eval em `.claude/evals/feature-name.md`
2. Para cada eval de capability:
- Tente verificar o critério
- Registre PASS/FAIL
- Salve tentativa em `.claude/evals/feature-name.log`
3. Para cada eval de regressão:
- Rode os testes relevantes
- Compare com baseline
- Registre PASS/FAIL
4. Reporte status atual:
```
EVAL CHECK: feature-name
========================
Capability: X/Y passing
Regression: X/Y passing
Status: IN PROGRESS / READY
```
## Relatório de Evals
`/eval report feature-name`
Gere relatório completo de eval:
```
EVAL REPORT: feature-name
=========================
Generated: $(date)
CAPABILITY EVALS
----------------
[eval-1]: PASS (pass@1)
[eval-2]: PASS (pass@2) - required retry
[eval-3]: FAIL - see notes
REGRESSION EVALS
----------------
[test-1]: PASS
[test-2]: PASS
[test-3]: PASS
METRICS
-------
Capability pass@1: 67%
Capability pass@3: 100%
Regression pass^3: 100%
NOTES
-----
[Any issues, edge cases, or observations]
RECOMMENDATION
--------------
[SHIP / NEEDS WORK / BLOCKED]
```
## Listar Evals
`/eval list`
Mostre todas as definições de eval:
```
EVAL DEFINITIONS
================
feature-auth [3/5 passing] IN PROGRESS
feature-search [5/5 passing] READY
feature-export [0/4 passing] NOT STARTED
```
## Argumentos
$ARGUMENTS:
- `define <name>` - Criar nova definição de eval
- `check <name>` - Rodar e verificar evals
- `report <name>` - Gerar relatório completo
- `list` - Mostrar todos os evals
- `clean` - Remover logs antigos de eval (mantém as últimas 10 execuções)

183
docs/pt-BR/commands/go-build.md Normal file
View File

@@ -0,0 +1,183 @@
---
description: Corrija erros de build em Go, avisos de go vet e problemas de lint incrementalmente. Invoca o agente go-build-resolver para correções mínimas e cirúrgicas.
---
# Build e Correção Go
Este comando invoca o agente **go-build-resolver** para corrigir erros de build Go incrementalmente com mudanças mínimas.
## O Que Este Comando Faz
1. **Rodar Diagnósticos**: Executa `go build`, `go vet`, `staticcheck`
2. **Parsear Erros**: Agrupa por arquivo e ordena por severidade
3. **Corrigir Incrementalmente**: Um erro por vez
4. **Verificar Cada Correção**: Roda build de novo após cada mudança
5. **Reportar Resumo**: Mostra o que foi corrigido e o que resta
## Quando Usar
Use `/go-build` quando:
- `go build ./...` falhar com erros
- `go vet ./...` reportar problemas
- `golangci-lint run` mostrar avisos
- Dependências do módulo estiverem quebradas
- Após puxar mudanças que quebraram o build
## Comandos de Diagnóstico Executados
```bash
# Primary build check
go build ./...
# Static analysis
go vet ./...
# Extended linting (if available)
staticcheck ./...
golangci-lint run
# Module issues
go mod verify
go mod tidy -v
```
## Exemplo de Sessão
```text
User: /go-build
Agent:
# Go Build Resolution
## Initial Diagnostics
```bash
$ go build ./...
internal/service/user.go:25:15: undefined: UserRepository
internal/handler/api.go:42:9: cannot use x (type string) as type int
internal/handler/api.go:58:2: missing return at end of function
```
Errors found: 3
## Fix 1: Undefined Identifier
File: internal/service/user.go:25
Error: undefined: UserRepository
Cause: Missing import
```go
// Added import
import "project/internal/repository"
// Changed
var repo UserRepository
// To
var repo repository.UserRepository
```
```bash
$ go build ./...
# 2 errors remaining
```
## Fix 2: Type Mismatch
File: internal/handler/api.go:42
Error: cannot use x (type string) as type int
```go
// Changed
count := params.Get("count")
// To
countStr := params.Get("count")
count, _ := strconv.Atoi(countStr)
```
```bash
$ go build ./...
# 1 error remaining
```
## Fix 3: Missing Return
File: internal/handler/api.go:58
Error: missing return at end of function
```go
func GetUser(id string) (*User, error) {
if id == "" {
return nil, ErrInvalidID
}
user := findUser(id)
// Added missing return
return user, nil
}
```
```bash
$ go build ./...
# Build successful!
```
## Final Verification
```bash
$ go vet ./...
# No issues
$ go test ./...
ok project/internal/service 0.015s
ok project/internal/handler 0.023s
```
## Summary
| Metric | Count |
|--------|-------|
| Build errors fixed | 3 |
| Vet warnings fixed | 0 |
| Files modified | 2 |
| Remaining issues | 0 |
Build Status: ✅ SUCCESS
```
## Erros Comuns Corrigidos
| Error | Typical Fix |
|-------|-------------|
| `undefined: X` | Add import or fix typo |
| `cannot use X as Y` | Type conversion or fix assignment |
| `missing return` | Add return statement |
| `X does not implement Y` | Add missing method |
| `import cycle` | Restructure packages |
| `declared but not used` | Remove or use variable |
| `cannot find package` | `go get` or `go mod tidy` |
## Estratégia de Correção
1. **Erros de build primeiro** - O código precisa compilar
2. **Avisos do vet depois** - Corrigir construções suspeitas
3. **Avisos de lint por último** - Estilo e boas práticas
4. **Uma correção por vez** - Verificar cada mudança
5. **Mudanças mínimas** - Não refatorar, apenas corrigir
## Condições de Parada
O agente vai parar e reportar se:
- O mesmo erro persistir após 3 tentativas
- A correção introduzir mais erros
- Exigir mudanças arquiteturais
- Faltarem dependências externas
## Comandos Relacionados
- `/go-test` - Rode testes após o build passar
- `/go-review` - Revise qualidade do código
- `/verify` - Loop completo de verificação
## Relacionado
- Agent: `agents/go-build-resolver.md`
- Skill: `skills/golang-patterns/`

148
docs/pt-BR/commands/go-review.md Normal file
View File

@@ -0,0 +1,148 @@
---
description: Revisão completa de código Go para padrões idiomáticos, segurança de concorrência, tratamento de erro e segurança. Invoca o agente go-reviewer.
---
# Code Review Go
Este comando invoca o agente **go-reviewer** para revisão abrangente e específica de Go.
## O Que Este Comando Faz
1. **Identificar Mudanças Go**: Encontra arquivos `.go` modificados via `git diff`
2. **Rodar Análise Estática**: Executa `go vet`, `staticcheck` e `golangci-lint`
3. **Varredura de Segurança**: Verifica SQL injection, command injection e race conditions
4. **Revisão de Concorrência**: Analisa segurança de goroutines, uso de channels e padrões com mutex
5. **Checagem de Go Idiomático**: Verifica se o código segue convenções e boas práticas de Go
6. **Gerar Relatório**: Categoriza problemas por severidade
## Quando Usar
Use `/go-review` quando:
- Após escrever ou modificar código Go
- Antes de commitar mudanças Go
- Ao revisar pull requests com código Go
- Ao entrar em um novo codebase Go
- Ao aprender padrões idiomáticos Go
## Categorias de Revisão
### CRITICAL (Obrigatório Corrigir)
- Vulnerabilidades de SQL/Command injection
- Race conditions sem sincronização
- Vazamento de goroutine
- Credenciais hardcoded
- Uso inseguro de ponteiros
- Erros ignorados em caminhos críticos
### HIGH (Deve Corrigir)
- Falta de wrapping de erro com contexto
- Panic em vez de retorno de erro
- Context não propagado
- Canais não bufferizados causando deadlock
- Erros de interface não satisfeita
- Falta de proteção com mutex
### MEDIUM (Considere)
- Padrões não idiomáticos
- Falta de comentários godoc em exports
- Concatenação de string ineficiente
- Slice sem pré-alocação
- Table-driven tests não usados
## Checagens Automáticas Executadas
```bash
# Static analysis
go vet ./...
# Advanced checks (if installed)
staticcheck ./...
golangci-lint run
# Race detection
go build -race ./...
# Security vulnerabilities
govulncheck ./...
```
## Exemplo de Uso
```text
User: /go-review
Agent:
# Go Code Review Report
## Files Reviewed
- internal/handler/user.go (modified)
- internal/service/auth.go (modified)
## Static Analysis Results
✓ go vet: No issues
✓ staticcheck: No issues
## Issues Found
[CRITICAL] Race Condition
File: internal/service/auth.go:45
Issue: Shared map accessed without synchronization
```go
var cache = map[string]*Session{} // Concurrent access!
func GetSession(id string) *Session {
return cache[id] // Race condition
}
```
Fix: Use sync.RWMutex or sync.Map
```go
var (
cache = map[string]*Session{}
cacheMu sync.RWMutex
)
func GetSession(id string) *Session {
cacheMu.RLock()
defer cacheMu.RUnlock()
return cache[id]
}
```
[HIGH] Missing Error Context
File: internal/handler/user.go:28
Issue: Error returned without context
```go
return err // No context
```
Fix: Wrap with context
```go
return fmt.Errorf("get user %s: %w", userID, err)
```
## Summary
- CRITICAL: 1
- HIGH: 1
- MEDIUM: 0
Recommendation: ❌ Block merge until CRITICAL issue is fixed
```
## Critérios de Aprovação
| Status | Condition |
|--------|-----------|
| ✅ Approve | No CRITICAL or HIGH issues |
| ⚠️ Warning | Only MEDIUM issues (merge with caution) |
| ❌ Block | CRITICAL or HIGH issues found |
## Integração com Outros Comandos
- Use `/go-test` primeiro para garantir que os testes passam
- Use `/go-build` se houver erros de build
- Use `/go-review` antes de commitar
- Use `/code-review` para preocupações não específicas de Go
## Relacionado
- Agent: `agents/go-reviewer.md`
- Skills: `skills/golang-patterns/`, `skills/golang-testing/`

268
docs/pt-BR/commands/go-test.md Normal file
View File

@@ -0,0 +1,268 @@
---
description: Impõe fluxo de TDD para Go. Escreva table-driven tests primeiro e depois implemente. Verifique cobertura de 80%+ com go test -cover.
---
# Comando TDD Go
Este comando impõe a metodologia de desenvolvimento orientado a testes para código Go usando padrões idiomáticos de teste em Go.
## O Que Este Comando Faz
1. **Definir Tipos/Interfaces**: Estrutura assinaturas de função primeiro
2. **Escrever Table-Driven Tests**: Criar casos de teste abrangentes (RED)
3. **Rodar Testes**: Verificar que os testes falham pelo motivo certo
4. **Implementar Código**: Escrever código mínimo para passar (GREEN)
5. **Refatorar**: Melhorar mantendo testes verdes
6. **Checar Cobertura**: Garantir 80%+ de cobertura
## Quando Usar
Use `/go-test` quando:
- Implementar novas funções Go
- Adicionar cobertura de testes a código existente
- Corrigir bugs (escreva primeiro o teste que falha)
- Construir lógica de negócio crítica
- Aprender fluxo TDD em Go
## Ciclo TDD
```
RED → Write failing table-driven test
GREEN → Implement minimal code to pass
REFACTOR → Improve code, tests stay green
REPEAT → Next test case
```
## Exemplo de Sessão
````
User: /go-test I need a function to validate email addresses
Agent:
# TDD Session: Email Validator
## Step 1: Define Interface
```go
// validator/email.go
package validator
// ValidateEmail checks if the given string is a valid email address.
// Returns nil if valid, error describing the issue otherwise.
func ValidateEmail(email string) error {
panic("not implemented")
}
```
## Step 2: Write Table-Driven Tests (RED)
```go
// validator/email_test.go
package validator
import (
"testing"
)
func TestValidateEmail(t *testing.T) {
tests := []struct {
name string
email string
wantErr bool
}{
// Valid emails
{"simple email", "user@example.com", false},
{"with subdomain", "user@mail.example.com", false},
{"with plus", "user+tag@example.com", false},
{"with dots", "first.last@example.com", false},
// Invalid emails
{"empty string", "", true},
{"no at sign", "userexample.com", true},
{"no domain", "user@", true},
{"no local part", "@example.com", true},
{"double at", "user@@example.com", true},
{"spaces", "user @example.com", true},
{"no tld", "user@example", true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := ValidateEmail(tt.email)
if tt.wantErr && err == nil {
t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
}
if !tt.wantErr && err != nil {
t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
}
})
}
}
```
## Step 3: Run Tests - Verify FAIL
```bash
$ go test ./validator/...
--- FAIL: TestValidateEmail (0.00s)
--- FAIL: TestValidateEmail/simple_email (0.00s)
panic: not implemented
FAIL
```
✓ Tests fail as expected (panic).
## Step 4: Implement Minimal Code (GREEN)
```go
// validator/email.go
package validator
import (
"errors"
"regexp"
)
var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
var (
ErrEmailEmpty = errors.New("email cannot be empty")
ErrEmailInvalid = errors.New("email format is invalid")
)
func ValidateEmail(email string) error {
if email == "" {
return ErrEmailEmpty
}
if !emailRegex.MatchString(email) {
return ErrEmailInvalid
}
return nil
}
```
## Step 5: Run Tests - Verify PASS
```bash
$ go test ./validator/...
PASS
ok project/validator 0.003s
```
✓ All tests passing!
## Step 6: Check Coverage
```bash
$ go test -cover ./validator/...
PASS
coverage: 100.0% of statements
ok project/validator 0.003s
```
✓ Coverage: 100%
## TDD Complete!
````
## Padrões de Teste
### Table-Driven Tests
```go
tests := []struct {
name string
input InputType
want OutputType
wantErr bool
}{
{"case 1", input1, want1, false},
{"case 2", input2, want2, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
got, err := Function(tt.input)
// assertions
})
}
```
### Testes Paralelos
```go
for _, tt := range tests {
tt := tt // Capture
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
// test body
})
}
```
### Helpers de Teste
```go
func setupTestDB(t *testing.T) *sql.DB {
t.Helper()
db := createDB()
t.Cleanup(func() { db.Close() })
return db
}
```
## Comandos de Cobertura
```bash
# Basic coverage
go test -cover ./...
# Coverage profile
go test -coverprofile=coverage.out ./...
# View in browser
go tool cover -html=coverage.out
# Coverage by function
go tool cover -func=coverage.out
# With race detection
go test -race -cover ./...
```
## Metas de Cobertura
| Code Type | Target |
|-----------|--------|
| Critical business logic | 100% |
| Public APIs | 90%+ |
| General code | 80%+ |
| Generated code | Exclude |
## Boas Práticas de TDD
**DO:**
- Escreva teste PRIMEIRO, antes de qualquer implementação
- Rode testes após cada mudança
- Use table-driven tests para cobertura abrangente
- Teste comportamento, não detalhes de implementação
- Inclua casos de borda (empty, nil, max values)
**DON'T:**
- Escrever implementação antes dos testes
- Pular a fase RED
- Testar funções privadas diretamente
- Usar `time.Sleep` em testes
- Ignorar testes flaky
## Comandos Relacionados
- `/go-build` - Corrigir erros de build
- `/go-review` - Revisar código após implementação
- `/verify` - Rodar loop completo de verificação
## Relacionado
- Skill: `skills/golang-testing/`
- Skill: `skills/tdd-workflow/`

70
docs/pt-BR/commands/learn.md Normal file
View File

@@ -0,0 +1,70 @@
# /learn - Extrair Padrões Reutilizáveis
Analise a sessão atual e extraia padrões que valem ser salvos como skills.
## Trigger
Rode `/learn` em qualquer ponto da sessão quando você tiver resolvido um problema não trivial.
## O Que Extrair
Procure por:
1. **Padrões de Resolução de Erro**
- Qual erro ocorreu?
- Qual foi a causa raiz?
- O que corrigiu?
- Isso é reutilizável para erros semelhantes?
2. **Técnicas de Debug**
- Passos de debug não óbvios
- Combinações de ferramentas que funcionaram
- Padrões de diagnóstico
3. **Workarounds**
- Quirks de bibliotecas
- Limitações de API
- Correções específicas de versão
4. **Padrões Específicos do Projeto**
- Convenções de codebase descobertas
- Decisões de arquitetura tomadas
- Padrões de integração
## Formato de Saída
Crie um arquivo de skill em `~/.claude/skills/learned/[pattern-name].md`:
```markdown
# [Descriptive Pattern Name]
**Extracted:** [Date]
**Context:** [Brief description of when this applies]
## Problem
[What problem this solves - be specific]
## Solution
[The pattern/technique/workaround]
## Example
[Code example if applicable]
## When to Use
[Trigger conditions - what should activate this skill]
```
## Processo
1. Revise a sessão para identificar padrões extraíveis
2. Identifique o insight mais valioso/reutilizável
3. Esboce o arquivo de skill
4. Peça confirmação do usuário antes de salvar
5. Salve em `~/.claude/skills/learned/`
## Notas
- Não extraia correções triviais (typos, erros simples de sintaxe)
- Não extraia problemas de uso único (indisponibilidade específica de API etc.)
- Foque em padrões que vão economizar tempo em sessões futuras
- Mantenha skills focadas - um padrão por skill

231
docs/pt-BR/commands/orchestrate.md Normal file
View File

@@ -0,0 +1,231 @@
---
description: Orientação de orquestração sequencial e tmux/worktree para fluxos multiagente.
---
# Comando Orchestrate
Fluxo sequencial de agentes para tarefas complexas.
## Uso
`/orchestrate [workflow-type] [task-description]`
## Tipos de Workflow
### feature
Workflow completo de implementação de feature:
```
planner -> tdd-guide -> code-reviewer -> security-reviewer
```
### bugfix
Workflow de investigação e correção de bug:
```
planner -> tdd-guide -> code-reviewer
```
### refactor
Workflow de refatoração segura:
```
architect -> code-reviewer -> tdd-guide
```
### security
Revisão focada em segurança:
```
security-reviewer -> code-reviewer -> architect
```
## Padrão de Execução
Para cada agente no workflow:
1. **Invoque o agente** com contexto do agente anterior
2. **Colete saída** como documento estruturado de handoff
3. **Passe para o próximo agente** na cadeia
4. **Agregue resultados** em um relatório final
## Formato do Documento de Handoff
Entre agentes, crie um documento de handoff:
```markdown
## HANDOFF: [previous-agent] -> [next-agent]
### Context
[Summary of what was done]
### Findings
[Key discoveries or decisions]
### Files Modified
[List of files touched]
### Open Questions
[Unresolved items for next agent]
### Recommendations
[Suggested next steps]
```
## Exemplo: Workflow de Feature
```
/orchestrate feature "Add user authentication"
```
Executa:
1. **Planner Agent**
- Analisa requisitos
- Cria plano de implementação
- Identifica dependências
- Saída: `HANDOFF: planner -> tdd-guide`
2. **TDD Guide Agent**
- Lê handoff do planner
- Escreve testes primeiro
- Implementa para passar testes
- Saída: `HANDOFF: tdd-guide -> code-reviewer`
3. **Code Reviewer Agent**
- Revisa implementação
- Verifica problemas
- Sugere melhorias
- Saída: `HANDOFF: code-reviewer -> security-reviewer`
4. **Security Reviewer Agent**
- Auditoria de segurança
- Verificação de vulnerabilidades
- Aprovação final
- Saída: Relatório Final
## Formato do Relatório Final
```
ORCHESTRATION REPORT
====================
Workflow: feature
Task: Add user authentication
Agents: planner -> tdd-guide -> code-reviewer -> security-reviewer
SUMMARY
-------
[One paragraph summary]
AGENT OUTPUTS
-------------
Planner: [summary]
TDD Guide: [summary]
Code Reviewer: [summary]
Security Reviewer: [summary]
FILES CHANGED
-------------
[List all files modified]
TEST RESULTS
------------
[Test pass/fail summary]
SECURITY STATUS
---------------
[Security findings]
RECOMMENDATION
--------------
[SHIP / NEEDS WORK / BLOCKED]
```
## Execução Paralela
Para verificações independentes, rode agentes em paralelo:
```markdown
### Parallel Phase
Run simultaneously:
- code-reviewer (quality)
- security-reviewer (security)
- architect (design)
### Merge Results
Combine outputs into single report
```
Para workers externos em tmux panes com git worktrees separados, use `node scripts/orchestrate-worktrees.js plan.json --execute`. O padrão embutido de orquestração permanece no processo atual; o helper é para sessões longas ou cross-harness.
Quando os workers precisarem enxergar arquivos locais sujos ou não rastreados do checkout principal, adicione `seedPaths` ao arquivo de plano. O ECC faz overlay apenas desses caminhos selecionados em cada worktree do worker após `git worktree add`, mantendo o branch isolado e ainda expondo scripts, planos ou docs em andamento.
```json
{
"sessionName": "workflow-e2e",
"seedPaths": [
"scripts/orchestrate-worktrees.js",
"scripts/lib/tmux-worktree-orchestrator.js",
".claude/plan/workflow-e2e-test.json"
],
"workers": [
{ "name": "docs", "task": "Update orchestration docs." }
]
}
```
Para exportar um snapshot do control plane para uma sessão tmux/worktree ao vivo, rode:
```bash
node scripts/orchestration-status.js .claude/plan/workflow-visual-proof.json
```
O snapshot inclui atividade da sessão, metadados de pane do tmux, estado dos workers, objetivos, overlays semeados e resumos recentes de handoff em formato JSON.
## Handoff de Command Center do Operador
Quando o workflow atravessar múltiplas sessões, worktrees ou panes tmux, acrescente um bloco de control plane ao handoff final:
```markdown
CONTROL PLANE
-------------
Sessions:
- active session ID or alias
- branch + worktree path for each active worker
- tmux pane or detached session name when applicable
Diffs:
- git status summary
- git diff --stat for touched files
- merge/conflict risk notes
Approvals:
- pending user approvals
- blocked steps awaiting confirmation
Telemetry:
- last activity timestamp or idle signal
- estimated token or cost drift
- policy events raised by hooks or reviewers
```
Isso mantém planner, implementador, revisor e loop workers legíveis pela superfície de operação.
## Argumentos
$ARGUMENTS:
- `feature <description>` - Workflow completo de feature
- `bugfix <description>` - Workflow de correção de bug
- `refactor <description>` - Workflow de refatoração
- `security <description>` - Workflow de revisão de segurança
- `custom <agents> <description>` - Sequência customizada de agentes
## Exemplo de Workflow Customizado
```
/orchestrate custom "architect,tdd-guide,code-reviewer" "Redesign caching layer"
```
## Dicas
1. **Comece com planner** para features complexas
2. **Sempre inclua code-reviewer** antes do merge
3. **Use security-reviewer** para auth/pagamento/PII
4. **Mantenha handoffs concisos** - foque no que o próximo agente precisa
5. **Rode verificação** entre agentes quando necessário

115
docs/pt-BR/commands/plan.md Normal file
View File

@@ -0,0 +1,115 @@
---
description: Reafirme requisitos, avalie riscos e crie plano de implementação passo a passo. ESPERE confirmação do usuário ANTES de tocar em qualquer código.
---
# Comando Plan
Este comando invoca o agente **planner** para criar um plano abrangente de implementação antes de escrever qualquer código.
## O Que Este Comando Faz
1. **Reafirmar Requisitos** - Esclarecer o que precisa ser construído
2. **Identificar Riscos** - Levantar problemas e bloqueios potenciais
3. **Criar Plano em Etapas** - Quebrar implementação em fases
4. **Aguardar Confirmação** - DEVE receber aprovação do usuário antes de prosseguir
## Quando Usar
Use `/plan` quando:
- Estiver iniciando uma nova feature
- For fazer mudanças arquiteturais significativas
- Estiver trabalhando em refatoração complexa
- Múltiplos arquivos/componentes serão afetados
- Requisitos estiverem pouco claros ou ambíguos
## Como Funciona
O agente planner vai:
1. **Analisar o pedido** e reafirmar os requisitos de forma clara
2. **Quebrar em fases** com etapas específicas e acionáveis
3. **Identificar dependências** entre componentes
4. **Avaliar riscos** e possíveis bloqueios
5. **Estimar complexidade** (High/Medium/Low)
6. **Apresentar o plano** e AGUARDAR sua confirmação explícita
## Exemplo de Uso
```
User: /plan I need to add real-time notifications when markets resolve
Agent (planner):
# Implementation Plan: Real-Time Market Resolution Notifications
## Requirements Restatement
- Send notifications to users when markets they're watching resolve
- Support multiple notification channels (in-app, email, webhook)
- Ensure notifications are delivered reliably
- Include market outcome and user's position result
## Implementation Phases
### Phase 1: Database Schema
- Add notifications table with columns: id, user_id, market_id, type, status, created_at
- Add user_notification_preferences table for channel preferences
- Create indexes on user_id and market_id for performance
### Phase 2: Notification Service
- Create notification service in lib/notifications.ts
- Implement notification queue using BullMQ/Redis
- Add retry logic for failed deliveries
- Create notification templates
### Phase 3: Integration Points
- Hook into market resolution logic (when status changes to "resolved")
- Query all users with positions in market
- Enqueue notifications for each user
### Phase 4: Frontend Components
- Create NotificationBell component in header
- Add NotificationList modal
- Implement real-time updates via Supabase subscriptions
- Add notification preferences page
## Dependencies
- Redis (for queue)
- Email service (SendGrid/Resend)
- Supabase real-time subscriptions
## Risks
- HIGH: Email deliverability (SPF/DKIM required)
- MEDIUM: Performance with 1000+ users per market
- MEDIUM: Notification spam if markets resolve frequently
- LOW: Real-time subscription overhead
## Estimated Complexity: MEDIUM
- Backend: 4-6 hours
- Frontend: 3-4 hours
- Testing: 2-3 hours
- Total: 9-13 hours
**WAITING FOR CONFIRMATION**: Proceed with this plan? (yes/no/modify)
```
## Notas Importantes
**CRITICAL**: O agente planner **NÃO** vai escrever código até você confirmar explicitamente o plano com "yes", "proceed" ou resposta afirmativa similar.
Se quiser mudanças, responda com:
- "modify: [your changes]"
- "different approach: [alternative]"
- "skip phase 2 and do phase 3 first"
## Integração com Outros Comandos
Após planejar:
- Use `/tdd` para implementar com test-driven development
- Use `/build-fix` se ocorrerem erros de build
- Use `/code-review` para revisar a implementação concluída
## Agentes Relacionados
Este comando invoca o agente `planner` fornecido pelo ECC.
Para instalações manuais, o arquivo fonte fica em:
`agents/planner.md`

80
docs/pt-BR/commands/refactor-clean.md Normal file
View File

@@ -0,0 +1,80 @@
# Refactor Clean
Identifique e remova código morto com segurança, com verificação de testes em cada passo.
## Passo 1: Detectar Código Morto
Rode ferramentas de análise com base no tipo do projeto:
| Tool | What It Finds | Command |
|------|--------------|---------|
| knip | Unused exports, files, dependencies | `npx knip` |
| depcheck | Unused npm dependencies | `npx depcheck` |
| ts-prune | Unused TypeScript exports | `npx ts-prune` |
| vulture | Unused Python code | `vulture src/` |
| deadcode | Unused Go code | `deadcode ./...` |
| cargo-udeps | Unused Rust dependencies | `cargo +nightly udeps` |
Se nenhuma ferramenta estiver disponível, use Grep para encontrar exports com zero imports:
```
# Find exports, then check if they're imported anywhere
```
## Passo 2: Categorizar Achados
Classifique os achados em níveis de segurança:
| Tier | Examples | Action |
|------|----------|--------|
| **SAFE** | Unused utilities, test helpers, internal functions | Delete with confidence |
| **CAUTION** | Components, API routes, middleware | Verify no dynamic imports or external consumers |
| **DANGER** | Config files, entry points, type definitions | Investigate before touching |
## Passo 3: Loop de Remoção Segura
Para cada item SAFE:
1. **Rode a suíte completa de testes** — Estabeleça baseline (tudo verde)
2. **Delete o código morto** — Use a ferramenta Edit para remoção cirúrgica
3. **Rode a suíte de testes novamente** — Verifique se nada quebrou
4. **Se testes falharem** — Reverta imediatamente com `git checkout -- <file>` e pule este item
5. **Se testes passarem** — Vá para o próximo item
## Passo 4: Tratar Itens CAUTION
Antes de deletar itens CAUTION:
- Procure imports dinâmicos: `import()`, `require()`, `__import__`
- Procure referências em string: nomes de rota, nomes de componente em configs
- Verifique se é exportado por API pública de pacote
- Verifique ausência de consumidores externos (dependents, se publicado)
## Passo 5: Consolidar Duplicatas
Depois de remover código morto, procure:
- Funções quase duplicadas (>80% similares) — mesclar em uma
- Definições de tipo redundantes — consolidar
- Funções wrapper sem valor — inline
- Re-exports sem propósito — remover indireção
## Passo 6: Resumo
Reporte resultados:
```
Dead Code Cleanup
──────────────────────────────
Deleted: 12 unused functions
3 unused files
5 unused dependencies
Skipped: 2 items (tests failed)
Saved: ~450 lines removed
──────────────────────────────
All tests passing ✅
```
## Regras
- **Nunca delete sem rodar testes antes**
- **Uma remoção por vez** — Mudanças atômicas facilitam rollback
- **Se houver dúvida, pule** — Melhor manter código morto do que quebrar produção
- **Não refatore durante limpeza** — Separe responsabilidades (limpar primeiro, refatorar depois)

80
docs/pt-BR/commands/setup-pm.md Normal file
View File

@@ -0,0 +1,80 @@
---
description: Configure seu package manager preferido (npm/pnpm/yarn/bun)
disable-model-invocation: true
---
# Configuração de Package Manager
Configure seu package manager preferido para este projeto ou globalmente.
## Uso
```bash
# Detect current package manager
node scripts/setup-package-manager.js --detect
# Set global preference
node scripts/setup-package-manager.js --global pnpm
# Set project preference
node scripts/setup-package-manager.js --project bun
# List available package managers
node scripts/setup-package-manager.js --list
```
## Prioridade de Detecção
Ao determinar qual package manager usar, esta ordem é verificada:
1. **Environment variable**: `CLAUDE_PACKAGE_MANAGER`
2. **Project config**: `.claude/package-manager.json`
3. **package.json**: `packageManager` field
4. **Lock file**: Presence of package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
5. **Global config**: `~/.claude/package-manager.json`
6. **Fallback**: First available package manager (pnpm > bun > yarn > npm)
## Arquivos de Configuração
### Configuração Global
```json
// ~/.claude/package-manager.json
{
"packageManager": "pnpm"
}
```
### Configuração do Projeto
```json
// .claude/package-manager.json
{
"packageManager": "bun"
}
```
### package.json
```json
{
"packageManager": "pnpm@8.6.0"
}
```
## Variável de Ambiente
Defina `CLAUDE_PACKAGE_MANAGER` para sobrescrever todos os outros métodos de detecção:
```bash
# Windows (PowerShell)
$env:CLAUDE_PACKAGE_MANAGER = "pnpm"
# macOS/Linux
export CLAUDE_PACKAGE_MANAGER=pnpm
```
## Rodar a Detecção
Para ver os resultados atuais da detecção de package manager, rode:
```bash
node scripts/setup-package-manager.js --detect
```

328
docs/pt-BR/commands/tdd.md Normal file
View File

@@ -0,0 +1,328 @@
---
description: Impõe fluxo de desenvolvimento orientado a testes. Estruture interfaces, gere testes PRIMEIRO e depois implemente código mínimo para passar. Garanta cobertura de 80%+.
---
# Comando TDD
Este comando invoca o agente **tdd-guide** para impor a metodologia de desenvolvimento orientado a testes.
## O Que Este Comando Faz
1. **Estruturar Interfaces** - Definir tipos/interfaces primeiro
2. **Gerar Testes Primeiro** - Escrever testes que falham (RED)
3. **Implementar Código Mínimo** - Escrever apenas o suficiente para passar (GREEN)
4. **Refatorar** - Melhorar o código mantendo testes verdes (REFACTOR)
5. **Verificar Cobertura** - Garantir cobertura de testes de 80%+
## Quando Usar
Use `/tdd` quando:
- Implementar novas features
- Adicionar novas funções/componentes
- Corrigir bugs (escrever primeiro teste que reproduz o bug)
- Refatorar código existente
- Construir lógica de negócio crítica
## Como Funciona
O agente tdd-guide vai:
1. **Definir interfaces** para entradas/saídas
2. **Escrever testes que vão FALHAR** (porque o código ainda não existe)
3. **Rodar testes** e verificar que falham pelo motivo correto
4. **Escrever implementação mínima** para fazer testes passarem
5. **Rodar testes** e verificar que passam
6. **Refatorar** código mantendo testes verdes
7. **Checar cobertura** e adicionar mais testes se estiver abaixo de 80%
## Ciclo TDD
```
RED → GREEN → REFACTOR → REPEAT
RED: Write a failing test
GREEN: Write minimal code to pass
REFACTOR: Improve code, keep tests passing
REPEAT: Next feature/scenario
```
## Exemplo de Uso
```
User: /tdd I need a function to calculate market liquidity score
Agent (tdd-guide):
# TDD Session: Market Liquidity Score Calculator
## Step 1: Define Interface (SCAFFOLD)
```typescript
// lib/liquidity.ts
export interface MarketData {
totalVolume: number
bidAskSpread: number
activeTraders: number
lastTradeTime: Date
}
export function calculateLiquidityScore(market: MarketData): number {
// TODO: Implementation
throw new Error('Not implemented')
}
```
## Step 2: Write Failing Test (RED)
```typescript
// lib/liquidity.test.ts
import { calculateLiquidityScore } from './liquidity'
describe('calculateLiquidityScore', () => {
it('should return high score for liquid market', () => {
const market = {
totalVolume: 100000,
bidAskSpread: 0.01,
activeTraders: 500,
lastTradeTime: new Date()
}
const score = calculateLiquidityScore(market)
expect(score).toBeGreaterThan(80)
expect(score).toBeLessThanOrEqual(100)
})
it('should return low score for illiquid market', () => {
const market = {
totalVolume: 100,
bidAskSpread: 0.5,
activeTraders: 2,
lastTradeTime: new Date(Date.now() - 86400000) // 1 day ago
}
const score = calculateLiquidityScore(market)
expect(score).toBeLessThan(30)
expect(score).toBeGreaterThanOrEqual(0)
})
it('should handle edge case: zero volume', () => {
const market = {
totalVolume: 0,
bidAskSpread: 0,
activeTraders: 0,
lastTradeTime: new Date()
}
const score = calculateLiquidityScore(market)
expect(score).toBe(0)
})
})
```
## Step 3: Run Tests - Verify FAIL
```bash
npm test lib/liquidity.test.ts
FAIL lib/liquidity.test.ts
✕ should return high score for liquid market (2 ms)
Error: Not implemented
1 test failed, 0 passed
```
✅ Tests fail as expected. Ready to implement.
## Step 4: Implement Minimal Code (GREEN)
```typescript
// lib/liquidity.ts
export function calculateLiquidityScore(market: MarketData): number {
// Handle zero volume edge case
if (market.totalVolume === 0) {
return 0
}
// Calculate component scores (0-100 scale)
const volumeScore = Math.min(market.totalVolume / 1000, 100)
const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
const traderScore = Math.min(market.activeTraders / 10, 100)
// Recent activity bonus
const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)
// Weighted average
const score = (
volumeScore * 0.4 +
spreadScore * 0.3 +
traderScore * 0.2 +
recencyScore * 0.1
)
return Math.min(Math.max(score, 0), 100) // Clamp to 0-100
}
```
## Step 5: Run Tests - Verify PASS
```bash
npm test lib/liquidity.test.ts
PASS lib/liquidity.test.ts
✓ should return high score for liquid market (3 ms)
✓ should return low score for illiquid market (2 ms)
✓ should handle edge case: zero volume (1 ms)
3 tests passed
```
✅ All tests passing!
## Step 6: Refactor (IMPROVE)
```typescript
// lib/liquidity.ts - Refactored with constants and better readability
const WEIGHTS = {
VOLUME: 0.4,
SPREAD: 0.3,
TRADERS: 0.2,
RECENCY: 0.1,
} as const
const SCALE_FACTORS = {
VOLUME: 1000,
SPREAD: 1000,
TRADERS: 10,
RECENCY_PENALTY: 10,
} as const
function clamp(value: number, min: number, max: number): number {
return Math.min(Math.max(value, min), max)
}
export function calculateLiquidityScore(market: MarketData): number {
if (market.totalVolume === 0) return 0
const volumeScore = Math.min(market.totalVolume / SCALE_FACTORS.VOLUME, 100)
const spreadScore = clamp(100 - (market.bidAskSpread * SCALE_FACTORS.SPREAD), 0, 100)
const traderScore = Math.min(market.activeTraders / SCALE_FACTORS.TRADERS, 100)
const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) / (1000 * 60 * 60)
const recencyScore = clamp(100 - (hoursSinceLastTrade * SCALE_FACTORS.RECENCY_PENALTY), 0, 100)
const weightedScore =
volumeScore * WEIGHTS.VOLUME +
spreadScore * WEIGHTS.SPREAD +
traderScore * WEIGHTS.TRADERS +
recencyScore * WEIGHTS.RECENCY
return clamp(weightedScore, 0, 100)
}
```
## Step 7: Verify Tests Still Pass
```bash
npm test lib/liquidity.test.ts
PASS lib/liquidity.test.ts
✓ should return high score for liquid market (3 ms)
✓ should return low score for illiquid market (2 ms)
✓ should handle edge case: zero volume (1 ms)
3 tests passed
```
✅ Refactoring complete, tests still passing!
## Step 8: Check Coverage
```bash
npm test -- --coverage lib/liquidity.test.ts
File | % Stmts | % Branch | % Funcs | % Lines
---------------|---------|----------|---------|--------
liquidity.ts | 100 | 100 | 100 | 100
Coverage: 100% ✅ (Target: 80%)
```
✅ TDD session complete!
```
## Boas Práticas de TDD
**DO:**
- ✅ Escreva o teste PRIMEIRO, antes da implementação
- ✅ Rode testes e confirme que FALHAM antes de implementar
- ✅ Escreva código mínimo para fazer passar
- ✅ Refatore só depois que os testes estiverem verdes
- ✅ Adicione casos de borda e cenários de erro
- ✅ Mire 80%+ de cobertura (100% para código crítico)
**DON'T:**
- ❌ Escrever implementação antes de testes
- ❌ Pular execução de testes após cada mudança
- ❌ Escrever código demais de uma vez
- ❌ Ignorar testes falhando
- ❌ Testar detalhes de implementação (teste comportamento)
- ❌ Fazer mock de tudo (prefira testes de integração)
## Tipos de Teste a Incluir
**Testes Unitários** (nível de função):
- Cenários happy path
- Casos de borda (vazio, null, valores máximos)
- Condições de erro
- Valores de fronteira
**Testes de Integração** (nível de componente):
- Endpoints de API
- Operações de banco de dados
- Chamadas a serviços externos
- Componentes React com hooks
**Testes E2E** (use comando `/e2e`):
- Fluxos críticos de usuário
- Processos multi-etapa
- Integração full stack
## Requisitos de Cobertura
- **Mínimo de 80%** para todo o código
- **100% obrigatório** para:
- Cálculos financeiros
- Lógica de autenticação
- Código crítico de segurança
- Lógica de negócio central
## Notas Importantes
**MANDATÓRIO**: Os testes devem ser escritos ANTES da implementação. O ciclo TDD é:
1. **RED** - Escrever teste que falha
2. **GREEN** - Implementar para passar
3. **REFACTOR** - Melhorar código
Nunca pule a fase RED. Nunca escreva código antes dos testes.
## Integração com Outros Comandos
- Use `/plan` primeiro para entender o que construir
- Use `/tdd` para implementar com testes
- Use `/build-fix` se ocorrerem erros de build
- Use `/code-review` para revisar implementação
- Use `/test-coverage` para verificar cobertura
## Agentes Relacionados
Este comando invoca o agente `tdd-guide` fornecido pelo ECC.
A skill relacionada `tdd-workflow` também é distribuída com o ECC.
Para instalações manuais, os arquivos fonte ficam em:
- `agents/tdd-guide.md`
- `skills/tdd-workflow/SKILL.md`

69
docs/pt-BR/commands/test-coverage.md Normal file
View File

@@ -0,0 +1,69 @@
# Cobertura de Testes
Analise cobertura de testes, identifique lacunas e gere testes faltantes para alcançar cobertura de 80%+.
## Passo 1: Detectar Framework de Teste
| Indicator | Coverage Command |
|-----------|-----------------|
| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
| `vitest.config.*` | `npx vitest run --coverage` |
| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
| `Cargo.toml` | `cargo llvm-cov --json` |
| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
| `go.mod` | `go test -coverprofile=coverage.out ./...` |
## Passo 2: Analisar Relatório de Cobertura
1. Rode o comando de cobertura
2. Parseie a saída (resumo em JSON ou saída de terminal)
3. Liste arquivos **abaixo de 80% de cobertura**, ordenados do pior para o melhor
4. Para cada arquivo abaixo da meta, identifique:
- Funções ou métodos sem teste
- Cobertura de branch faltante (if/else, switch, caminhos de erro)
- Código morto que infla o denominador
## Passo 3: Gerar Testes Faltantes
Para cada arquivo abaixo da meta, gere testes seguindo esta prioridade:
1. **Happy path** — Funcionalidade principal com entradas válidas
2. **Tratamento de erro** — Entradas inválidas, dados ausentes, falhas de rede
3. **Casos de borda** — Arrays vazios, null/undefined, valores de fronteira (0, -1, MAX_INT)
4. **Cobertura de branch** — Cada if/else, caso de switch, ternário
### Regras para Geração de Testes
- Coloque testes adjacentes ao código-fonte: `foo.ts` → `foo.test.ts` (ou convenção do projeto)
- Use padrões de teste existentes do projeto (estilo de import, biblioteca de asserção, abordagem de mocking)
- Faça mock de dependências externas (banco, APIs, sistema de arquivos)
- Cada teste deve ser independente — sem estado mutável compartilhado entre testes
- Nomeie testes de forma descritiva: `test_create_user_with_duplicate_email_returns_409`
## Passo 4: Verificar
1. Rode a suíte completa de testes — todos os testes devem passar
2. Rode cobertura novamente — confirme a melhoria
3. Se ainda estiver abaixo de 80%, repita o Passo 3 para as lacunas restantes
## Passo 5: Reportar
Mostre comparação antes/depois:
```
Coverage Report
──────────────────────────────
File Before After
src/services/auth.ts 45% 88%
src/utils/validation.ts 32% 82%
──────────────────────────────
Overall: 67% 84% ✅
```
## Áreas de Foco
- Funções com branching complexo (alta complexidade ciclomática)
- Error handlers e blocos catch
- Funções utilitárias usadas em todo o codebase
- Handlers de endpoint de API (fluxo request → response)
- Casos de borda: null, undefined, string vazia, array vazio, zero, números negativos

72
docs/pt-BR/commands/update-codemaps.md Normal file
View File

@@ -0,0 +1,72 @@
# Atualizar Codemaps
Analise a estrutura do codebase e gere documentação arquitetural enxuta em tokens.
## Passo 1: Escanear Estrutura do Projeto
1. Identifique o tipo de projeto (monorepo, app única, library, microservice)
2. Encontre todos os diretórios de código-fonte (src/, lib/, app/, packages/)
3. Mapeie entry points (main.ts, index.ts, app.py, main.go, etc.)
## Passo 2: Gerar Codemaps
Crie ou atualize codemaps em `docs/CODEMAPS/` (ou `.reports/codemaps/`):
| File | Contents |
|------|----------|
| `architecture.md` | High-level system diagram, service boundaries, data flow |
| `backend.md` | API routes, middleware chain, service → repository mapping |
| `frontend.md` | Page tree, component hierarchy, state management flow |
| `data.md` | Database tables, relationships, migration history |
| `dependencies.md` | External services, third-party integrations, shared libraries |
### Formato de Codemap
Cada codemap deve ser enxuto em tokens — otimizado para consumo de contexto por IA:
```markdown
# Backend Architecture
## Routes
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET /api/users/:id → UserController.get → UserService.findById → UserRepo.findById
## Key Files
src/services/user.ts (business logic, 120 lines)
src/repos/user.ts (database access, 80 lines)
## Dependencies
- PostgreSQL (primary data store)
- Redis (session cache, rate limiting)
- Stripe (payment processing)
```
## Passo 3: Detecção de Diff
1. Se codemaps anteriores existirem, calcule a porcentagem de diff
2. Se mudanças > 30%, mostre o diff e solicite aprovação do usuário antes de sobrescrever
3. Se mudanças <= 30%, atualize in-place
## Passo 4: Adicionar Metadados
Adicione um cabeçalho de freshness em cada codemap:
```markdown
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
```
## Passo 5: Salvar Relatório de Análise
Escreva um resumo em `.reports/codemap-diff.txt`:
- Arquivos adicionados/removidos/modificados desde o último scan
- Novas dependências detectadas
- Mudanças de arquitetura (novas rotas, novos serviços etc.)
- Alertas de obsolescência para docs sem atualização em 90+ dias
## Dicas
- Foque em **estrutura de alto nível**, não em detalhes de implementação
- Prefira **caminhos de arquivo e assinaturas de função** em vez de blocos de código completos
- Mantenha cada codemap abaixo de **1000 tokens** para carregamento eficiente de contexto
- Use diagramas ASCII para fluxo de dados em vez de descrições verbosas
- Rode após grandes adições de feature ou sessões de refatoração

84
docs/pt-BR/commands/update-docs.md Normal file
View File

@@ -0,0 +1,84 @@
# 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:
```markdown
| 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
```markdown
| 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

59
docs/pt-BR/commands/verify.md Normal file
View File

@@ -0,0 +1,59 @@
# Comando Verification
Rode verificação abrangente no estado atual do codebase.
## Instruções
Execute a verificação nesta ordem exata:
1. **Build Check**
- Rode o comando de build deste projeto
- Se falhar, reporte erros e PARE
2. **Type Check**
- Rode o TypeScript/type checker
- Reporte todos os erros com file:line
3. **Lint Check**
- Rode o linter
- Reporte warnings e errors
4. **Test Suite**
- Rode todos os testes
- Reporte contagem de pass/fail
- Reporte percentual de cobertura
5. **Console.log Audit**
- Procure por console.log em arquivos de código-fonte
- Reporte localizações
6. **Git Status**
- Mostre mudanças não commitadas
- Mostre arquivos modificados desde o último commit
## Saída
Produza um relatório conciso de verificação:
```
VERIFICATION: [PASS/FAIL]
Build: [OK/FAIL]
Types: [OK/X errors]
Lint: [OK/X issues]
Tests: [X/Y passed, Z% coverage]
Secrets: [OK/X found]
Logs: [OK/X console.logs]
Ready for PR: [YES/NO]
```
Se houver problemas críticos, liste-os com sugestões de correção.
## Argumentos
$ARGUMENTS podem ser:
- `quick` - Apenas build + types
- `full` - Todas as checagens (padrão)
- `pre-commit` - Checagens relevantes para commits
- `pre-pr` - Checagens completas mais security scan