Projeto 2: Agentic com Claude Code

Por que usar

• + Executa tarefas complexas de múltiplos arquivos sem supervisão constante
• + Integra nativamente com git, GitHub CLI, pytest e qualquer ferramenta de terminal
• + Contexto persistente via CLAUDE.md — o agente "conhece" as regras do projeto
• + Permissões configuráveis por projeto, com listas allow/deny granulares

Como configurar

Instale globalmente via npm e autentique com sua chave da Anthropic:

# 1. Instalar o Claude Code globalmente
npm install -g @anthropic-ai/claude-code

# 2. Verificar a instalação
claude --version

# 3. Autenticar (abre o browser para OAuth)
claude auth login

# 4. Ou usar chave de API diretamente
export ANTHROPIC_API_KEY="sk-ant-..."

# 5. Entrar no diretório do projeto e iniciar
cd meu-projeto
claude

# 6. Modo não-interativo (headless)
claude -p "Adicione testes para o módulo de autenticação"

Estrutura básica recomendada para qualquer projeto:

meu-projeto/
├── CLAUDE.md                  # Memória e regras do agente
├── .claude/
│   ├── settings.json          # Permissões e hooks
│   └── skills/
│       ├── fix-issue/
│       │   └── SKILL.md       # Skill customizada
│       └── deploy/
│           └── SKILL.md
└── src/                       # Código do projeto

Por que usar

• + Elimina a necessidade de explicar o projeto do zero a cada sessão
• + Garante que o Claude siga as convenções da equipe (snake_case, docstrings, etc.)
• + Previne ações indesejadas com regras explícitas ("nunca commitar em main")
• + Pode ser compartilhado entre a equipe via controle de versão

Como configurar

Seções recomendadas para um CLAUDE.md completo:

# CLAUDE.md

## Contexto do Projeto
API REST com FastAPI + PostgreSQL para gestão de tarefas.
Stack: Python 3.11, SQLAlchemy 2.0, Pydantic v2, pytest.

## Comandos Principais
- Rodar: `uvicorn app.main:app --reload`
- Testes: `pytest --cov=app`
- Lint: `ruff check app/`

## Convenções
- snake_case para funções e variáveis
- Type hints obrigatórios em todas as funções
- Docstrings no formato Google Style

## Regras do Claude
- NUNCA commitar em main ou develop
- Sempre criar branch: feat/, fix/, refactor/
- Rodar pytest antes de qualquer commit
- Nunca expor SECRET_KEY ou DATABASE_URL

## Arquitetura
app/routers/   → endpoints por recurso
app/models/    → SQLAlchemy models
app/schemas/   → Pydantic schemas
app/services/  → lógica de negócio

Por que usar

• + Previne ações destrutivas acidentais (rm -rf, git push --force)
• + Libera fluxo para ações seguras e repetitivas sem confirmação manual
• + Configurável por projeto — um projeto de produção pode ter regras mais rígidas
• + Três modos: default (pergunta tudo), auto-edit (edições sem confirmar), bypass-permissions (CI/CD)

Como configurar

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(git add:*)",        // git add permitido
      "Bash(git commit:*)",
      "Bash(pytest:*)",          // rodar testes sem confirmar
      "Bash(pip install:*)",
      "Bash(python:*)"
    ],
    "deny": [
      "Bash(git push --force:*)", // bloqueado permanentemente
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

Modos de execução via flag:

# Modo padrão (pergunta antes de ações não configuradas)
claude

# Modo auto-edit (edita arquivos sem confirmação)
claude --auto-edit

# Modo headless para CI/CD (bypass total, use com cuidado)
claude --dangerously-skip-permissions -p "rodar suíte de testes"

Por que usar

• + Rodar lint automaticamente após cada edição de arquivo Python
• + Enviar notificações no Slack quando o agente concluir uma tarefa longa
• + Registrar logs de auditoria de todos os comandos executados
• + Bloquear comandos perigosos com verificação customizada antes de executar

Como configurar

// .claude/settings.json — seção hooks
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",        // aplica a todos os Bash
        "hooks": [{
          "type": "command",
          "command": "echo '[Audit] Bash: $CLAUDE_TOOL_INPUT'"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",         // após editar arquivo
        "hooks": [{
          "type": "command",
          "command": "ruff check app/ --quiet"
        }]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [{
          "type": "command",
          "command": "notify-send 'Claude Code' '$CLAUDE_NOTIFICATION'"
        }]
      }
    ]
  }
}

Por que usar

• + /fix-issue 123 — corrige automaticamente uma issue do GitHub
• + /commit — cria commit com mensagem gerada a partir do diff
• + /review-pr 45 — revisa um PR e sugere melhorias
• + /deploy staging — executa pipeline de deploy para staging

Como configurar

Estrutura de um SKILL.md para a skill /fix-issue:

# Skill: fix-issue

## Uso
/fix-issue <numero-da-issue>

## Passos
1. Ler issue: `gh issue view <numero> --json title,body`
2. Identificar arquivos relacionados com Grep/Glob
3. Criar branch: `git checkout -b fix/issue-<numero>`
4. Implementar correção com Edit/Write
5. Rodar testes: `pytest`
6. Commitar: `git commit -m "Fix: resolve #<numero>"`

## Regras
- Nunca modificar main diretamente
- Se testes falharem, corrigir antes de commitar
- Mencionar o número da issue na mensagem de commit

## Ferramentas
Bash, Read, Edit, Write, Grep, Glob

Localização no projeto:

.claude/skills/
├── fix-issue/
│   └── SKILL.md      → ativada com /fix-issue
├── commit/
│   └── SKILL.md      → ativada com /commit
└── review-pr/
    └── SKILL.md      → ativada com /review-pr

Por que usar

• + MCP conecta Claude a bancos de dados, APIs, Slack, Jira, sem código customizado
• + Subagentes permitem trabalho paralelo — 4 módulos sendo implementados ao mesmo tempo
• + Worktrees isolam cada subagente em seu próprio diretório — sem conflitos de arquivos
• + Modo headless (claude -p "...") permite automação total via scripts e CI/CD

Como configurar

Conectar um servidor MCP ao Claude Code:

# Adicionar servidor MCP ao Claude
claude mcp add postgres-server \
  --command "npx @anthropic/mcp-server-postgres" \
  --env DATABASE_URL="$DATABASE_URL"

# Listar MCPs configurados
claude mcp list

# Usar em sessão interativa (Claude agora tem acesso ao banco)
claude
# "Liste as 10 tarefas mais recentes do banco de dados"

Usar a ferramenta Task para criar subagentes paralelos:

# Prompt para o agente principal orquestrar subagentes
claude -p "
Implemente as seguintes features em paralelo usando subagentes:

1. Subagente A: Criar endpoint POST /api/v1/tasks com validação
2. Subagente B: Adicionar testes para o endpoint de autenticação
3. Subagente C: Atualizar documentação do README

Use a ferramenta Task para cada subagente.
Aguarde todos completarem antes de fazer o commit final.
"

Trabalhar com worktrees para isolamento:

# Criar worktree para trabalhar em feature isolada
git worktree add .claude/worktrees/feat-auth feat/auth-refresh

# Claude Code cria worktrees automaticamente com /worktree
/worktree feat-notifications

# Listar worktrees ativos
git worktree list