Pular para o conteúdo principal

Fase 2 — Fluência: usando Claude Code no dia a dia

Duração: 4 semanas · Dedicação: 8–10h/semana · Trilhas: 🟢🔵🟣 (todos os módulos são essenciais) Pré-requisito: Fase 1 concluída (Claude Code instalado, CLAUDE.md configurado, prompts estruturados, primeiro projeto entregue). Foco principal: Claude Code · Conceitos transferíveis: marcados com 🌐.

Objetivo da fase​

Sair de "uso Claude Code de vez em quando" para "Claude Code é par fixo no meu dia a dia". Ao final desta fase, automação, geração de testes, debugging, code review, documentação e navegação em codebases grandes deixam de ser tarefas que você faz manualmente.

Ao final desta fase você consegue:

  • Refatorar e gerar código multi-arquivo com Claude Code
  • Trabalhar em modo spec-driven (escrever a spec, deixar Claude implementar)
  • Praticar TDD com Claude Code de forma confiável
  • Automatizar commits, PRs e code review com Claude Code + GitHub Actions
  • Debugar bugs reais usando workflows estruturados
  • Manter documentação sincronizada com código
  • Navegar e contribuir em codebases grandes sem se afogar em contexto

Convenções​

  • Tipo: 📚 Doc oficial · 📖 Artigo/Paper · 🎓 Curso · 🎬 Vídeo/Podcast · 🛠️ Hands-on/Repositório
  • Idioma: [PT] português · [EN] inglês
  • Custo: [Grátis] · [Pago] · [Freemium]
  • Nível: iniciante · intermediário · avançado
  • ⭐ essencial · 🌐 conceito universal (transferível para qualquer agente)

M5 · Automação de tarefas de desenvolvimento com Claude Code

Por que este módulo​

Você já sabe usar Claude Code para tarefas pontuais. Aqui você consolida os padrões de automação que aparecem todo dia: refatoração multi-arquivo, geração de boilerplate, transformações repetitivas, migrações pequenas. O ganho é deixar de "pensar como pedir" e começar a ter prompts e fluxos reflexos.

Tópicos​

  • Refatoração com Claude Code: mover código entre arquivos, extrair funções, renomear consistentemente, aplicar padrões
  • Edição multi-arquivo em uma sessão (Claude Code é nativamente multi-file)
  • Geração de boilerplate: rotas de API, componentes, schemas, migrations
  • Transformações repetitivas: aplicar a mesma mudança em N lugares
  • Padrões de prompt para tarefas recorrentes (templates pessoais)
  • Quando usar modo plan (Shift+Tab) vs. modo direto
  • Quando ativar thinking modes (think, think hard, ultrathink)
  • Quando NÃO usar Claude Code (tarefas triviais, tarefas onde você já está fluente)

Materiais​

Documentação oficial ⭐​

Cursos e guias​

Em português​

Exercício prático​

Em um projeto seu real, faça 5 tarefas com Claude Code:

  1. Refatorar uma função grande em 3 funções menores
  2. Renomear consistentemente uma variável/conceito em 5+ arquivos
  3. Adicionar tipagem (TypeScript / Python type hints) a um módulo sem tipos
  4. Gerar boilerplate para uma nova rota de API + teste correspondente
  5. Aplicar a mesma transformação (ex: trocar console.log por logger estruturado) em N arquivos

Documente em meu-playbook-claude.md o prompt template que funcionou para cada tipo de tarefa. Este arquivo vai virar referência sua para sempre.

Definition of Done​

  • Você tem 3+ prompt templates pessoais para tarefas recorrentes
  • Sabe quando usar modo plan e quando ir direto
  • Sabe ativar thinking mode quando o problema exige
  • Identifica em segundos quando NÃO usar Claude Code

M6 · Spec-driven development com Claude

Por que este módulo​

🌐 Spec-driven development virou padrão emergente em 2025/26 — escrever a especificação primeiro e deixar o agente implementar. Em vez de prompts soltos, você escreve um documento que explica intenção, restrições e critérios de aceitação. Resultado: menos iteração, menos retrabalho, qualidade muito mais alta.

A Anthropic documenta o padrão como Explore → Plan → Code → Commit. O GitHub criou o Spec Kit, toolkit open source para esse fluxo. Várias organizações relataram mudança de throughput ao adotar.

Tópicos​

Universais 🌐​

  • O que é spec-driven development e por que funciona
  • Estrutura de uma boa spec: contexto, objetivos, requisitos, restrições, critérios de aceitação, edge cases
  • Fluxo Explore → Plan → Code → Commit
  • Spec vs. PRD vs. design doc — quando usar cada formato

Específico Claude Code​

  • Modo plan (Shift+Tab) como ferramenta primária para spec interativa
  • CLAUDE.md como spec persistente do projeto inteiro
  • .claude/rules/ para regras escopadas
  • Subagentes recebendo specs como input

Ferramentas​

  • GitHub Spec Kit — toolkit oficial, suporta Claude Code (constitution → specify → plan → tasks → implement)
  • claude-code-spec-workflow (Pimzino) — workflows automatizados para spec-driven dev e bug fix
  • cc-sdd (gotalab) — minimal spec-driven harness com Skills

Materiais​

Conceituais ⭐​

Ferramentas (hands-on) ⭐​

  • ⭐ 🛠️ GitHub Spec Kit · [EN] [Grátis] Toolkit oficial open source. Suporta Claude Code, Copilot, Gemini CLI. Use durante o exercício.

  • 🛠️ claude-code-spec-workflow (Pimzino) · [EN] [Grátis] Workflow automatizado para Claude Code: Requirements → Design → Tasks → Implementation, mais um workflow de bug fix.

  • 🛠️ cc-sdd (gotalab) · [EN] [Grátis] Mais minimalista, foca em autonomia de longa execução com Skills. Compatível com vários agentes.

Tutorial guiado​

Documentação Anthropic​

Exercício prático​

Escolha uma feature pequena de um projeto seu (ou inicie um projeto novo) e construa via spec-driven:

  1. Instale GitHub Spec Kit (uv tool install spec-kit-cli ou equivalente)
  2. Inicialize o fluxo: constitution → specify → plan → tasks → implement
  3. Use Claude Code como agente em todas as etapas
  4. Compare o resultado com o que você faria com prompts soltos
  5. Documente em learnings-spec-driven.md:
    • Quanto tempo levou cada etapa
    • Quanto retrabalho houve vs. seu fluxo anterior
    • Onde a spec foi insuficiente e teve que iterar

Definition of Done​

  • Você completou pelo menos 1 feature via spec-driven completo
  • Tem opinião informada sobre quando spec-driven vale o overhead vs. quando é exagero
  • Sabe usar CLAUDE.md como camada de spec persistente
  • Conhece pelo menos 1 ferramenta de spec workflow (Spec Kit, Pimzino, ou cc-sdd)

M7 · Test-Driven Development com Claude Code

Por que este módulo​

🌐 TDD com IA é particularmente poderoso porque o agente performa muito melhor quando tem um alvo verificável (testes que precisam passar). É a versão moderna e justificada do TDD — o agente itera até verde, sem teimosia.

A trinca Red → Green → Refactor ganha um quarto passo: Validate (você revisa que o agente não fez batota, não escreveu testes para o código que ele já escreveu, não ignorou edge cases).

Tópicos​

Universais 🌐​

  • Red → Green → Refactor → Validate
  • Por que TDD com agente é diferente de TDD humano
  • Como evitar anti-padrões: agente escrevendo testes vazios, mockando demais, atalhos
  • Como dar alvos verificáveis ao agente (asserts específicos, edge cases explícitos)

Específico Claude Code​

  • Padrão Write tests, commit; code, iterate, commit (Anthropic best practices)
  • Usar plan mode para escrever a spec dos testes primeiro
  • Subagente "verificador" que revisa se o agente não trapaceou
  • Skill de TDD customizada (existem várias na comunidade)

Materiais​

Conceitual ⭐​

Cursos pagos​

Skills e ferramentas comunitárias 🛠️​

Artigos práticos​

Exercício prático​

Escolha uma feature nova que vai precisar implementar (algo real, ~2–4h de trabalho normalmente).

  1. Crie um branch
  2. Inicie sessão Claude Code
  3. Use o prompt: "Vamos fazer TDD. Para a feature X, escreva os testes primeiro cobrindo casos felizes, casos de erro e edge cases. Não implemente o código ainda. Confirme que os testes falham."
  4. Revise os testes manualmente — eles refletem o comportamento que você quer?
  5. Peça implementação: "Agora implemente o código mínimo para fazer todos os testes passarem. Não modifique os testes."
  6. Verifique que passou
  7. Refactor: "Refatore para legibilidade sem alterar comportamento. Confirme que os testes continuam passando."
  8. Validate manual: rode os testes, leia a implementação, garanta que não tem mock indevido

Documente em learnings-tdd.md: o que funcionou, onde Claude tentou trapacear, quais prompts impediram batota.

Definition of Done​

  • Você fez pelo menos 1 feature inteira via TDD com Claude Code
  • Identifica em 30 segundos se Claude está "trapaceando" (escrevendo testes para o que ele já escreveu)
  • Tem 1 prompt template para TDD pronto no seu playbook
  • Conhece pelo menos 1 Skill ou slash command de TDD (instalada ou referenciada)

M8 · Git, PR e code review com Claude Code

Por que este módulo​

Git, PRs e code review consomem muito tempo cognitivo dos devs. Claude Code automatiza esses três pontos com qualidade alta — desde mensagens de commit semânticas até PR review estruturado em GitHub Actions.

A Anthropic mantém um plugin oficial de Code Review com pipeline de 4 fases (qualificação → resumo → revisão paralela por 5 agentes especializados → verificação final). Está em research preview em planos Team/Enterprise.

Tópicos​

Workflow Git diário com Claude Code​

  • Geração de mensagens de commit semânticas
  • Geração de descrições de PR (título + corpo + checklist)
  • Resolução de merge conflicts com Claude Code
  • Atribuição "Co-authored-by: Claude" (convenção, não obrigatório)

Code review​

  • Comando /review integrado
  • Plugin oficial Code Review da Anthropic (5 agentes especializados)
  • Comentar @claude review em PRs do GitHub para review on-demand
  • Comparativo: o que Claude pega bem vs. o que ele perde

Automação com GitHub Actions​

  • anthropics/claude-code-action — Action oficial
  • Trigger em open/update de PR
  • Postar review como comentários inline
  • Configurar via CLAUDE.md e workflow YAML
  • Custo e segurança (secrets, allowlists)

Materiais​

Documentação oficial ⭐​

Guias práticos ⭐​

Reviews honestos​

Git workflow​

Skills comunitárias​

Exercício prático​

  1. Configure um template de commit message no CLAUDE.md do seu projeto (Conventional Commits, por exemplo)
  2. Use Claude Code para criar 5 commits em um branch real seguindo o template
  3. Crie um PR com descrição gerada por Claude Code (título, corpo, checklist)
  4. Configure claude-code-action no repositório (use a Action oficial da Anthropic)
  5. Abra um novo PR e veja o review automático rodando
  6. Critique o review: o que Claude pegou? O que perdeu? Compare com o artigo da LogRocket
  7. Documente em learnings-pr-review.md

Definition of Done​

  • Você gera commit messages e descrições de PR exclusivamente via Claude Code
  • Tem claude-code-action rodando em pelo menos 1 repositório seu
  • Sabe quando o review automático é confiável e quando não é
  • Configurou o trigger @claude review ou similar para review on-demand

M9 · Debugging e resolução de erros com Claude Code

Por que este módulo​

Debugging é a tarefa onde Claude Code mais brilha — porque combina três coisas: leitura de muitos arquivos (call stack), raciocínio multi-passo (do sintoma à causa raiz) e iteração até verde (rodar testes/scripts e validar fix). Estudos práticos relatam ~95% de fix-rate na primeira tentativa com workflow estruturado vs. ~40% com prompts soltos.

Tópicos​

Workflow estruturado de debugging com Claude Code​

  • Fase 1 — Investigação: capturar stack trace completa, anexar código relevante, pedir análise (NÃO peça fix ainda)
  • Fase 2 — Hipótese e validação: pedir 2–3 hipóteses, validar com leitura adicional ou logs
  • Fase 3 — Fix mínimo: aplicar correção mínima e rodar testes
  • Fase 4 — Regressão: pedir teste de regressão automatizado para o bug específico

Princípios universais 🌐​

  • Sempre rastrear até a causa raiz, nunca corrigir só o sintoma
  • Stack trace completa, não apenas a última linha
  • Reproduzir o bug primeiro, fixar depois
  • Test de regressão antes de fechar

Específico Claude Code​

  • think hard ou ultrathink para bugs realmente difíceis
  • Subagente especializado em debugging (definição em .claude/agents/)
  • Hooks PostToolUse para rodar testes automaticamente após edição

Materiais​

Documentação e blog oficiais ⭐​

Guias práticos ⭐​

Skills e patterns comunitárias​

Exercício prático​

Pegue 2 bugs reais (do seu trabalho ou do backlog do seu projeto pessoal):

Bug A — médio: stack trace claro, hipótese rápida.

  1. Cole stack trace completa no Claude Code
  2. Peça análise sem fix
  3. Valide hipótese
  4. Aplique fix e rode testes
  5. Crie teste de regressão

Bug B — difícil: intermitente, multi-arquivo, ou de comportamento.

  1. Use ultrathink ou think hard
  2. Use modo plan para planejar a investigação antes
  3. Considere subagente "investigador" (você define em .claude/agents/)
  4. Documente o caminho até a causa raiz

Anote em learnings-debugging.md:

  • Tempo para cada bug com Claude Code
  • Tempo estimado se fosse fazer sozinho
  • Onde Claude foi essencial vs. onde atrapalhou

Definition of Done​

  • Você usa Claude Code como ferramenta de debug primária para bugs não triviais
  • Tem 1 prompt template de debug no seu playbook
  • Cria teste de regressão para todo bug não trivial que você fixa
  • Conhece quando ativar ultrathink

M10 · Documentação técnica automatizada

Por que este módulo​

Documentação é o lugar mais óbvio onde IA agrega valor — e ainda assim a maioria dos times gera documentação ruim porque trata como "tarefa de uma vez só". Claude Code permite manter documentação sincronizada com código via hooks, slash commands e workflows recorrentes.

Tópicos​

Tipos de documentação automatizável​

  • Inline: JSDoc, docstrings (Python), TSDoc (TypeScript)
  • README: estrutura, badges, exemplos, troubleshooting
  • API docs: OpenAPI/Swagger gerados de tipos/schemas
  • Diagramas: Mermaid e PlantUML gerados a partir de código (sequence, ER, architecture)
  • Changelogs: gerados a partir de commits e PRs
  • ADRs (Architecture Decision Records) assistidos por Claude

Manter documentação sincronizada​

  • Slash command /update-docs customizado
  • Hook PostToolUse que pede sync de docs após mudança grande
  • Subagente "documentation reviewer" que roda em PRs

Materiais​

Documentação oficial ⭐​

Guias e exemplos​

Hands-on​

  • 🛠️ Pegue qualquer projeto seu sem README e faça Claude gerar um README completo a partir do código
  • 🛠️ Pegue qualquer função sem docstring e peça documentação inline com exemplos

Exercício prático​

  1. Em um projeto seu sem README decente, peça a Claude um README completo (estrutura: O que é, instalação, uso, arquitetura, contributing, license)
  2. Adicione diagrama Mermaid de arquitetura ao README, gerado por Claude a partir do código
  3. Crie um slash command customizado /update-docs em .claude/commands/update-docs.md que padroniza a tarefa
  4. Crie um changelog gerado a partir de commits com Claude
  5. Adicione docstrings ricas em pelo menos 1 módulo crítico

Definition of Done​

  • Tem README de qualidade gerado em pelo menos 1 projeto seu
  • Pelo menos 1 diagrama Mermaid no README
  • Tem slash command /update-docs ou equivalente no seu setup
  • Sabe gerar changelog do nada em segundos

M11 · Codebases grandes com Claude Code

Por que este módulo​

Em projetos pequenos, Claude Code "só funciona". Em monorepos e codebases grandes, sem estratégia, ele se afoga: lê arquivos demais, perde contexto, repete trabalho, ignora convenções escopadas.

A solução tem 3 pilares: CLAUDE.md hierárquico, subagentes para exploração, e orchestrator pattern com paralelização. Times relatam ~4x redução em overhead de contexto com escopo correto.

Tópicos​

Hierarquia de CLAUDE.md​

  • ~/.claude/CLAUDE.md — preferências globais do dev
  • <projeto>/CLAUDE.md — convenções do projeto
  • <projeto>/<modulo>/CLAUDE.md — escopadas por área (frontend, backend, infra)
  • .claude/rules/ para regras ainda mais granulares

Subagentes para exploração​

  • "Code search agent" — exploração em context window separada
  • "Architecture agent" — entende estrutura sem poluir contexto principal
  • Subagentes reportam resumos, não dump de arquivos

Orchestrator pattern (4 fases)​

  1. Clarify — agente principal entende o pedido
  2. Plan — gera plano com tarefas independentes
  3. Dispatch — dispara subagentes em paralelo
  4. Verify — agente principal consolida e valida

Padrões em monorepo​

  • 1 subagente por módulo (auth, db, api, frontend)
  • Skills específicas por área
  • Plugins de time compartilhados
  • Convenção compartilhada via AGENTS.md (padrão emergente cross-tool)

Materiais​

Oficial Anthropic ⭐​

Casos práticos ⭐​

Exercício prático​

Use um repositório grande (seu monorepo de trabalho, ou clone um open source grande tipo vercel/next.js, microsoft/vscode, kubernetes/kubernetes):

  1. Mapeie a estrutura: crie CLAUDE.md na raiz com mapa do repo, módulos, convenções globais
  2. Escope: crie CLAUDE.md em pelo menos 2 subpastas (módulos diferentes)
  3. Crie 2 subagentes especializados em .claude/agents/:
    • Um "explorer" que mapeia código sem editar
    • Um "module-X-expert" para um módulo específico
  4. Faça uma tarefa real que toque 2+ módulos e use o orchestrator pattern (Claude principal delega para subagentes)
  5. Compare: quantas vezes Claude precisou re-ler o mesmo arquivo? Quanto contexto foi economizado?
  6. Documente em learnings-large-codebase.md

Definition of Done​

  • Tem CLAUDE.md hierárquico em pelo menos 1 codebase grande sua
  • Definiu pelo menos 2 subagentes em .claude/agents/
  • Executou pelo menos 1 tarefa multi-módulo com orchestrator pattern
  • Sabe quando subagente vale o overhead vs. quando é exagero

Capstone da Fase 2 (entregável integrador)

Aplique os 7 módulos em um projeto real seu (seu produto, side project, ou contribuição para open source). Não precisa ser uma feature gigante — escolha algo de ~10–15h de trabalho real.

Requisitos​

  • Feature implementada via spec-driven (M6)
  • Implementação seguiu TDD (M7)
  • Pelo menos 5 commits com mensagens geradas via Claude Code (M8)
  • PR com descrição automática (M8)
  • claude-code-action ativo no repositório (M8)
  • Pelo menos 1 bug real debugado com workflow estruturado documentado em learnings-debugging.md (M9)
  • README e diagrama Mermaid atualizados via Claude Code (M10)
  • Se for monorepo/codebase grande: CLAUDE.md hierárquico + 1 subagente customizado (M11)
  • Arquivo final LEARNINGS-FASE-2.md consolidando aprendizados

Auto-avaliação ao final da Fase 2

  • Tenho 3+ prompt templates pessoais para tarefas recorrentes
  • Já fiz feature inteira via spec-driven com Spec Kit ou equivalente
  • Já fiz feature inteira via TDD com Claude Code
  • Tenho claude-code-action rodando em pelo menos 1 repo
  • Uso Claude Code como ferramenta primária de debug
  • Sei gerar README + diagrama Mermaid em minutos
  • Tenho CLAUDE.md hierárquico em codebase grande (se aplicável)
  • Defini pelo menos 1 subagente em .claude/agents/
  • Sei quando subagente vale o overhead

Se você marcou 7+ itens, está pronto para a Fase 3.

Próxima fase​

Fase 3 — Avançado: estendendo o agente (4 semanas) cobre os módulos M12 a M18: modo headless e CI/CD, MCP (Model Context Protocol), subagentes em profundidade, hooks e slash commands customizados, skills e plugins, controle de contexto avançado, e segurança/prompt injection.

Será expandida quando você concluir e validar a Fase 2.