kakaroto-config 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +48 -0
- package/bin/install.js +101 -0
- package/config/ARCHITECTURE.md +474 -0
- package/config/CLAUDE.md +24 -0
- package/config/agents/code-reviewer.md +265 -0
- package/config/agents/code-simplifier.md +151 -0
- package/config/agents/dry-enforcer.md +227 -0
- package/config/agents/memory-sync.md +140 -0
- package/config/agents/terraform-validator.md +275 -0
- package/config/agents/test-fixer.md +355 -0
- package/config/agents/visual-validator.md +296 -0
- package/config/commands/debug/01-investigate.md +119 -0
- package/config/commands/debug/02-fix.md +108 -0
- package/config/commands/debug/03-verify.md +66 -0
- package/config/commands/debug.md +19 -0
- package/config/commands/feature/01-interview.md +151 -0
- package/config/commands/feature/02-spec.md +174 -0
- package/config/commands/feature/03-planner.md +123 -0
- package/config/commands/feature/04-implement.md +74 -0
- package/config/commands/feature/05-quality.md +122 -0
- package/config/commands/feature.md +19 -0
- package/config/commands/gate.md +313 -0
- package/package.json +26 -0
package/README.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# kakaroto-config
|
|
2
|
+
|
|
3
|
+
Claude Code configuration for autonomous development workflows.
|
|
4
|
+
|
|
5
|
+
## Quick Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npx kakaroto-config
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
This installs the configuration to `~/.claude/`.
|
|
12
|
+
|
|
13
|
+
## What's Included
|
|
14
|
+
|
|
15
|
+
### Skills (Commands)
|
|
16
|
+
|
|
17
|
+
| Skill | Description |
|
|
18
|
+
|-------|-------------|
|
|
19
|
+
| `/feature` | Full feature development workflow (interview → spec → plan → implement → quality) |
|
|
20
|
+
| `/debug` | Bug resolution with 5 Whys methodology (investigate → fix → verify) |
|
|
21
|
+
| `/gate` | Quality gate before PR (runs 7 validation agents) |
|
|
22
|
+
|
|
23
|
+
### Agents (Subagents)
|
|
24
|
+
|
|
25
|
+
| Agent | Purpose |
|
|
26
|
+
|-------|---------|
|
|
27
|
+
| `test-fixer` | Runs tests, fixes failures, creates missing tests |
|
|
28
|
+
| `code-reviewer` | Reviews code quality, security, auto-fixes issues |
|
|
29
|
+
| `code-simplifier` | Reduces complexity, improves readability |
|
|
30
|
+
| `dry-enforcer` | Detects duplication, suggests reuse |
|
|
31
|
+
| `visual-validator` | Validates UI with Playwright |
|
|
32
|
+
| `terraform-validator` | Validates env vars and Terraform consistency |
|
|
33
|
+
| `memory-sync` | Syncs knowledge to MCP Memory |
|
|
34
|
+
|
|
35
|
+
## Philosophy
|
|
36
|
+
|
|
37
|
+
- **FAZER, não perguntar** - Agents fix issues automatically
|
|
38
|
+
- **BUSCAR, não pedir contexto** - Use MCP Memory and codebase exploration
|
|
39
|
+
- **Código sem teste = PR rejeitado** - Tests are mandatory
|
|
40
|
+
- **Erros: corrigir e continuar** - Don't stop on failures
|
|
41
|
+
|
|
42
|
+
## Documentation
|
|
43
|
+
|
|
44
|
+
After installation, read `~/.claude/ARCHITECTURE.md` for full documentation.
|
|
45
|
+
|
|
46
|
+
## License
|
|
47
|
+
|
|
48
|
+
MIT
|
package/bin/install.js
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
const fs = require('fs');
|
|
4
|
+
const path = require('path');
|
|
5
|
+
const os = require('os');
|
|
6
|
+
const readline = require('readline');
|
|
7
|
+
|
|
8
|
+
const CLAUDE_DIR = path.join(os.homedir(), '.claude');
|
|
9
|
+
const CONFIG_DIR = path.join(__dirname, '..', 'config');
|
|
10
|
+
|
|
11
|
+
const rl = readline.createInterface({
|
|
12
|
+
input: process.stdin,
|
|
13
|
+
output: process.stdout
|
|
14
|
+
});
|
|
15
|
+
|
|
16
|
+
function question(prompt) {
|
|
17
|
+
return new Promise((resolve) => {
|
|
18
|
+
rl.question(prompt, resolve);
|
|
19
|
+
});
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function copyRecursive(src, dest) {
|
|
23
|
+
const stats = fs.statSync(src);
|
|
24
|
+
|
|
25
|
+
if (stats.isDirectory()) {
|
|
26
|
+
if (!fs.existsSync(dest)) {
|
|
27
|
+
fs.mkdirSync(dest, { recursive: true });
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
const files = fs.readdirSync(src);
|
|
31
|
+
for (const file of files) {
|
|
32
|
+
copyRecursive(path.join(src, file), path.join(dest, file));
|
|
33
|
+
}
|
|
34
|
+
} else {
|
|
35
|
+
fs.copyFileSync(src, dest);
|
|
36
|
+
console.log(` + ${path.relative(CLAUDE_DIR, dest)}`);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function countFiles(dir) {
|
|
41
|
+
let count = 0;
|
|
42
|
+
const items = fs.readdirSync(dir);
|
|
43
|
+
for (const item of items) {
|
|
44
|
+
const fullPath = path.join(dir, item);
|
|
45
|
+
if (fs.statSync(fullPath).isDirectory()) {
|
|
46
|
+
count += countFiles(fullPath);
|
|
47
|
+
} else {
|
|
48
|
+
count++;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
return count;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
async function main() {
|
|
55
|
+
console.log('\n🥋 kakaroto-config - Claude Code Configuration\n');
|
|
56
|
+
console.log('This will install the following to ~/.claude/:');
|
|
57
|
+
console.log(' - CLAUDE.md (global rules)');
|
|
58
|
+
console.log(' - ARCHITECTURE.md (documentation)');
|
|
59
|
+
console.log(' - commands/ (skills: /feature, /debug, /gate)');
|
|
60
|
+
console.log(' - agents/ (7 specialized subagents)\n');
|
|
61
|
+
|
|
62
|
+
const fileCount = countFiles(CONFIG_DIR);
|
|
63
|
+
console.log(`Total: ${fileCount} files\n`);
|
|
64
|
+
|
|
65
|
+
if (fs.existsSync(CLAUDE_DIR)) {
|
|
66
|
+
const answer = await question('~/.claude/ already exists. Overwrite? (y/N): ');
|
|
67
|
+
if (answer.toLowerCase() !== 'y') {
|
|
68
|
+
console.log('\nAborted. No changes made.');
|
|
69
|
+
rl.close();
|
|
70
|
+
process.exit(0);
|
|
71
|
+
}
|
|
72
|
+
console.log('\nOverwriting existing config...\n');
|
|
73
|
+
} else {
|
|
74
|
+
const answer = await question('Proceed with installation? (Y/n): ');
|
|
75
|
+
if (answer.toLowerCase() === 'n') {
|
|
76
|
+
console.log('\nAborted. No changes made.');
|
|
77
|
+
rl.close();
|
|
78
|
+
process.exit(0);
|
|
79
|
+
}
|
|
80
|
+
console.log('\nInstalling config...\n');
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
try {
|
|
84
|
+
copyRecursive(CONFIG_DIR, CLAUDE_DIR);
|
|
85
|
+
|
|
86
|
+
console.log('\n✅ Installation complete!\n');
|
|
87
|
+
console.log('Next steps:');
|
|
88
|
+
console.log(' 1. Open any project with Claude Code');
|
|
89
|
+
console.log(' 2. Try /feature to create a new feature');
|
|
90
|
+
console.log(' 3. Try /debug to fix a bug');
|
|
91
|
+
console.log(' 4. Try /gate before creating a PR\n');
|
|
92
|
+
console.log('Read ~/.claude/ARCHITECTURE.md for full documentation.\n');
|
|
93
|
+
} catch (err) {
|
|
94
|
+
console.error('Error during installation:', err.message);
|
|
95
|
+
process.exit(1);
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
rl.close();
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
main();
|
|
@@ -0,0 +1,474 @@
|
|
|
1
|
+
# Claude Code Configuration Architecture
|
|
2
|
+
|
|
3
|
+
Este documento descreve a arquitetura de configuracao do Claude Code, otimizada para **autonomia maxima** e **contexto minimo**.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Visao Geral
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
┌─────────────────────────────────────────────────────────────────────────────┐
|
|
11
|
+
│ CONFIGURACAO CLAUDE CODE │
|
|
12
|
+
├─────────────────────────────────────────────────────────────────────────────┤
|
|
13
|
+
│ │
|
|
14
|
+
│ ~/.claude/ (GLOBAL) projeto/.claude/ (LOCAL) │
|
|
15
|
+
│ ━━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━ │
|
|
16
|
+
│ │
|
|
17
|
+
│ ┌─────────────┐ ┌─────────────┐ │
|
|
18
|
+
│ │ CLAUDE.md │ ◄──── herda ──────────►│ CLAUDE.md │ │
|
|
19
|
+
│ │ (regras) │ │ (projeto) │ │
|
|
20
|
+
│ └─────────────┘ └─────────────┘ │
|
|
21
|
+
│ │ │ │
|
|
22
|
+
│ ▼ ▼ │
|
|
23
|
+
│ ┌─────────────┐ ┌─────────────┐ │
|
|
24
|
+
│ │ commands/ │ │ commands/ │ │
|
|
25
|
+
│ │ (skills) │ │ (skills) │ │
|
|
26
|
+
│ └─────────────┘ └─────────────┘ │
|
|
27
|
+
│ │ │ │
|
|
28
|
+
│ ▼ │ │
|
|
29
|
+
│ ┌─────────────┐ │ │
|
|
30
|
+
│ │ agents/ │ ◄─── chamados por ────────────┘ │
|
|
31
|
+
│ │(subagentes) │ │
|
|
32
|
+
│ └─────────────┘ │
|
|
33
|
+
│ │
|
|
34
|
+
└─────────────────────────────────────────────────────────────────────────────┘
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Principio: Contexto Minimo por Camada
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
┌───────────────────────┐
|
|
43
|
+
│ CLAUDE.md │ ~25 linhas
|
|
44
|
+
│ (regras essenciais) │ Carregado SEMPRE
|
|
45
|
+
└───────────┬───────────┘
|
|
46
|
+
│
|
|
47
|
+
Trigger: "/feature" ou "/debug"
|
|
48
|
+
│
|
|
49
|
+
▼
|
|
50
|
+
┌───────────────────────┐
|
|
51
|
+
│ commands/*.md │ ~20 linhas
|
|
52
|
+
│ (orquestradores) │ Carregado sob demanda
|
|
53
|
+
└───────────┬───────────┘
|
|
54
|
+
│
|
|
55
|
+
Leitura encadeada: cada fase aponta para proxima
|
|
56
|
+
│
|
|
57
|
+
▼
|
|
58
|
+
┌───────────────────────┐
|
|
59
|
+
│ commands/X/0N-*.md │ ~100-150 linhas
|
|
60
|
+
│ (fases) │ Carregado 1 por vez
|
|
61
|
+
└───────────┬───────────┘
|
|
62
|
+
│
|
|
63
|
+
Invocacao via Task tool
|
|
64
|
+
│
|
|
65
|
+
▼
|
|
66
|
+
┌───────────────────────┐
|
|
67
|
+
│ agents/*.md │ ~200-300 linhas
|
|
68
|
+
│ (especialistas) │ Carregado isolado
|
|
69
|
+
└───────────────────────┘
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**Por que isso importa:**
|
|
73
|
+
- Claude nao carrega TODO o sistema de uma vez
|
|
74
|
+
- Cada camada e lida apenas quando necessaria
|
|
75
|
+
- Reduz tokens consumidos por request
|
|
76
|
+
- Permite instructions maiores sem overhead
|
|
77
|
+
|
|
78
|
+
---
|
|
79
|
+
|
|
80
|
+
## Hierarquia de Arquivos
|
|
81
|
+
|
|
82
|
+
### Global (~/.claude/)
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
~/.claude/
|
|
86
|
+
├── CLAUDE.md # Regras globais (todas as sessoes)
|
|
87
|
+
├── ARCHITECTURE.md # Este arquivo
|
|
88
|
+
│
|
|
89
|
+
├── commands/ # Skills disponiveis via /skill
|
|
90
|
+
│ ├── feature.md # /feature - orquestrador
|
|
91
|
+
│ ├── feature/
|
|
92
|
+
│ │ ├── 01-interview.md # Fase 1: entender requisitos
|
|
93
|
+
│ │ ├── 02-spec.md # Fase 2: especificacao tecnica
|
|
94
|
+
│ │ ├── 03-planner.md # Fase 3: plano de implementacao
|
|
95
|
+
│ │ ├── 04-implement.md # Fase 4: codigo
|
|
96
|
+
│ │ └── 05-quality.md # Fase 5: validacao
|
|
97
|
+
│ │
|
|
98
|
+
│ ├── debug.md # /debug - orquestrador
|
|
99
|
+
│ ├── debug/
|
|
100
|
+
│ │ ├── 01-investigate.md # Fase 1: 5 Whys
|
|
101
|
+
│ │ ├── 02-fix.md # Fase 2: correcao minima
|
|
102
|
+
│ │ └── 03-verify.md # Fase 3: confirmar fix
|
|
103
|
+
│ │
|
|
104
|
+
│ └── gate.md # /gate - quality gate completo
|
|
105
|
+
│
|
|
106
|
+
├── agents/ # Subagentes especializados (7 agents)
|
|
107
|
+
│ ├── code-reviewer.md # Review + auto-fix
|
|
108
|
+
│ ├── test-fixer.md # Testes + auto-fix
|
|
109
|
+
│ ├── visual-validator.md # Playwright + auto-fix
|
|
110
|
+
│ ├── code-simplifier.md # Reducao de complexidade
|
|
111
|
+
│ ├── dry-enforcer.md # Detecta duplicacao
|
|
112
|
+
│ ├── memory-sync.md # Sincroniza MCP Memory
|
|
113
|
+
│ └── terraform-validator.md # Valida env vars
|
|
114
|
+
│
|
|
115
|
+
└── *-defaults.json # Configs default para agents
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Local (projeto/.claude/)
|
|
119
|
+
|
|
120
|
+
```
|
|
121
|
+
projeto/.claude/
|
|
122
|
+
├── commands/ # Skills especificas do projeto
|
|
123
|
+
│ └── *.md # Ex: deploy.md, test-e2e.md, etc.
|
|
124
|
+
│
|
|
125
|
+
├── specs/ # Specs geradas pelo /feature
|
|
126
|
+
│ ├── {slug}.md # Spec com nome descritivo
|
|
127
|
+
│ └── current.md # Ponteiro para spec ativa
|
|
128
|
+
│
|
|
129
|
+
├── plans/ # Planos gerados pelo /feature
|
|
130
|
+
│ ├── {slug}.md # Plano com mesmo slug da spec
|
|
131
|
+
│ └── current.md # Ponteiro para plano ativo
|
|
132
|
+
│
|
|
133
|
+
├── settings.json # Config do Claude Code
|
|
134
|
+
├── visual-validation.json # Routes para visual-validator (opcional)
|
|
135
|
+
└── terraform-validation.json # Paths para terraform-validator (opcional)
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
**Personalizacoes por projeto:**
|
|
139
|
+
|
|
140
|
+
| Arquivo | Proposito | Quando Criar |
|
|
141
|
+
|---------|-----------|--------------|
|
|
142
|
+
| `commands/*.md` | Skills especificas (deploy, E2E, migrations) | Quando projeto tem workflows unicos |
|
|
143
|
+
| `visual-validation.json` | Mapeia components → routes para teste | Projetos com UI complexa |
|
|
144
|
+
| `terraform-validation.json` | Paths de env vars e terraform | Projetos com infra como codigo |
|
|
145
|
+
| `settings.json` | Modelo default, permissoes, etc. | Config avancada |
|
|
146
|
+
|
|
147
|
+
**CLAUDE.md do projeto deve conter:**
|
|
148
|
+
- Nome e descricao do projeto
|
|
149
|
+
- Comandos npm (dev, build, test)
|
|
150
|
+
- Estrutura de pastas
|
|
151
|
+
- Prefixo do namespace MCP Memory (ex: `sm:`, `api:`, `web:`)
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## Fluxo de Chamadas
|
|
156
|
+
|
|
157
|
+
### /feature (Desenvolvimento de Feature)
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
User: "adiciona filtro de data"
|
|
161
|
+
│
|
|
162
|
+
▼
|
|
163
|
+
┌──────────────────────────────────────────────────────────────────────────┐
|
|
164
|
+
│ CLAUDE.md global detecta trigger "adicionar/implementar" │
|
|
165
|
+
│ → Redireciona para /feature │
|
|
166
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
167
|
+
│
|
|
168
|
+
▼
|
|
169
|
+
┌──────────────────────────────────────────────────────────────────────────┐
|
|
170
|
+
│ commands/feature.md (orquestrador) │
|
|
171
|
+
│ → Le: commands/feature/01-interview.md │
|
|
172
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
173
|
+
│
|
|
174
|
+
▼
|
|
175
|
+
┌────────────────────────┐ ┌────────────────────────┐
|
|
176
|
+
│ 01-interview.md │────►│ 02-spec.md │
|
|
177
|
+
│ - Explora codebase │ │ - Gera spec tecnica │
|
|
178
|
+
│ - MCP Memory │ │ - Mapeia reutilizacao│
|
|
179
|
+
│ - AskUserQuestion │ │ - Documenta decisoes │
|
|
180
|
+
└────────────────────────┘ └───────────┬────────────┘
|
|
181
|
+
│
|
|
182
|
+
▼
|
|
183
|
+
┌────────────────────────┐ ┌────────────────────────┐
|
|
184
|
+
│ 04-implement.md │◄────│ 03-planner.md │
|
|
185
|
+
│ - Codigo seguindo │ │ - EnterPlanMode │
|
|
186
|
+
│ spec e plano │ │ - Passos detalhados │
|
|
187
|
+
│ - TodoWrite │ │ - APROVACAO USER │
|
|
188
|
+
└───────────┬────────────┘ └────────────────────────┘
|
|
189
|
+
│
|
|
190
|
+
▼
|
|
191
|
+
┌────────────────────────────────────────────────────────────────────────┐
|
|
192
|
+
│ 05-quality.md │
|
|
193
|
+
│ → Invoca agents via Task tool (ordem atualizada): │
|
|
194
|
+
│ test-fixer (baseline) → code-simplifier → dry-enforcer → │
|
|
195
|
+
│ test-fixer (verificacao) → code-reviewer → │
|
|
196
|
+
│ visual-validator (se UI) → terraform-validator (se env) │
|
|
197
|
+
└───────────┬────────────────────────────────────────────────────────────┘
|
|
198
|
+
│
|
|
199
|
+
▼
|
|
200
|
+
┌────────────────────────────────────────────────────────────────────────┐
|
|
201
|
+
│ memory-sync agent │
|
|
202
|
+
│ - Atualiza MCP Memory com conhecimento adquirido │
|
|
203
|
+
└────────────────────────────────────────────────────────────────────────┘
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### /debug (Resolucao de Bug)
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
User: "erro ao publicar video"
|
|
210
|
+
│
|
|
211
|
+
▼
|
|
212
|
+
┌──────────────────────────────────────────────────────────────────────────┐
|
|
213
|
+
│ CLAUDE.md global detecta trigger "bug/erro/problema" │
|
|
214
|
+
│ → Redireciona para /debug │
|
|
215
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
216
|
+
│
|
|
217
|
+
▼
|
|
218
|
+
┌────────────────────────┐ ┌────────────────────────┐
|
|
219
|
+
│ 01-investigate.md │────►│ 02-fix.md │
|
|
220
|
+
│ - Reproduzir bug │ │ - Gate de criticidade│
|
|
221
|
+
│ - 5 Whys com │ │ - EnterPlanMode se │
|
|
222
|
+
│ EVIDENCIA │ │ path critico │
|
|
223
|
+
└────────────────────────┘ │ - Fix MINIMO │
|
|
224
|
+
│ - Testes obrigatorio │
|
|
225
|
+
└───────────┬────────────┘
|
|
226
|
+
│
|
|
227
|
+
▼
|
|
228
|
+
┌────────────────────────┐
|
|
229
|
+
│ 03-verify.md │
|
|
230
|
+
│ - Reproduzir fix │
|
|
231
|
+
│ - Quality gates │
|
|
232
|
+
│ - Salvar bug raro │
|
|
233
|
+
│ em MCP Memory │
|
|
234
|
+
└────────────────────────┘
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### /gate (Quality Gate Antes de PR)
|
|
238
|
+
|
|
239
|
+
```
|
|
240
|
+
User: "/gate" ou invocado por /feature
|
|
241
|
+
│
|
|
242
|
+
▼
|
|
243
|
+
┌──────────────────────────────────────────────────────────────────────────┐
|
|
244
|
+
│ commands/gate.md │
|
|
245
|
+
│ Orquestra 7 agents em sequencia, corrigindo automaticamente: │
|
|
246
|
+
└──────────────────────────────────────────────────────────────────────────┘
|
|
247
|
+
│
|
|
248
|
+
▼
|
|
249
|
+
┌─────────────────────────────────────────────────────────────────────────┐
|
|
250
|
+
│ │
|
|
251
|
+
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
252
|
+
│ │ test-fixer │──►│ code- │──►│ dry- │──►│ code- │ │
|
|
253
|
+
│ │ │ │ simplifier │ │ enforcer │ │ reviewer │ │
|
|
254
|
+
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
255
|
+
│ │ │
|
|
256
|
+
│ ▼ │
|
|
257
|
+
│ ┌─────────────────────────────────────────────────────────────────────┐│
|
|
258
|
+
│ │ SE mudancas relevantes: ││
|
|
259
|
+
│ │ ┌──────────────────┐ ┌──────────────────────┐ ││
|
|
260
|
+
│ │ │ visual-validator │ │ terraform-validator │ ││
|
|
261
|
+
│ │ │ (se UI .tsx) │ │ (se .env/.tf) │ ││
|
|
262
|
+
│ │ └──────────────────┘ └──────────────────────┘ ││
|
|
263
|
+
│ └─────────────────────────────────────────────────────────────────────┘│
|
|
264
|
+
│ │
|
|
265
|
+
└─────────────────────────────────────────────────────────────────────────┘
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## Distribuicao de Responsabilidades
|
|
271
|
+
|
|
272
|
+
### CLAUDE.md (Global vs Local)
|
|
273
|
+
|
|
274
|
+
| Aspecto | Global (~/.claude/) | Local (projeto/.claude/) |
|
|
275
|
+
|---------|---------------------|--------------------------|
|
|
276
|
+
| **Escopo** | Todas as sessoes | Apenas este projeto |
|
|
277
|
+
| **Conteudo** | Regras de codigo, autonomia | Comandos npm, estrutura, linguagem |
|
|
278
|
+
| **Skills** | /feature, /debug, /gate | Skills customizadas do projeto |
|
|
279
|
+
| **Memory NS** | Define padrao de uso | Define prefixo unico (ex: `api:`) |
|
|
280
|
+
| **Tamanho** | ~25 linhas | ~30 linhas |
|
|
281
|
+
|
|
282
|
+
### Agents vs Skills
|
|
283
|
+
|
|
284
|
+
| Agents (subagentes) | Skills (commands) |
|
|
285
|
+
|---------------------|-------------------|
|
|
286
|
+
| Executam em contexto isolado | Executam no contexto principal |
|
|
287
|
+
| Invocados via `Task` tool | Invocados via `/skill` ou `Skill` tool |
|
|
288
|
+
| Especializados em UMA tarefa | Orquestram multiplas tarefas |
|
|
289
|
+
| Totalmente autonomos | Podem pedir aprovacao |
|
|
290
|
+
| ~200-300 linhas cada | ~20-150 linhas cada |
|
|
291
|
+
|
|
292
|
+
### Modelos por Componente
|
|
293
|
+
|
|
294
|
+
```
|
|
295
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
296
|
+
│ ALOCACAO DE MODELOS │
|
|
297
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
298
|
+
│ │
|
|
299
|
+
│ OPUS (alta qualidade, mais lento) │
|
|
300
|
+
│ ├── commands/feature.md → Decisoes complexas │
|
|
301
|
+
│ ├── commands/debug.md → Root cause analysis │
|
|
302
|
+
│ └── agents/code-reviewer.md → Julgamento de qualidade │
|
|
303
|
+
│ │
|
|
304
|
+
│ SONNET (balanceado) │
|
|
305
|
+
│ ├── agents/test-fixer.md → Criacao de testes │
|
|
306
|
+
│ └── agents/visual-validator.md → Navegacao browser │
|
|
307
|
+
│ │
|
|
308
|
+
│ HAIKU (rapido, economico) │
|
|
309
|
+
│ └── agents/memory-sync.md → Operacoes simples de CRUD │
|
|
310
|
+
│ │
|
|
311
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
---
|
|
315
|
+
|
|
316
|
+
## Autonomia por Design
|
|
317
|
+
|
|
318
|
+
### Principios
|
|
319
|
+
|
|
320
|
+
```
|
|
321
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
322
|
+
│ PILARES DA AUTONOMIA │
|
|
323
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
324
|
+
│ │
|
|
325
|
+
│ 1. FAZER, nao perguntar │
|
|
326
|
+
│ └── Agentes corrigem problemas automaticamente │
|
|
327
|
+
│ └── Nao pedem confirmacao para fixes │
|
|
328
|
+
│ │
|
|
329
|
+
│ 2. BUSCAR, nao pedir contexto │
|
|
330
|
+
│ └── MCP Memory para conhecimento persistente │
|
|
331
|
+
│ └── Grep/Glob para explorar codebase │
|
|
332
|
+
│ └── AskUserQuestion APENAS para decisoes de produto │
|
|
333
|
+
│ │
|
|
334
|
+
│ 3. Regras BLOQUEANTES │
|
|
335
|
+
│ └── Codigo sem teste = PR rejeitado │
|
|
336
|
+
│ └── Quality gates devem passar │
|
|
337
|
+
│ │
|
|
338
|
+
│ 4. Erros: corrigir e continuar │
|
|
339
|
+
│ └── Nao abandonar workflow por falha │
|
|
340
|
+
│ └── Fix automatico ate 3 tentativas │
|
|
341
|
+
│ │
|
|
342
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
### Triggers Automaticos
|
|
346
|
+
|
|
347
|
+
| Condicao | Acao Automatica |
|
|
348
|
+
|----------|-----------------|
|
|
349
|
+
| User pede "adicionar/implementar feature" | Redireciona para `/feature` |
|
|
350
|
+
| User menciona "bug/erro/problema" | Redireciona para `/debug` |
|
|
351
|
+
| Mudanca em `components/*.tsx` | `visual-validator` invocado |
|
|
352
|
+
| Mudanca em `.env` ou `terraform/` | `terraform-validator` invocado |
|
|
353
|
+
| Codigo novo sem teste | `test-fixer` cria teste |
|
|
354
|
+
| Fim de workflow | `memory-sync` atualiza Memory |
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## MCP Memory Integration
|
|
359
|
+
|
|
360
|
+
```
|
|
361
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
362
|
+
│ MCP MEMORY FLOW │
|
|
363
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
364
|
+
│ │
|
|
365
|
+
│ INICIO DE SESSAO │
|
|
366
|
+
│ └── search_nodes({ query: "config" }) │
|
|
367
|
+
│ └── Carrega: escopo, comandos, quality gates │
|
|
368
|
+
│ │
|
|
369
|
+
│ DURANTE DESENVOLVIMENTO │
|
|
370
|
+
│ └── search_nodes({ query: "<termos>" }) │
|
|
371
|
+
│ └── Busca: patterns, bugs conhecidos, fluxos │
|
|
372
|
+
│ │
|
|
373
|
+
│ FIM DE WORKFLOW │
|
|
374
|
+
│ └── memory-sync agent │
|
|
375
|
+
│ ├── Atualiza entidades obsoletas │
|
|
376
|
+
│ ├── Cria entidades para conhecimento novo │
|
|
377
|
+
│ └── Remove entidades de arquivos deletados │
|
|
378
|
+
│ │
|
|
379
|
+
│ NAMESPACE POR PROJETO │
|
|
380
|
+
│ └── Prefixo definido no CLAUDE.md local │
|
|
381
|
+
│ └── Ex: sm:pattern:X, sm:bug:Y, sm:fluxo:Z │
|
|
382
|
+
│ │
|
|
383
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
---
|
|
387
|
+
|
|
388
|
+
## Persistencia e Checkpoints
|
|
389
|
+
|
|
390
|
+
```
|
|
391
|
+
┌─────────────────────────────────────────────────────────────────────┐
|
|
392
|
+
│ PERSISTENCIA DE ESTADO │
|
|
393
|
+
├─────────────────────────────────────────────────────────────────────┤
|
|
394
|
+
│ │
|
|
395
|
+
│ SPECS E PLANOS │
|
|
396
|
+
│ └── .claude/specs/{slug}.md → Spec gerada │
|
|
397
|
+
│ └── .claude/specs/current.md → Ponteiro para spec ativa │
|
|
398
|
+
│ └── .claude/plans/{slug}.md → Plano gerado │
|
|
399
|
+
│ └── .claude/plans/current.md → Ponteiro para plano ativo │
|
|
400
|
+
│ │
|
|
401
|
+
│ BENEFICIO: Sessao pode ser retomada sem perder contexto │
|
|
402
|
+
│ │
|
|
403
|
+
│ CHECKPOINTS VIA TodoWrite │
|
|
404
|
+
│ └── Cada fase registra conclusao no TodoWrite │
|
|
405
|
+
│ └── Gate: proxima fase so inicia se anterior completed │
|
|
406
|
+
│ └── Visibilidade para user do progresso │
|
|
407
|
+
│ │
|
|
408
|
+
│ CONTEXT LOADING INTELIGENTE │
|
|
409
|
+
│ └── 01-interview: Carrega MCP Memory (config, patterns) │
|
|
410
|
+
│ └── 02-spec+: Contexto ja disponivel, apenas busca patterns │
|
|
411
|
+
│ └── Retomada: Read .claude/specs/current.md │
|
|
412
|
+
│ │
|
|
413
|
+
└─────────────────────────────────────────────────────────────────────┘
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## Output Estruturado dos Agents
|
|
419
|
+
|
|
420
|
+
Todos os 7 agents retornam bloco padronizado ao final:
|
|
421
|
+
|
|
422
|
+
```
|
|
423
|
+
---AGENT_RESULT---
|
|
424
|
+
STATUS: PASS | FAIL
|
|
425
|
+
ISSUES_FOUND: <numero>
|
|
426
|
+
ISSUES_FIXED: <numero>
|
|
427
|
+
BLOCKING: true | false
|
|
428
|
+
---END_RESULT---
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
**Regras de Agregacao (05-quality.md e gate.md):**
|
|
432
|
+
- SE STATUS=FAIL e BLOCKING=true → Workflow PARA
|
|
433
|
+
- SE STATUS=FAIL e BLOCKING=false → Continua com warning
|
|
434
|
+
- Resultado agregado em tabela para relatorio final
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
|
|
438
|
+
## Beneficios desta Arquitetura
|
|
439
|
+
|
|
440
|
+
| Beneficio | Como e Alcancado |
|
|
441
|
+
|-----------|------------------|
|
|
442
|
+
| **Contexto minimo** | Leitura encadeada, arquivos pequenos |
|
|
443
|
+
| **Autonomia maxima** | Agents auto-corrigem, regras bloqueantes |
|
|
444
|
+
| **Consistencia** | Regras globais herdadas por todos projetos |
|
|
445
|
+
| **Flexibilidade** | Skills locais para necessidades especificas |
|
|
446
|
+
| **Qualidade** | /gate orquestra 7 validacoes automaticas |
|
|
447
|
+
| **Conhecimento** | MCP Memory persiste aprendizados |
|
|
448
|
+
| **Escalabilidade** | Mesmo setup funciona para N projetos |
|
|
449
|
+
|
|
450
|
+
---
|
|
451
|
+
|
|
452
|
+
## Quick Reference
|
|
453
|
+
|
|
454
|
+
```bash
|
|
455
|
+
# Skills globais (qualquer projeto)
|
|
456
|
+
/feature # Desenvolver feature completa
|
|
457
|
+
/debug # Resolver bug com 5 Whys
|
|
458
|
+
/gate # Quality gate pre-PR
|
|
459
|
+
|
|
460
|
+
# Skills locais (definidas em projeto/.claude/commands/)
|
|
461
|
+
# Exemplos comuns:
|
|
462
|
+
# /deploy # Deploy para producao
|
|
463
|
+
# /test-e2e # Testes end-to-end
|
|
464
|
+
# /migrate # Database migrations
|
|
465
|
+
|
|
466
|
+
# Agents (invocados automaticamente ou via Task)
|
|
467
|
+
test-fixer, code-reviewer, visual-validator,
|
|
468
|
+
code-simplifier, dry-enforcer, memory-sync,
|
|
469
|
+
terraform-validator
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
*Ultima atualizacao: Janeiro 2026*
|
package/config/CLAUDE.md
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Claude Code - Regras Globais
|
|
2
|
+
|
|
3
|
+
## Autonomia
|
|
4
|
+
FAZER, não perguntar. BUSCAR, não pedir contexto.
|
|
5
|
+
|
|
6
|
+
## Workflows
|
|
7
|
+
| Trigger | Ação |
|
|
8
|
+
|---------|------|
|
|
9
|
+
| criar/adicionar/implementar feature | `/feature` |
|
|
10
|
+
| bug/erro/problema | `/debug` |
|
|
11
|
+
|
|
12
|
+
## Código
|
|
13
|
+
- Funções < 50 linhas, max 2 níveis nesting
|
|
14
|
+
- TypeScript strict, ES modules, async/await
|
|
15
|
+
- Zod para inputs externos
|
|
16
|
+
- PROIBIDO: `any`, try/catch genérico, callbacks
|
|
17
|
+
|
|
18
|
+
## Testes (BLOQUEANTE)
|
|
19
|
+
Código sem teste = PR rejeitado.
|
|
20
|
+
Exceções: config files, .d.ts, UI puro sem lógica.
|
|
21
|
+
|
|
22
|
+
## Memory
|
|
23
|
+
Namespace: ver CLAUDE.md do projeto.
|
|
24
|
+
Sincronizar via `memory-sync` ao final de workflows.
|