Voc\u00ea abre o terminal, dispara o Claude Code em um projeto que j\u00e1 tem seis meses de hist\u00f3ria, e pede para ele “adicionar autentica\u00e7\u00e3o por token na API”. Vinte minutos depois, o agente entregou um c\u00f3digo que compila, os testes passam, mas ele reescreveu o middleware de logging que outro desenvolvedor tinha ajustado na semana anterior, ignorou o padr\u00e3o de tratamento de erro que o time usa em todo o resto do sistema e criou uma depend\u00eancia nova que ningu\u00e9m pediu. Nada est\u00e1 “errado” no sentido de quebrar a build. Mas est\u00e1 errado no sentido de que agora existe um c\u00f3digo estranho ao projeto, escrito por uma ferramenta que n\u00e3o tinha ideia do que j\u00e1 existia ali.<\/p>\n
Esse cen\u00e1rio se repete porque a maioria dos desenvolvedores trata o Claude Code como um gerador de trechos isolados \u2014 cola um prompt, recebe um bloco, copia, segue. Funciona para scripts avulsos. N\u00e3o funciona quando o objetivo \u00e9 entregar uma feature completa, testada e em produ\u00e7\u00e3o, dentro de uma base de c\u00f3digo que outras pessoas tamb\u00e9m tocam. O problema n\u00e3o \u00e9 a ferramenta: \u00e9 a aus\u00eancia de um fluxo de trabalho definido, com etapas, checkpoints e responsabilidades claras entre voc\u00ea e o agente.<\/p>\n
Este artigo apresenta um fluxo operacional \u2014 do commit inicial da sess\u00e3o at\u00e9 o deploy \u2014 pensado para quem j\u00e1 usa Claude Code no dia a dia e quer parar de trat\u00e1-lo como sorteio de qualidade. Vamos cobrir estrutura\u00e7\u00e3o de contexto, quebra de tarefas, revis\u00e3o de diffs, integra\u00e7\u00e3o com testes e o momento em que a IA deve sair de cena e o processo de deploy tradicional assumir.<\/p>\n
Claude Code, como qualquer agente de codifica\u00e7\u00e3o, opera bem quando o espa\u00e7o de decis\u00e3o \u00e9 pequeno e o contexto est\u00e1 expl\u00edcito. O problema surge porque o espa\u00e7o de decis\u00e3o em um projeto real nunca \u00e9 pequeno: existem conven\u00e7\u00f5es n\u00e3o escritas, decis\u00f5es de arquitetura tomadas h\u00e1 meses, depend\u00eancias entre m\u00f3dulos que s\u00f3 quem trabalhou no c\u00f3digo sabe reconhecer visualmente. Um agente que n\u00e3o recebe esse contexto vai preencher as lacunas com suposi\u00e7\u00f5es razo\u00e1veis \u2014 e “razo\u00e1vel” para o modelo n\u00e3o \u00e9 o mesmo que “consistente com o seu projeto”.<\/p>\n
Segundo a discuss\u00e3o registrada em uma thread da comunidade r\/ClaudeAI sobre os fluxos de trabalho mais usados com a ferramenta<\/a>, o padr\u00e3o que se repete entre quem usa Claude Code de forma produtiva n\u00e3o \u00e9 “pe\u00e7a e receba”, mas sim um ciclo de planejamento, execu\u00e7\u00e3o em etapas pequenas e revis\u00e3o constante \u2014 muito mais pr\u00f3ximo de como se trabalha com um desenvolvedor j\u00fanior competente do que com um or\u00e1culo que acerta de primeira.<\/p>\n A analogia mais precisa \u00e9 a de um consultor externo contratado para uma tarefa espec\u00edfica. Ele \u00e9 competente, trabalha r\u00e1pido, mas n\u00e3o conhece a pol\u00edtica interna da empresa, n\u00e3o sabe quem decidiu o qu\u00ea nem por que aquela gambiarra no m\u00f3dulo de pagamento existe h\u00e1 dois anos. Se voc\u00ea n\u00e3o brifa esse consultor, ele vai entregar um trabalho tecnicamente correto e organizacionalmente incompat\u00edvel. O fluxo que vamos construir existe justamente para dar esse brifing de forma sistem\u00e1tica, sess\u00e3o ap\u00f3s sess\u00e3o.<\/p>\n Antes de pedir qualquer implementa\u00e7\u00e3o, o projeto precisa ter um arquivo de contexto persistente que o Claude Code carrega automaticamente. Isso evita repetir, prompt ap\u00f3s prompt, informa\u00e7\u00f5es que deveriam estar fixadas: conven\u00e7\u00f5es de nomenclatura, estrutura de pastas, ferramentas de teste, pol\u00edtica de tratamento de erro.<\/p>\n Um arquivo Esse arquivo n\u00e3o \u00e9 documenta\u00e7\u00e3o para humanos lerem depois \u2014 \u00e9 a mem\u00f3ria operacional que o agente consulta a cada sess\u00e3o. Sem ele, cada intera\u00e7\u00e3o come\u00e7a do zero, e o agente reinventa decis\u00f5es que o time j\u00e1 tomou.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> em um tutorial introdut\u00f3rio de Claude Code voltado a quem est\u00e1 come\u00e7ando<\/a>, fica evidente que a etapa de configura\u00e7\u00e3o inicial \u2014 arquivos de contexto, escopo de permiss\u00f5es, integra\u00e7\u00e3o com o reposit\u00f3rio \u2014 \u00e9 tratada como pr\u00e9-requisito, n\u00e3o como detalhe opcional. Pular essa etapa \u00e9 a causa mais comum de sess\u00f5es que “saem do trilho”.<\/p><\/blockquote>\n O erro mais recorrente \u00e9 jogar a tarefa inteira de uma vez: “implemente o m\u00f3dulo de recupera\u00e7\u00e3o de senha completo”. Isso for\u00e7a o agente a tomar decis\u00f5es de arquitetura, de fluxo e de nomenclatura simultaneamente, aumentando a superf\u00edcie de erro. O fluxo correto separa planejamento de execu\u00e7\u00e3o.<\/p>\n Primeiro, pe\u00e7a um plano, sem c\u00f3digo:<\/p>\n Com o plano em m\u00e3os, voc\u00ea valida antes de gastar uma \u00fanica linha de c\u00f3digo gerada. Se o passo 3 prop\u00f5e alterar o middleware de autentica\u00e7\u00e3o global \u2014 algo sens\u00edvel \u2014 voc\u00ea interv\u00e9m ali, antes que o agente j\u00e1 tenha escrito e testado tudo em cima dessa premissa. S\u00f3 depois de aprovar o plano \u00e9 que se pede a execu\u00e7\u00e3o, etapa por etapa:<\/p>\n Esse padr\u00e3o de “planeje, aprove, execute em partes” \u00e9 o mesmo descrito em um v\u00eddeo sobre constru\u00e7\u00e3o de sistemas completos do zero com IA<\/a>, no qual o autor mostra que sistemas maiores s\u00f3 se tornam manej\u00e1veis quando a IA trabalha sobre unidades pequenas e verific\u00e1veis, e n\u00e3o sobre a especifica\u00e7\u00e3o inteira de uma vez.<\/p>\n A cada etapa conclu\u00edda, antes de pedir a pr\u00f3xima, tr\u00eas verifica\u00e7\u00f5es r\u00e1pidas evitam ac\u00famulo de d\u00edvida:<\/p>\n Se qualquer um desses pontos falhar, a corre\u00e7\u00e3o deve ser pedida imediatamente, antes de avan\u00e7ar. Deixar acumular tr\u00eas ou quatro etapas com pend\u00eancias pequenas \u00e9 o caminho mais direto para uma sess\u00e3o de duas horas que termina em um Pedir “escreva testes para isso” depois que o c\u00f3digo j\u00e1 existe tende a gerar testes que confirmam o comportamento implementado, n\u00e3o que validam o comportamento esperado. A invers\u00e3o \u2014 pedir o teste antes ou junto da implementa\u00e7\u00e3o \u2014 funciona melhor com agentes de codifica\u00e7\u00e3o porque cria um alvo objetivo para a gera\u00e7\u00e3o.<\/p>\n Esse padr\u00e3o aproxima o fluxo de TDD assistido: voc\u00ea valida a especifica\u00e7\u00e3o atrav\u00e9s do teste \u2014 que \u00e9 leg\u00edvel e revis\u00e1vel rapidamente \u2014 antes de avaliar a implementa\u00e7\u00e3o inteira, que \u00e9 mais longa e mais custosa de revisar linha a linha.<\/p>\n Aceitar automaticamente tudo que o agente prop\u00f5e \u00e9 o ponto onde a maior parte dos problemas em produ\u00e7\u00e3o nasce. O Claude Code integra bem com o fluxo padr\u00e3o de revis\u00e3o via Git, e isso deve ser usado deliberadamente: cada etapa gera um commit isolado, revis\u00e1vel.<\/p>\n Usar \ud83d\udca1 Dica do Mestre:<\/strong> conforme apontado em uma compara\u00e7\u00e3o entre Claude Code e outras ferramentas de IA para desenvolvimento<\/a>, o diferencial do Claude Code \u00e9 rodar diretamente na sua m\u00e1quina, com controle total do ambiente \u2014 o que tamb\u00e9m significa que a responsabilidade pela revis\u00e3o do que ele produz \u00e9 inteiramente sua, sem a rede de seguran\u00e7a adicional que plataformas mais fechadas \u00e0s vezes oferecem.<\/p><\/blockquote>\n Depois que as etapas locais est\u00e3o validadas, o fluxo sai da sess\u00e3o interativa com o Claude Code e entra no territ\u00f3rio determin\u00edstico do CI\/CD. Esse \u00e9 um ponto de corte importante: a IA participa da cria\u00e7\u00e3o do c\u00f3digo, mas n\u00e3o deve ser o crit\u00e9rio de aprova\u00e7\u00e3o para o deploy. Essa fun\u00e7\u00e3o pertence ao pipeline, com testes automatizados, lint e build reproduz\u00edveis.<\/p>\n Um exemplo de workflow com GitHub Actions<\/a> ilustra esse limite:<\/p>\n O pull request gerado a partir de uma sess\u00e3o de Claude Code passa pelas mesmas verifica\u00e7\u00f5es que qualquer outro. Se o agente sugeriu uma depend\u00eancia nova, o Uma vez que o pipeline aprova o pull request e ele \u00e9 mesclado, o deploy pode ser automatizado normalmente \u2014 seja via cont\u00eainer, serverless ou build est\u00e1tico \u2014 sem que o Claude Code participe dessa etapa. A IA n\u00e3o deveria ter permiss\u00e3o de executar deploy diretamente para produ\u00e7\u00e3o; sua fun\u00e7\u00e3o termina na entrega de um pull request revis\u00e1vel. Manter esse limite claro evita o cen\u00e1rio em que uma sess\u00e3o automatizada de forma agressiva empurra c\u00f3digo n\u00e3o revisado para produ\u00e7\u00e3o porque “os testes passaram”.<\/p>\nO modelo mental correto: agente com contexto limitado, n\u00e3o or\u00e1culo<\/h3>\n
Etapa 1 \u2014 Preparando o terreno antes de qualquer prompt<\/h2>\n
CLAUDE.md<\/code> na raiz do reposit\u00f3rio cumpre esse papel:<\/p>\n# Contexto do projeto: api-pagamentos\n\n## Stack\n- Node.js 20, TypeScript, Fastify\n- Banco: PostgreSQL via Prisma\n- Testes: Vitest + Supertest\n\n## Conven\u00e7\u00f5es\n- Toda rota fica em src\/routes\/{recurso}.ts\n- Erros de neg\u00f3cio usam a classe DomainError (src\/errors)\n- Nunca lan\u00e7ar exce\u00e7\u00e3o gen\u00e9rica; sempre mapear para DomainError\n- Toda fun\u00e7\u00e3o p\u00fablica precisa de teste unit\u00e1rio correspondente\n\n## Decis\u00f5es de arquitetura j\u00e1 tomadas\n- Autentica\u00e7\u00e3o \u00e9 feita via middleware globalAuth, n\u00e3o repetir\n l\u00f3gica de verifica\u00e7\u00e3o de token em rotas individuais\n- Logs estruturados com pino, nunca console.log\n\n## O que N\u00c3O fazer\n- N\u00e3o instalar bibliotecas novas sem justificar no PR\n- N\u00e3o alterar o schema do Prisma sem gerar migration correspondente\n<\/code><\/pre>\nEtapa 2 \u2014 Quebrando a tarefa antes de pedir c\u00f3digo<\/h2>\n
Antes de escrever qualquer c\u00f3digo, liste as etapas necess\u00e1rias\npara implementar recupera\u00e7\u00e3o de senha por e-mail neste projeto,\nrespeitando o CLAUDE.md. N\u00e3o escreva implementa\u00e7\u00e3o ainda, apenas\no plano em passos numerados, com os arquivos que ser\u00e3o criados\nou alterados em cada etapa.\n<\/code><\/pre>\nExecute apenas a etapa 1 do plano: criar o endpoint\nPOST \/auth\/recover-password que gera o token e dispara o e-mail.\nN\u00e3o avance para as pr\u00f3ximas etapas.\n<\/code><\/pre>\nCheckpoints entre etapas: o que revisar<\/h3>\n
\n
git diff --stat\nnpm test\n<\/code><\/pre>\ngit reset --hard<\/code>.<\/p>\nEtapa 3 \u2014 Testes como contrato, n\u00e3o como formalidade<\/h2>\n
Escreva o teste de integra\u00e7\u00e3o para o endpoint\nPOST \/auth\/recover-password cobrindo:\n1. E-mail v\u00e1lido gera token e retorna 202\n2. E-mail inexistente retorna 202 tamb\u00e9m (n\u00e3o revelar exist\u00eancia)\n3. Requisi\u00e7\u00e3o sem campo email retorna 400 com DomainError\n\nDepois de eu aprovar o teste, implemente o endpoint para\nfaz\u00ea-lo passar.\n<\/code><\/pre>\nEtapa 4 \u2014 Revis\u00e3o de diff como o port\u00e3o real<\/h2>\n
git add -p\ngit commit -m \"feat: endpoint de recupera\u00e7\u00e3o de senha (etapa 1)\"\n<\/code><\/pre>\ngit add -p<\/code> em vez de git add .<\/code> for\u00e7a voc\u00ea a olhar cada trecho antes de confirmar \u2014 inclusive trechos que o agente alterou sem que voc\u00ea tenha pedido diretamente, como imports reorganizados ou formata\u00e7\u00e3o de arquivos vizinhos. Esse \u00e9 o mesmo tipo de disciplina que se aplicaria \u00e0 revis\u00e3o de um pull request de qualquer colega: ningu\u00e9m aprova um PR sem ler o diff, e n\u00e3o deveria haver excel\u00eancia diferente quando quem escreveu foi um agente.<\/p>\nEtapa 5 \u2014 Integra\u00e7\u00e3o cont\u00ednua: onde a IA para e o pipeline assume<\/h2>\n
name: ci\non: [pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - uses: actions\/setup-node@v4\n with:\n node-version: 20\n - run: npm ci\n - run: npm run lint\n - run: npm test -- --coverage\n - run: npm run build\n<\/code><\/pre>\nnpm ci<\/code> vai refletir isso no lockfile e o build vai expor eventuais incompatibilidades. N\u00e3o existe atalho: o c\u00f3digo gerado por IA entra na esteira como qualquer outro c\u00f3digo.<\/p>\nDeploy: automa\u00e7\u00e3o sim, confian\u00e7a cega n\u00e3o<\/h3>\n
name: deploy\non:\n push:\n branches: [main]\n\njobs:\n deploy:\n needs: test\n runs-on: ubuntu-latest\n steps:\n - uses: actions\/checkout@v4\n - run: npm ci && npm run build\n - name: Deploy\n run: .\/scripts\/deploy-production.sh\n<\/code><\/pre>\n