Claude Code — Setup e Uso
MCP, agentes, skills, rules e os hooks que barram besteira
O Claude Code é o assistente que conecta o board ao código. A configuração dele vive em dois lugares.
MCP servers
Os servers do repositório ficam em .mcp.json na raiz (versionado):
| Server | Para quê |
|---|---|
supabase | banco, migrations, advisors |
codegraph | índice de código — responde "onde está X" e "quem chama Y" sem grep |
chrome-devtools | dirigir o navegador para provar tela |
linear | resíduo legado |
O server do vStack (cockpit) não fica no repositório — é configurado em ~/.claude.json, no nível do usuário. Se o board não responder, é lá que se olha.
.claude/settings.json guarda permissões e hooks, não MCP.
O que vive em .claude/
| Pasta | O que é |
|---|---|
agents/ | os subagentes (implementação, QA, arquitetura, DevOps, dados, UX…) |
skills/ | os fluxos da casa: /promocao, /adversarial, /teste-final, /feature, /encerrar e outros |
hooks/ | os gates mecânicos (abaixo) |
rules/ | ciclo de vida do trabalho, execução de workflow, autoridade de agente, handoff |
checklists/ | definição de pronto |
Os hooks — travas por operação, não por pessoa
Valem para todo mundo: sessão comum, subagente, agente noturno.
| Operação | Regra |
|---|---|
git push de branch, gh pr create | liberado |
commit, merge ou push com destino main | bloqueado para todos |
git push --force | bloqueado; prefira --force-with-lease, que passa |
gh pr merge | bloqueado — exige autorização explícita |
| criar ou alterar migration | bloqueado sem aprovação |
| instalar dependência nova | bloqueado sem aprovação |
Há ainda um hook que lembra de mover o cartão do board no git push -u e no gh pr create.
As regras que o assistente segue
Estão no CLAUDE.md da raiz — Prime Directives, comandos, convenções de apps/app, padrões de engenharia e a lista de decisões já tomadas (para não perguntar duas vezes a mesma coisa). É leitura obrigatória antes de qualquer tarefa, e vence em caso de empate com qualquer outra camada de instrução.