Voc\u00ea j\u00e1 passou pela seguinte situa\u00e7\u00e3o: abre o terminal, invoca uma IA para gerar um trecho de c\u00f3digo, cola no projeto, testa manualmente, ajusta um pouco, esquece de rodar os testes automatizados, sobe para o reposit\u00f3rio e s\u00f3 descobre que quebrou algo quando o cliente reclama em produ\u00e7\u00e3o. O c\u00f3digo at\u00e9 funcionava na sua m\u00e1quina \u2014 mas o caminho entre “funciona aqui” e “est\u00e1 no ar, est\u00e1vel, monitorado” ficou cheio de buracos, porque cada etapa foi feita de forma isolada, sem um fio condutor.<\/p>\n
Esse problema n\u00e3o \u00e9 da IA. \u00c9 de processo. Ferramentas como o Claude Code entregam muito valor quando usadas para gerar trechos pontuais, mas o ganho real de produtividade s\u00f3 aparece quando existe um fluxo de trabalho estruturado<\/strong> \u2014 do primeiro commit at\u00e9 o deploy \u2014 no qual a IA participa de forma consistente em cada etapa, e n\u00e3o apenas na hora de “escrever a fun\u00e7\u00e3o”. Neste artigo, vou apresentar um roteiro pr\u00e1tico, testado no dia a dia, para conduzir um projeto inteiro com o Claude Code como parceiro de desenvolvimento, cobrindo planejamento, implementa\u00e7\u00e3o, testes, revis\u00e3o, CI\/CD e deploy.<\/p>\n A maioria dos tutoriais sobre IA no desenvolvimento foca em prompts isolados: “pe\u00e7a isso e receba aquilo”. Isso \u00e9 \u00fatil para tarefas pontuais, mas gera uma armadilha: o desenvolvedor trata a IA como uma calculadora de c\u00f3digo, sem integr\u00e1-la ao ciclo de vida do software. O resultado \u00e9 um ac\u00famulo de trechos gerados que ningu\u00e9m revisou com crit\u00e9rio, testes que n\u00e3o cobrem os casos reais e um deploy manual, feito no improviso.<\/p>\n Um fluxo de trabalho bem desenhado resolve isso porque define o que a IA faz em cada fase<\/strong>, o que voc\u00ea valida antes de avan\u00e7ar<\/strong> e onde ficam os pontos de controle<\/strong>. \u00c9 a diferen\u00e7a entre usar uma furadeira sem plano de obra e seguir uma planta com etapas de funda\u00e7\u00e3o, estrutura e acabamento \u2014 a ferramenta \u00e9 a mesma, mas o resultado depende de como o trabalho foi organizado.<\/p>\n Vamos percorrer cada uma delas com exemplos concretos.<\/p>\n O primeiro erro comum \u00e9 pedir ao Claude Code para “criar uma API de pedidos” sem contexto. O resultado tende a ser gen\u00e9rico, desalinhado com as conven\u00e7\u00f5es do seu projeto. O ponto de partida deveria ser um arquivo de especifica\u00e7\u00e3o, versionado junto ao c\u00f3digo, descrevendo requisitos, regras de neg\u00f3cio e restri\u00e7\u00f5es t\u00e9cnicas.<\/p>\n Uma pr\u00e1tica eficaz \u00e9 manter um arquivo Com esse arquivo em vigor, cada solicita\u00e7\u00e3o feita ao Claude Code j\u00e1 carrega o contexto do projeto, reduzindo a necessidade de repetir instru\u00e7\u00f5es e aumentando a ader\u00eancia do c\u00f3digo gerado aos padr\u00f5es estabelecidos.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> a documenta\u00e7\u00e3o oficial do Claude Code detalha como o arquivo de contexto do projeto \u00e9 carregado e como estruturar instru\u00e7\u00f5es permanentes para a ferramenta. Vale a leitura antes de montar o seu: docs.claude.com\/en\/docs\/claude-code<\/a>.<\/p><\/blockquote>\n Al\u00e9m do contexto geral, cada nova funcionalidade merece uma especifica\u00e7\u00e3o curta, em linguagem natural, que sirva de prompt estruturado:<\/p>\n Esse n\u00edvel de detalhe evita ambiguidade e faz o modelo produzir algo alinhado ao que voc\u00ea realmente precisa, em vez de uma implementa\u00e7\u00e3o plaus\u00edvel, por\u00e9m gen\u00e9rica.<\/p>\n Com a especifica\u00e7\u00e3o pronta, o Claude Code entra em a\u00e7\u00e3o diretamente no terminal, com acesso de leitura e escrita ao reposit\u00f3rio. A instala\u00e7\u00e3o \u00e9 simples via npm:<\/p>\n A partir da\u00ed, voc\u00ea conversa com a ferramenta dentro do pr\u00f3prio projeto. Um ponto importante do fluxo \u00e9 usar o modo de planejamento<\/strong> antes de deixar a IA alterar arquivos, para revisar a abordagem sem risco:<\/p>\n O Claude Code responde com um plano de mudan\u00e7as \u2014 quais arquivos ser\u00e3o criados ou alterados, qual a ordem de execu\u00e7\u00e3o \u2014 antes de tocar em qualquer linha de c\u00f3digo. Isso \u00e9 equivalente a revisar a planta antes de come\u00e7ar a obra: voc\u00ea identifica decis\u00f5es question\u00e1veis (por exemplo, um novo pacote desnecess\u00e1rio, ou uma abstra\u00e7\u00e3o fora do padr\u00e3o) e corrige a rota antes do trabalho ser feito.<\/p>\n Depois de aprovar o plano, a execu\u00e7\u00e3o segue com edi\u00e7\u00f5es reais nos arquivos, e o Claude Code mostra o diff de cada altera\u00e7\u00e3o para aprova\u00e7\u00e3o incremental \u2014 nada \u00e9 aplicado silenciosamente.<\/p>\n O roteiro n\u00e3o muda de acordo com a linguagem; muda o contexto informado. Em um projeto Delphi legado, por exemplo, o mesmo princ\u00edpio de especifica\u00e7\u00e3o clara se aplica:<\/p>\n O mesmo vale para times que trabalham com Python, Go, Java ou qualquer outra stack: o diferencial n\u00e3o \u00e9 a linguagem, \u00e9 a clareza da instru\u00e7\u00e3o e o contexto de projeto dispon\u00edvel para o modelo.<\/p>\n Um c\u00f3digo gerado por IA sem teste automatizado \u00e9 uma promessa, n\u00e3o uma entrega. O fluxo precisa incluir, obrigatoriamente, a gera\u00e7\u00e3o e execu\u00e7\u00e3o dos testes como parte do mesmo ciclo \u2014 nunca como etapa posterior e opcional.<\/p>\n Um detalhe relevante do Claude Code \u00e9 a capacidade de executar comandos no terminal e reagir ao resultado \u2014 ele roda \ud83d\udca1 Dica do Mestre:<\/strong> para aprofundar como estruturar uma rede de seguran\u00e7a de testes especificamente pensada para c\u00f3digo gerado por IA, vale revisitar a l\u00f3gica de harness de testes, que trata desse tema em detalhe \u2014 um bom complemento a este roteiro de deploy.<\/p><\/blockquote>\n Antes do merge, o c\u00f3digo passa por revis\u00e3o humana e, idealmente, por uma revis\u00e3o automatizada adicional. O pr\u00f3prio Claude Code pode atuar como um segundo revisor, analisando o diff antes de voc\u00ea abrir o pull request:<\/p>\n Esse passo funciona como uma segunda opini\u00e3o antes da opini\u00e3o definitiva, que continua sendo humana. A IA \u00e9 \u00f3tima para apontar inconsist\u00eancias \u00f3bvias e desvios de padr\u00e3o; a decis\u00e3o final sobre arquitetura e trade-offs de neg\u00f3cio permanece com o time.<\/p>\n O pull request deve disparar um pipeline de CI que rode de forma independente do que foi validado localmente. Um exemplo de workflow do GitHub Actions:<\/p>\n Nenhum c\u00f3digo gerado por IA \u2014 ou por humano \u2014 deve chegar \u00e0 branch principal sem passar por esse port\u00e3o. Documenta\u00e7\u00e3o completa do GitHub Actions est\u00e1 dispon\u00edvel em docs.github.com\/pt\/actions<\/a>.<\/p>\n Com o c\u00f3digo revisado e integrado, o deploy deve ser automatizado, disparado pelo merge na branch principal. O Claude Code pode ajudar inclusive a escrever ou ajustar esse pipeline de deploy, mas a execu\u00e7\u00e3o em produ\u00e7\u00e3o nunca deve depender de um comando manual disparado por conveni\u00eancia.<\/p>\n Um exemplo simplificado de job de deploy, complementando o pipeline de CI anterior:<\/p>\n Se o projeto usa cont\u00eaineres, o mesmo princ\u00edpio se aplica com uma etapa adicional de build e push de imagem, seguida de atualiza\u00e7\u00e3o do servi\u00e7o em produ\u00e7\u00e3o \u2014 seja via Kubernetes, um provedor gerenciado ou uma plataforma como a Fly.io<\/a>.<\/p>\n Depois do deploy, o trabalho ainda n\u00e3o acabou. \u00c9 necess\u00e1rio observar m\u00e9tricas, logs e alertas para confirmar que o comportamento em produ\u00e7\u00e3o corresponde ao esperado. Aqui, o Claude Code tamb\u00e9m pode ser \u00fatil na fase de investiga\u00e7\u00e3o, analisando logs colados no terminal e sugerindo hip\u00f3teses de causa raiz, mas a decis\u00e3o de rollback ou hotfix deve seguir um processo claro, com crit\u00e9rios objetivos \u2014 por exemplo, taxa de erro acima de um limiar predefinido ou aumento anormal de lat\u00eancia.<\/p>\n \ud83d\udca1 Dica do Mestre:<\/strong> “You build it, you run it” \u2014 a m\u00e1xima atribu\u00edda \u00e0 cultura de engenharia da Amazon, popularizada por Werner Vogels, resume bem o esp\u00edrito dessa fase: quem escreve o c\u00f3digo, com ou sem IA, tamb\u00e9m acompanha o que acontece depois do deploy.<\/p><\/blockquote>\n Para tornar esse fluxo repet\u00edvel, vale registrar as etapas como um checklist dentro do pr\u00f3prio reposit\u00f3rio, em um arquivo como Esse documento vivo evita que o uso da IA vire uma pr\u00e1tica informal e dependente de quem est\u00e1 no teclado naquele dia \u2014 ele transforma o fluxo em um processo de equipe, reproduz\u00edvel por qualquer pessoa do time.<\/p>\n Montar esse roteiro sozinho, por tentativa e erro, consome tempo que poderia ser investido em entregar valor. Na Comunidade Dev’s AI<\/strong> compartilhamos fluxos de trabalho testados, templates de O Claude Code, como qualquer ferramenta de IA aplicada ao desenvolvimento, entrega o seu maior valor quando inserido em um fluxo de trabalho bem definido, e n\u00e3o quando usado de forma isolada para gerar trechos avulsos de c\u00f3digo. Planejamento com especifica\u00e7\u00e3o clara, implementa\u00e7\u00e3o assistida com revis\u00e3o incremental, testes automatizados como crit\u00e9rio de aceite, revis\u00e3o de qualidade antes do merge e deploy automatizado com observa\u00e7\u00e3o p\u00f3s-produ\u00e7\u00e3o formam um ciclo que reduz retrabalho e aumenta a confian\u00e7a em cada entrega. O ganho n\u00e3o est\u00e1 apenas na velocidade de escrever c\u00f3digo \u2014 est\u00e1 na consist\u00eancia de todo o caminho at\u00e9 o software estar, de fato, no ar e funcionando como esperado.<\/p>\n","protected":false},"excerpt":{"rendered":" Voc\u00ea j\u00e1 passou pela seguinte situa\u00e7\u00e3o: abre o terminal, invoca uma IA para gerar um trecho de c\u00f3digo, cola no projeto, testa manualmente, ajusta um pouco, esquece de rodar os testes automatizados, sobe para o reposit\u00f3rio e s\u00f3 descobre que quebrou algo quando o cliente reclama em produ\u00e7\u00e3o. O c\u00f3digo at\u00e9 funcionava na sua m\u00e1quina […]<\/p>\n","protected":false},"author":127,"featured_media":1077,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"class_list":["post-1076","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog"],"_links":{"self":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1076","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/users\/127"}],"replies":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/comments?post=1076"}],"version-history":[{"count":1,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1076\/revisions"}],"predecessor-version":[{"id":1078,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/posts\/1076\/revisions\/1078"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media\/1077"}],"wp:attachment":[{"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/media?parent=1076"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/categories?post=1076"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/adrianosantostreina.com.br\/blog\/wp-json\/wp\/v2\/tags?post=1076"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}Por que pensar em “fluxo” e n\u00e3o em “prompts soltos”<\/h2>\n
As cinco fases do roteiro<\/h3>\n
\n
Fase 1: Planejamento \u2014 antes de codificar, escrever a especifica\u00e7\u00e3o<\/h2>\n
CLAUDE.md<\/code> na raiz do reposit\u00f3rio \u2014 o Claude Code l\u00ea esse arquivo automaticamente ao iniciar uma sess\u00e3o, e ele funciona como a “planta baixa” do projeto:<\/p>\n# CLAUDE.md\n\n## Stack\n- Backend: Node.js 20 + TypeScript + Fastify\n- Banco: PostgreSQL via Prisma\n- Testes: Vitest + Supertest\n- Padr\u00e3o de commits: Conventional Commits\n\n## Regras de neg\u00f3cio\n- Todo pedido precisa ter ao menos um item.\n- Pedidos acima de R$ 500 exigem aprova\u00e7\u00e3o manual (status \"pending_review\").\n- Nunca expor o campo \"custo_interno\" nas respostas da API.\n\n## Conven\u00e7\u00f5es de c\u00f3digo\n- Controllers n\u00e3o acessam o banco diretamente; sempre via camada de reposit\u00f3rio.\n- Erros de neg\u00f3cio lan\u00e7am classes que estendem AppError.\n- Toda rota nova precisa de teste de integra\u00e7\u00e3o correspondente.\n<\/code><\/pre>\nEspecificando a funcionalidade da vez<\/h3>\n
Implemente o endpoint POST \/orders seguindo as regras do CLAUDE.md.\n\nRequisitos:\n- Receber { customerId, items[] } no corpo da requisi\u00e7\u00e3o.\n- Validar que items n\u00e3o est\u00e1 vazio.\n- Calcular o total somando price * quantity de cada item.\n- Se total > 500, status inicial deve ser \"pending_review\"; caso contr\u00e1rio, \"confirmed\".\n- Persistir via OrderRepository (n\u00e3o acessar o Prisma diretamente no controller).\n- Retornar 201 com o pedido criado, sem o campo custo_interno.\n\nGere tamb\u00e9m o teste de integra\u00e7\u00e3o cobrindo os dois cen\u00e1rios de status.\n<\/code><\/pre>\nFase 2: Implementa\u00e7\u00e3o assistida no terminal<\/h2>\n
npm install -g @anthropic-ai\/claude-code\nclaude\n<\/code><\/pre>\n\/plan Implemente o endpoint POST \/orders conforme a especifica\u00e7\u00e3o abaixo:\n[cole a especifica\u00e7\u00e3o]\n<\/code><\/pre>\nTrabalhando com m\u00faltiplas linguagens no mesmo fluxo<\/h3>\n
Refatore a unit UOrderService.pas para extrair a regra de c\u00e1lculo de\ndesconto (atualmente dentro de TOrderService.CalcularTotal) para uma\nclasse separada TDiscountCalculator, seguindo o padr\u00e3o Strategy.\nMantenha a assinatura p\u00fablica de CalcularTotal inalterada e gere\ntestes com DUnitX cobrindo desconto por volume e por cliente fidelidade.\n<\/code><\/pre>\nFase 3: Testes e valida\u00e7\u00e3o \u2014 a IA n\u00e3o substitui evid\u00eancia<\/h2>\n
Gere testes de integra\u00e7\u00e3o para o endpoint POST \/orders usando Vitest e\nSupertest, cobrindo:\n1. Pedido v\u00e1lido com total abaixo de 500 -> status \"confirmed\"\n2. Pedido v\u00e1lido com total acima de 500 -> status \"pending_review\"\n3. Requisi\u00e7\u00e3o sem items -> 400 com mensagem de erro clara\n4. Verificar que a resposta nunca cont\u00e9m o campo custo_interno\n\nDepois de gerar, rode os testes e corrija at\u00e9 todos passarem.\n<\/code><\/pre>\nnpm test<\/code>, l\u00ea a sa\u00edda, identifica falhas e ajusta o c\u00f3digo, em um ciclo iterativo, sem que voc\u00ea precise copiar e colar mensagens de erro manualmente.<\/p>\nChecklist de sa\u00edda da fase de testes<\/h3>\n
\n
skip<\/code> para “passar por enquanto”.<\/li>\nFase 4: Revis\u00e3o e integra\u00e7\u00e3o \u2014 o port\u00e3o de qualidade<\/h2>\n
Revise o diff atual em busca de:\n- Vazamento de dados sens\u00edveis nas respostas da API\n- Tratamento de erros ausente ou gen\u00e9rico demais\n- Duplica\u00e7\u00e3o de l\u00f3gica j\u00e1 existente em outro m\u00f3dulo\n- Ader\u00eancia \u00e0s conven\u00e7\u00f5es descritas em CLAUDE.md\n\nAponte os problemas encontrados, sem aplicar corre\u00e7\u00f5es ainda.\n<\/code><\/pre>\nIntegra\u00e7\u00e3o cont\u00ednua como rede de seguran\u00e7a<\/h3>\n
name: CI\n\non:\n pull_request:\n branches: [main]\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>\nFase 5: Deploy \u2014 do merge ao ar<\/h2>\n
deploy:\n needs: test\n if: github.ref == 'refs\/heads\/main'\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 build\n - name: Deploy\n run: npm run deploy\n env:\n DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}\n<\/code><\/pre>\nObserva\u00e7\u00e3o p\u00f3s-deploy: o fluxo n\u00e3o termina no “publicado”<\/h3>\n
Consolidando o roteiro em um s\u00f3 lugar<\/h2>\n
WORKFLOW.md<\/code>:<\/p>\n1. Escrever ou atualizar a especifica\u00e7\u00e3o da funcionalidade.\n2. Rodar `claude` e usar \/plan antes de qualquer edi\u00e7\u00e3o.\n3. Implementar com revis\u00e3o incremental dos diffs.\n4. Gerar e rodar testes; nenhum PR sem cobertura correspondente.\n5. Pedir revis\u00e3o automatizada de qualidade antes do PR.\n6. Abrir PR; aguardar CI (lint, testes, build).\n7. Merge dispara deploy automatizado.\n8. Observar m\u00e9tricas e logs por, no m\u00ednimo, o per\u00edodo cr\u00edtico definido pelo time.\n<\/code><\/pre>\nLeve esse fluxo para dentro da sua rotina com apoio de quem j\u00e1 passou por isso<\/h2>\n
CLAUDE.md<\/code>, pipelines de CI\/CD prontos para adaptar e discuss\u00f5es pr\u00e1ticas sobre como integrar IA em cada etapa do desenvolvimento \u2014 do planejamento ao deploy. Se voc\u00ea quer parar de reinventar processo a cada projeto, entre na comunidade: adrianosantos.link\/ComunidadeDevAI<\/a>.<\/p>\nConclus\u00e3o<\/h2>\n