Fluxo de Trabalho com o Claude

fluxo-claude.md

Tutorial: Fluxo de Trabalho do Claude Code

Claude Code é um agente de linha de comando que roda no terminal com acesso completo ao sistema — lê arquivos, executa comandos, modifica código, gerencia git e delega tarefas a subagentes especializados.

---

Índice

1. Arquivos de Configuração
2. Modos de Permissão
3. O Fluxo Principal: Explore → Plan → Execute → Commit
4. Subagentes Especializados
5. Slash Commands Customizados
6. Hooks — Automação por Eventos
7. Modo Headless para Automação
8. Resumo Prático

---

1. Arquivos de Configuração

Os arquivos de configuração são carregados hierarquicamente: do global (vale para todos os projetos) ao projeto específico (sobrescreve o global onde houver conflito).

~/.claude/CLAUDE.md          ← Global: suas preferências pessoais
~/.claude/settings.json      ← Global: permissões e modelo padrão
~/.claude/commands/          ← Global: slash commands disponíveis em todo lugar

./CLAUDE.md                  ← Projeto: arquitetura, convenções, comandos
./.claude/settings.json      ← Projeto: sobrescreve o global
./.claude/commands/          ← Projeto: slash commands específicos
./.claude/rules/             ← Projeto: regras com path-scoping

Global — ~/.claude/CLAUDE.md Aplica-se a todos os projetos · regras globais, preferências pessoais Projeto — ./CLAUDE.md Arquitetura, convenções, comandos do projeto · ~120 linhas ideais .claude/rules/ Regras com path-scoping, carregadas quando relevantes .claude/commands/ Slash commands customizados /nome-do-comando settings.json — Permissões e modelo allowedTools, deny, model, maxTokens, hooks pós-ferramenta ~/.claude/settings.json (global) ou .claude/settings.json (projeto)

Exemplo de CLAUDE.md para um projeto

## Arquitetura
- Monorepo: frontend em /packages/ui, API em /packages/api
- PostgreSQL via Prisma

## Convenções
- TypeScript strict em todo o projeto
- Sem default exports
- Testes obrigatórios para todo código novo

## Comandos
- `npm test`         — rodar testes
- `npm run dev`      — iniciar servidores
- `npm run db:migrate` — migrações

Exemplo de settings.json

{
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    "allowedTools": ["Read", "Write", "Bash(git *)"],
    "deny": ["Read(./.env)", "Write(./production.config.*)"]
  }
}

---

2. Modos de Permissão

O Shift+Tab alterna entre três modos de operação. Você também pode iniciar já em Plan Mode com --permission-mode plan.

Normal Pede confirmação antes de agir padrão recomendado

Shift+Tab

Auto-Accept ⏵⏵ Executa sem pedir confirmação ótimo para tarefas longas

Shift+Tab

Plan ⏸ Read only planejar antes

Modo	Atalho	Comportamento	Quando usar
Normal	padrão	Pede confirmação a cada ação	Tarefas delicadas, código crítico
Auto-Accept	Shift+Tab	Executa todas as ações sem pausa	Tarefas longas e repetitivas
Plan Mode	Shift+Tab × 2	Apenas lê, sem modificar nada	Antes de começar qualquer tarefa complexa

---

3. O Fluxo Principal: Explore → Plan → Execute → Commit

O insight central do Claude Code: as fases 1 e 2 (Explore + Plan) são as mais baratas em tokens e as mais valiosas em resultado. Nunca pule direto para a execução.

1. Explore Lê o código, mapeia a estrutura Read-only · Haiku 2. Plan Gera plano detalhado, sem escrever código Read-only · Sonnet/Opus 3. Execute Implementa conforme o plano aprovado Leitura + escrita · Sonnet 4. Commit Consolida no git git + PR

Plan Mode em detalhe

Claude lê o código Glob, Grep, Read, Bash Gera o plano Você edita com Ctrl+G Você aprova Claude passa a executar 💡 Ctrl+G abre o plano no editor de texto para você editar diretamente antes de aprovar

Como iniciar o fluxo na prática

# Iniciar direto em Plan Mode (recomendado para tarefas novas)
claude --permission-mode plan

# Dentro do Claude Code, alternar modos
Shift+Tab     # Normal → Auto-Accept
Shift+Tab     # Auto-Accept → Plan Mode
Shift+Tab     # Plan Mode → Normal

# Ctrl+G: abrir o plano no editor antes de aprovar

---

4. Subagentes Especializados

Claude Code delega automaticamente a subagentes baseados no tipo de tarefa. Você também pode solicitá-los explicitamente.

Orchestrator Decide qual agente usar Explore Agent Read-only · ultra-rápido Haiku · mapeia código Plan Agent Read-only · planejamento Sonnet/Opus General Agent Leitura + escrita Sonnet · uso geral

Solicitando subagentes explicitamente

> Use the explore agent to find all authentication-related files
> Have a subagent analyze the database schema thoroughly
> Run the plan agent before making any changes

---

5. Slash Commands Customizados

Você cria comandos personalizados em .claude/commands/ (projeto) ou ~/.claude/commands/ (global). Cada arquivo .md vira um comando /nome-do-arquivo.

# Criar estrutura de commands
mkdir -p .claude/commands

# Comando simples
echo "Analyze this code for performance issues and suggest optimizations:" \
  > .claude/commands/optimize.md

# Usar no Claude Code
> /optimize

# Comando com parâmetros ($ARGUMENTS recebe o que você digitar depois)
echo 'Fix issue #$ARGUMENTS following our coding standards' \
  > .claude/commands/fix-issue.md

> /fix-issue 123

Exemplo de command mais elaborado

<!-- .claude/commands/review.md -->
Review the following code changes:

1. Check for security vulnerabilities
2. Verify test coverage
3. Ensure TypeScript types are correct
4. Suggest performance improvements
5. Verify it follows our coding conventions in CLAUDE.md

Focus on: $ARGUMENTS

---

6. Hooks — Automação por Eventos

Hooks disparam comandos shell automaticamente em eventos do Claude Code.

{
  "model": "claude-sonnet-4-20250514",
  "permissions": {
    "allowedTools": ["Read", "Write", "Bash(git *)"],
    "deny": ["Read(./.env)", "Write(./production.config.*)"]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write(*.py)",
        "hooks": [
          { "type": "command", "command": "python -m black $file" }
        ]
      },
      {
        "matcher": "Write(*.ts)",
        "hooks": [
          { "type": "command", "command": "npx prettier --write $file" }
        ]
      }
    ]
  }
}

Evento	Quando dispara
PostToolUse	Após Claude usar uma ferramenta (escrever arquivo, rodar comando)
PreToolUse	Antes de Claude usar uma ferramenta
SessionStart	No início de uma sessão

---

7. Modo Headless (-p) para Automação

O flag -p ativa o modo headless (sem interação), perfeito para scripts, pipes e CI/CD.

# Query simples em modo headless
claude -p "Analyze this file for security issues" < myfile.py

# Encadear com outros comandos Unix
git diff HEAD | claude -p "Summarize these changes for a commit message"

# Usar em scripts de CI
claude -p "Run tests and report any failures" --output-format json

# Especificar modelo
claude -p "Review this PR" --model claude-opus-4-20250514

Exemplo: script de revisão automática no git

#!/bin/bash
# pre-commit hook: revisão automática de segurança

STAGED=$(git diff --cached --name-only)

if [ -n "$STAGED" ]; then
  echo "$STAGED" | claude -p \
    "Review these staged files for security issues. If critical issues found, exit 1." \
    --permission-mode plan
fi

---

Resumo Prático

O que fazer	Como fazer
Novo projeto	Criar CLAUDE.md com arquitetura e convenções
Tarefa complexa	Shift+Tab duas vezes → Plan Mode, editar plano com Ctrl+G
Limpar contexto entre tarefas	/clear
Automatizar formatação	Hooks em settings.json
Reutilizar prompts	Slash commands em .claude/commands/
Integrar CI/CD	Flag -p (headless mode)
Adicionar serviços externos	MCP servers (GitHub, Slack, Postgres, etc.)
Tarefas longas sem interrupção	Shift+Tab → Auto-Accept ⏵⏵

Workflow ideal resumido

1. Criar/atualizar CLAUDE.md com contexto do projeto
2. Iniciar: claude --permission-mode plan
3. Descrever a tarefa detalhadamente
4. Revisar o plano (Ctrl+G para editar)
5. Aprovar → Claude executa
6. Revisar o resultado e commitar

---

Documentação oficial: https://docs.claude.com/en/docs/claude-code/overview