O Fluxo de Trabalho de Producao - Entregando Funcionalidades Reais com o Claude Code

Claude Code - Fluxo de Trabalho de Produção

Aprenda um fluxo de trabalho estruturado em 5 fases e 10 etapas usando Claude Code, especificações em Markdown e arquivos de plano para entregar software .NET e frontend com qualidade de produção. (Traduzido e formatado com ajuda da IA, ajustado e adaptado por Macoratti)

Hoje, vou mostrar um fluxo de trabalho real com IA que pode ser usado para entregar aplicações em produção. (Você deve fazer os ajustes ao seu projeto e ambiente específicos)

No desenvolvimento de software moderno, existem dois caminhos comuns:

1 - Você não usa IA e passa semanas em decisões de arquitetura e meses escrevendo código boilerplate.
2 - Você usa IA intensamente, pega atalhos em cada decisão de arquitetura, faz vibe-coding em 98% do seu projeto e entrega rapidamente com baixa qualidade.

Nenhum desses caminhos é ótimo.

Existe um terceiro caminho: tratar a IA como sua assistente em um processo estruturado, onde cada etapa se baseia no resultado da anterior.

Você continua sendo o arquiteto e o tomador de decisões. O Claude acelera cada etapa.

Hoje veremos um panorama completo, incluindo o arquivo de planejamento (plan file).

Neste artigo, vamos explorar:
• Por Que a Maioria dos Códigos Gerados por IA Falha em Produção
• O Fluxo de Trabalho: Cinco Fases da Ideia à Produção
• O Arquivo de Plano: Sua Única Fonte da Verdade
• Trabalhando Através de Repositórios
• Passando o Trabalho para Outra Equipe

Vamos mergulhar nisso.

Por Que a Maioria dos Códigos Gerados por IA Falha em Produção

A forma mais comum pela qual os desenvolvedores usam IA para codificação é o já conhecido: "vibe coding".

Você abre um chat, digita "crie para mim uma API REST para gerenciar pedidos" e recebe de volta algo que compila e até funciona.

O código gerado normalmente tem:
• Validação de entrada fraca (ou apenas instruções if-else inline);
• Nenhuma estratégia global de tratamento de erros;
• Nenhuma estrutura de projeto consistente;
• Configuração hard-coded (fixada no código);
• Nenhum logging ou observabilidade;
• Nenhum teste (ou testes de qualidade pura).

Isso acontece porque a IA não tem contexto sobre o seu projeto e o seu destino.

Ela não conhece suas decisões de arquitetura, suas convenções ou suas restrições de deploy. Ela fornece um resultado genérico para prompts genéricos.

Código pronto para produção é diferente: arquitetura consistente em toda a base de código, entradas validadas, um formato unificado de erros, observabilidade e uma suíte de testes real.

Você não consegue chegar lá apenas com prompts de uma só vez. Você precisa de um processo.

O Fluxo de Trabalho: Cinco Fases da Ideia à Produção

Veremos agora apresentar um fluxo de trabalho que possui 5 fases e 10 etapas:

• Fase 1: Requisitos e Planejamento. Defina os requisitos de negócio (etapa 1) e os requisitos não funcionais (etapa 2). O Claude analisa seu documento de requisitos ou entrevista você para criar um, sinalizando cada ambiguidade antes que uma única linha de código exista.

• Fase 2: Arquitetura e Especificação. Projete a arquitetura (etapa 3) e gere uma especificação de backend (etapa 4). Use o Claude como um consultor de arquitetura, não uma autoridade: ele propõe algumas opções com prós e contras (trade-offs), e você mesmo teome a decisão (muitas vezes nem mesmo da lista proposta). O resultado é uma especificação detalhada em Markdown: entidades, endpoints, regras de negócio, validação.

• Fase 3: Implementação do Backend. Codifique o backend a partir da especificação (etapa 5), depois revise e refine (etapa 6). A revisão é executada em três etapas - qualidade do código, desempenho, segurança - cada uma em uma nova sessão para uma visão imparcial.

• Fase 4: Implementação do Frontend. Gere uma especificação de frontend (etapa 7) e implemente a interface de usuário (UI) a partir dela (etapa 8). A especificação do frontend inclui exemplos exatos de requisição e resposta em JSON para cada endpoint, portanto a implementação exige zero adivinhação.

• Fase 5: Deploy. Automatize o CI/CD (etapa 9), depois faça a revisão humana, teste e faça o deploy (etapa 10). A etapa final é inteiramente humana: execute cada fluxo de usuário manualmente, teste os casos extremos (edge cases), leia o código.

Cada fase produz artefatos - documentos e especificações - que alimentam a próxima fase.

Vamos explorar cada etapa em mais detalhes.

Etapa 1: Definir Requisitos de Negócio

Todo projeto começa com requisitos (independentemente de você usar IA ou não).

Pule esta etapa e você gastará mais tempo corrigindo mal-entendidos do que escrevendo código.

Um Documento de Requisitos de Negócio - DRN - (Business Requirements Document) descreve o que o sistema deve fazer da perspectiva do usuário. Ele cobre funções de usuário, funcionalidades principais, fluxos de trabalho, regras de negócio e casos extremos.

Se você já tiver um BRD, envie-o para o Claude Code, mude para o modelo Opus 5 e use o Plan Mode (Modo de Planejamento) (você pode usar o modelo Fable AI se estiver no plano Max). O Opus pode lidar com 1 milhão de tokens em um único prompt, o que é suficiente para documentos com 500 páginas.

O Plan Mode diz ao Claude para analisar e raciocinar sobre o problema antes de gerar qualquer coisa. Isso é crítico. Sem ele, o Claude pulará direto para o código.

Aqui está o prompt usado para analisar requisitos de negócio:

Você é um Analista de Negócios Sênior revisando um Documento de Requisitos de Negócio.
Leia o BRD em anexo e analise-o minuciosamente.

Para cada funcionalidade, identifique e documente:
1. Todas as funções de usuário e suas permissões
2. Entidades principais e seus relacionamentos
3. Fluxos de trabalho completos do usuário (passo a passo)
4. Regras de negócio e restrições de validação
5. Casos extremos e cenários de erro
6. Quaisquer ambiguidades ou requisitos ausentes

Apresente sua análise como um documento estruturado.
Sinalize cada ambiguidade com uma tag [CLARIFICATION NEEDED]
para que possamos resolvê-la antes de passar para a arquitetura.

Se você não tiver um DRN, pode criar um de forma interativa. Descreva a ideia do seu projeto e peça ao Claude para gerar um DRN fazendo perguntas de esclarecimento a você:

Eu quero construir [descreva seu projeto em 2-3 frases].
Ajude-me a criar um Documento de Requisitos de Negócio fazendo-me perguntas de esclarecimento sobre:
- Funções e permissões de usuário
- Funcionalidades principais e fluxos de trabalho
- Regras de negócio e restrições
- Requisitos de integração

Faça perguntas uma seção por vez.
Depois que eu responder, resuma minhas respostas e passe para a próxima seção.

O objetivo desta etapa é eliminar a ambiguidade. Cada requisito não claro se tornará um bug ou um ciclo de retrabalho mais tarde.

Etapa 2: Definir Requisitos Não Funcionais (RNFS)

A maioria dos desenvolvedores ignora os requisitos não funcionais e paga por isso mais tarde durante incidentes em produção.

Requisitos não funcionais (RNFs) definem os atributos de qualidade do seu sistema:
• Disponibilidade: estará acessível quando os usuários precisarem?
• Escalabilidade: consegue lidar com 10x mais usuários sem uma reescrita?
• Desempenho: quão rápido responde sob carga?
• Custo: quanto custará para rodar em escala?
• Segurança: quem pode acessar o quê e como os dados são protegidos?
• Manutenibilidade: quão fácil é alterar ou estender mais tarde?
• Confiabilidade: ele se recupera graciosamente quando as coisas dão errado?
• Testabilidade: você consegue verificar se o código é facilmente testável?

Essas restrições afetam diretamente as decisões de arquitetura na próxima etapa.

Aqui está o prompt usado:

Com base nos requisitos de negócio que definimos, ajude-me a definir
os requisitos não funcionais para este projeto.

Para cada categoria abaixo, extraia do documento e,
se estiver ausente, sugira metas específicas e mensuráveis:

1. Disponibilidade: SLA de Uptime, tempo de inatividade aceitável por mês
2. Desempenho: Metas de tempo de resposta da API (p50, p95, p99),
   metas de tempo de carregamento de página
3. Escalabilidade: Usuários simultâneos esperados, taxa de crescimento de dados,
   cenários de carga de pico
4. Segurança: Método de autenticação, modelo de autorização,
   requisitos de criptografia de dados, necessidades de conformidade
5. Custo: Restrições de orçamento de infraestrutura, preferências de hospedagem
   (provedor de nuvem, auto-hospedado)

Apresente cada requisito com uma meta mensurável e o raciocínio por trás dela.

Isto é apenas um exemplo; sua tarefa como Arquiteto é definir os RNFs para o seu projeto. Existem muito mais do que os que foi citado.

Depois que o Claude sugerir metas, desafie-as. Elas são realistas para o tamanho do seu projeto? Você realmente precisa de 99,95% de uptime para o seu projeto?

A superengenharia (overengineering) começa com requisitos não funcionais inflados. O resultado desta etapa é um documento curto (geralmente de uma página) que guiará cada decisão de arquitetura a seguir.

Etapa 3: Projetar a Arquitetura

É aqui que muitos desenvolvedores cometem seu maior erro com IA: eles aceitam a primeira sugestão de arquitetura sem questioná-la.

Procure usar o Claude como um Consultor de Arquitetura, não como uma autoridade.

Apresente os requisitos e NFRs, peça opções com vantagens e desvantagens e, em seguida, tome a decisão.

Aqui está o prompt:

Você é um Arquiteto de Soluções. Preciso de ajuda para projetar a arquitetura
para o projeto descrito nos requisitos em anexo.

Com base nos requisitos de negócio e requisitos não funcionais,
proponha 2-3 opções de arquitetura.

Para cada opção, forneça:
1. Estilo de arquitetura (Monólito Modular, Microsserviços, Serverless)
2. Estrutura do projeto e limites de módulos/serviços
3. Escolha do banco de dados e abordagem de esquema
4. Abordagem de design de API (REST, GraphQL, gRPC, Eventos)
5. Estratégia de autenticação e autorização
6. Modelo de deploy

Para cada opção, indique claramente:
- Prós e contras
- Quais NFRs ela atende e quais ela abre mão (trade-offs)
- Requisitos de tamanho de equipe e especialização
- Complexidade estimada

Recomende uma opção e explique seu raciocínio.

Para a maioria dos projetos, o uso de um Monólito Modular com Vertical Slice Architecture desde o início resolve a grande maioria dos projetos.

Isso oferece limites de módulo limpos sem a complexidade operacional dos microsserviços. Você sempre pode extrair módulos em serviços separados mais tarde, se necessário.

Depois de escolher a arquitetura, uso uma conversa interativa para definir os detalhes:
• Limites dos módulos
• Abstrações compartilhadas
• Esquema do banco de dados
• Contratos de API
• Padrões de comunicação: síncrono ou assíncrono

O segredo é desafiar cada proposta. Pergunte "Por que esta abordagem em vez de X?" e "O que acontece quando Y falha?"

O resultado desta etapa é um documento de arquitetura que descreve a estrutura do sistema, escolhas de tecnologia e o raciocínio por trás delas.

Etapa 4: Gerar a Especificação do Backend

Uma especificação de backend é um arquivo Markdown detalhado que descreve cada aspecto da implementação.

É tão detalhada que um desenvolvedor poderia implementar todo o backend sem fazer muitas perguntas.

Quando você alimenta o Claude com um arquivo de especificação, o código gerado é consistente, segue seus padrões e exige retrabalho mínimo.

Antes de gerar qualquer especificação ou código, configure um arquivo


CLAUDE.md

na raiz do seu projeto. Esta é a coisa de maior impacto que você pode fazer.

O CLAUDE.md é um arquivo Markdown que o Claude Code carrega automaticamente no contexto quando você abre um projeto. Ele diz ao Claude sua pilha de tecnologia, arquitetura, convenções de código e padrões, de modo que cada arquivo gerado seja consistente desde o início.

Com o CLAUDE.md em vigor, seu prompt de especificação fica muito mais curto. O Claude já conhece a estrutura do seu projeto, nomenclatura de arquivos, padrões e convenções.

O prompt só precisa descrever o conteúdo específico do negócio: entidades, endpoints e regras de negócio.

Aqui está o prompt usado para:

Com base na arquitetura que projetamos, crie uma Especificação de
Implementação de Backend detalhada como um arquivo Markdown.

A especificação deve incluir:

1. Definições de Entidades
   - Todas as entidades como classes C# com tipos de propriedades
   - Value objects e enums
   - Relacionamentos de entidades

2. Banco de Dados
   - Configuração de mapeamento do EF Core para cada entidade
   - Migrações do EF Core
   - Estratégia de seed com dados de amostra usando Bogus

3. Endpoints de API
   - Para cada endpoint: método HTTP, rota, corpo da requisição,
     corpo da resposta com definições de records em C#
   - Regras de negócio e regras de validação por endpoint
   - Cenários de erro e respostas de erro esperadas

4. Autenticação e Autorização
   - Quais endpoints exigem autenticação
   - Quais endpoints exigem políticas ou funções específicas

Não há necessidade de descrever nomenclatura de arquivos, padrões de handler, registro de DI ou estrutura do projeto. O Claude já sabe tudo isso a partir do


CLAUDE.md

e da sua base de código.

Itere nesta especificação até que ela cubra todas as funcionalidades. Cada hora gasta na especificação economiza de 3 a 5 vezes mais horas de retrabalho, reescrita e depuração do código gerado.

Etapa 5: Codificar o Backend

Esta é a etapa principal de implementação. O Claude já conhece sua arquitetura, padrões, nomenclatura de arquivos e convenções.

Como resultado da etapa anterior, você obterá um arquivo MD com o plano de implementação exato.

A única coisa que precisamos fazer nesta etapa é clicar no botão "Approve and Start the Implementation" na janela do plano.

Etapa 6: Revisar e Refinar

Depois de gerar o código do backend e todos os testes passarem, revise-o.

Etapa 7: Gerar a Especificação do Frontend

O frontend precisa de sua própria especificação, separada do backend.

Podemos chamar esta especificação de Documento de Requisitos de Produto - DRP (Product Document Requirement).

O DRP faz referência à API do backend e inclui tudo o que um desenvolvedor frontend precisa para construir a UI.

Aqui está o prompt usado para gerar o DRP :

Com base no backend implementado, crie um Documento de Requisitos
de Produto (PDR) de Frontend como um arquivo Markdown.

O PDR deve incluir:

1. Fluxo de Autenticação
   - Página de login: requisição/resposta POST /api/users/login
   - Armazenar token JWT, chamar GetMe após o login
   - Fluxo de refresh token: interceptar respostas 401,
     chamar POST /api/users/refresh, tentar novamente a requisição original
   - Logout: limpar tokens e redirecionar para o login

2. Para Cada Página
   - Endpoints de API que ela chama com exemplos exatos de
     requisição e resposta em JSON
   - Layout de UI: quais campos exibir, entradas de formulário,
     colunas de tabela
   - Ações: botões de criar, atualizar, excluir
     com suas chamadas de API
   - Regras de validação correspondentes aos validadores do backend
   - Tratamento de erros: como exibir erros de API para o usuário

3. Renderização Condicional
   - Ler políticas de autorização de @file:UserPolicyConstants.cs
   - Mostrar/ocultar botões de ação com base em links HATEOAS
     nas respostas da API
   - Mostrar/ocultar páginas na navegação com base nas claims do usuário

4. Paginação
   - Como chamar endpoints paginados
   - Parâmetros de requisição (page, pageSize)
   - Formato da resposta (items, totalCount, totalPages)
   - UI: controles de página, seletor de tamanho de página

Inclua exemplos completos em JSON para cada requisição e resposta
para que a implementação do frontend exija zero adivinhação sobre
o contrato da API.

Observe a referência @file:UserPolicyConstants.cs. Isso diz ao Claude para ler as constantes reais de política do backend e usar os nomes exatos das claims no DRP .

O DRP gerado deve ser tão bom que um desenvolvedor front-end real possa implementar a UI sem perguntas adicionais. E o mesmo vale para o Claude Code.

O DRP faz a ponte entre backend e frontend incluindo os formatos JSON exatos para cada endpoint.

Você precisará criar um CLAUDE.md separado para o frontend.

Em seguida, depois de ter um documento de requisitos de produção para o frontend, outro desenvolvedor (ou você) ativará o modo de plano no Claude para criar o plano exato de implementação para o frontend com base neste DRP .

Etapa 8: Codificar o Frontend

Assim como no backend, clique no botão "Approve and Start the Implementation" na janela do plano.

P.S. Se você usa o Claude, pode conectar um MCP do Figma, deixar sua IA se comunicar com o Figma e gerar código de UI que segue o design exato (ele pode até baixar imagens do Figma).

Etapa 9: Automatizar o Deploy com CI/CD

Com o backend e o frontend funcionando, a próxima etapa é automatizar o deploy.

Aqui está o prompt usado para gerar pipelines de CI/CD:

Crie uma pipeline de CI/CD do GitHub Actions para este projeto.
A pipeline deve:

1. Ser acionada no push para a main e pull requests
2. Backend (.NET):
   - Restaurar, compilar e executar todos os testes
   - Construir imagem Docker
   - Fazer push para o registro privado de contêineres do GitHub
3. Frontend (React):
   - Instalar dependências
   - Executar linter e testes
   - Construir o pacote de produção
4. Fazer deploy para [seu ambiente de destino]

Use jobs separados para backend e frontend para que rodem em paralelo.
Faça cache de pacotes NuGet e módulos npm para builds mais rápidos.
Use variáveis de ambiente para segredos (nunca os coloque hard-coded).

Ajuste o destino do deploy para corresponder à sua infraestrutura. Quer seja Azure App Service, AWS ECS, um cluster Kubernetes ou uma VPS simples com Docker Compose, o prompt deve especificar o destino exato.

Mas quem executa os comandos para fazer o deploy do seu aplicativo, para executar scripts do Terraform ou Pulumi, deve ser você. E quase nunca a IA.

Aposto que você já ouviu histórias assustadoras sobre IA apagando bancos de dados de produção... Tudo porque os comandos não foram cuidadosamente revisados e foram autorizados a serem executados sem a confirmação de um humano.

Etapa 10: Revisão Humana, Teste e Deploy

Esta etapa final é inteiramente humana.

• Execute a aplicação de ponta a ponta: Teste cada fluxo de usuário manualmente. Clique pela UI. Chame cada endpoint de API. Verifique se as mensagens de erro fazem sentido. Verifique se a autorização funciona corretamente para diferentes funções de usuário.

• Revise o código gerado você mesmo: Leia os handlers, validadores e endpoints. Procure por erros de lógica de negócio que a IA possa ter deixado passar. A IA é excelente em seguir padrões, mas não entende o domínio do seu negócio tão bem quanto você.

• Teste casos extremos: O que acontece quando você envia um formulário vazio? O que acontece quando dois usuários editam o mesmo registro simultaneamente? O que acontece quando o banco de dados está fora do ar?

Quando encontrar problemas, volte ao Claude com feedback específico. Faça referência ao arquivo e à linha reais:

Em CreateOrder.Handler.cs, o handler não verifica se o cliente
existe antes de criar o pedido. Adicione uma verificação que retorna
Error.NotFound se o ID do cliente for inválido.

O Feedback específico produz correções específicas. "A criação de pedidos está quebrada" é apenas um desperdício de tokens.

P.S.: Você também pode usar IA para ajudá-lo a criar casos de teste para testes automatizados e manuais. Frequentemente, a IA cria um conjunto de testes mais detalhado do que um humano. Mas ela não consegue raciocinar da mesma forma que um humano e não conhece todas as nuances e detalhes. Sempre revise os testes gerados por IA, adicione e refine-os conforme necessário.

O Arquivo de Plano: Sua Única Fonte da Verdade

Uma sessão do Claude é um lugar terrível para armazenar um plano.

A janela de contexto fica cheia. A sessão termina. Seu laptop reinicia. E seu colega de equipe não tem ideia do que você e o Claude concordaram ontem.

Por isso, a conversa não deve ser tratada como a fonte da verdade. Agora, todo trabalho real começa com um arquivo de plano : um documento Markdown em uma pasta plans/ na raiz do repositório.

O arquivo de plano registra o que fazer, o que está feito, como foi verificado e o que uma sessão futura precisa saber.

Aqui está o prompt usado para criar cada plano:

# Trabalho Real

Transforme o planejamento em um artefato durável e retomável. O arquivo de plano — e não a
conversa — é a fonte da verdade: ele registra o que fazer, o que está feito, como
foi verificado e como fazer o deploy. Qualquer agente futuro pode retomar a partir dele com zero
contexto prévio.

**Use quando** planejar trabalhos de várias etapas / várias sessões que possam durar mais do que a sessão
atual. Pule para tarefas triviais de sessão única.

## 1. Alcance o entendimento completo primeiro

**Não** escreva o plano até que o escopo seja totalmente compreendido. Faça perguntas incansavelmente
ao usuário até que ambos compartilhem um entendimento completo, **sem lacunas** —
trate uma pergunta não feita como um bug futuro.

- Não pare na primeira rodada; continue até que nenhuma ambiguidade, suposição ou
  decisão em aberto permaneça. Investigue as bordas: limites do escopo (dentro/fora), dependências,
  restrições, critérios de sucesso, dados, ambientes, deploy, casos de falha.
- Traga à tona todas as suposições para o usuário confirmar. Se uma resposta abrir uma nova
  incógnita, faça a pergunta de acompanhamento — aprofunde-se recursivamente.
- Use `AskUserQuestion` para escolhas concretas. Quando terminar, resuma o escopo completo
  de volta e prossiga apenas quando o usuário confirmar que nada está faltando.

## 2. Escreva o plano

Salve em `plans/<nome-descritivo>.md` na **raiz do repositório** (crie `plans/`
se necessário). Use este modelo autodocumentado:

"""
# <Título do Trabalho>

<1-2 frases de objetivo e escopo.>

## Para Agentes Futuros
Conforme o trabalho avança: marque as caixas de seleção `- [x]` à medida que os itens forem concluídos; quando uma fase terminar,
defina seu status como `Complete` e escreva seu **Resumo da Fase** (o que foi feito, decisões
principais, qualquer coisa necessária para continuar com zero contexto); execute o **Plano de
Verificação** da fase e registre o resultado antes de prosseguir. Quando todas as fases estiverem
concluídas, preencha a **Recapitulação Final** e o **Plano de Deploy**.

## Fase 1: <Título>
Status: Not started   <!-- Not started | In progress | Complete -->

- [ ] <item concreto e acionável>
- [ ] <item concreto e acionável>

### Plano de Verificação
- <comando/verificação que o agente pode executar autonomamente, com o resultado esperado>

### Resumo da Fase
_(escreva quando a fase for concluída)_

## Fase 2: <Título>
Status: Not started
- [ ] <item acionável>

### Plano de Verificação
- <verificação autônoma>

### Resumo da Fase
_(escreva quando a fase for concluída)_

## Recapitulação Final
_(escreva quando todas as fases forem concluídas: resumo de todo o trabalho)_

## Plano de Deploy
_(escreva quando todas as fases forem concluídas: instruções de deploy passo a passo)_
"""

## Erros comuns

- **Itens vagos** — cada caixa de seleção é uma tarefa concreta ("Adicionar lógica de nova tentativa em
  `PaymentClient.Charge`"), não um tema ("melhorar pagamentos").
- **Verificação não autônoma** — forneça comandos executáveis com a saída esperada,
  não "testar manualmente".
- **Localização errada** — sempre na pasta `plans/` da raiz do repositório.
- **Pré-preenchimento de resumos** — resumos de fases, recapitulação e plano de deploy permanecem como
  espaços reservados (placeholders) até que o trabalho seja realmente concluído.

Leia esse prompt novamente e observe a ordem:

1. A entrevista vem primeiro.
2. O plano vem em segundo.

Primeiro, o Claude me entrevista. Uma entrevista incansável até que não haja lacunas: limites de escopo, casos extremos, dependências, o que está explicitamente fora de escopo.

Cada pergunta que deixa de ser feita durante o planejamento se torna um bug durante a implementação.

Somente quando ambos compartilhamos um entendimento completo é que o Claude escreve uma única linha do plano.

Em seguida, o Claude escreve o arquivo de plano. Ele divide o trabalho em fases, e cada fase carrega três coisas:
• Caixas de seleção concretas: "Adicionar lógica de nova tentativa ao consumidor de e-mail" é uma tarefa. "Melhorar notificações" é um tema, e temas nunca são concluídos.
• Um plano de verificação: Comandos reais com resultados esperados, para que o Claude possa verificar seu próprio trabalho sem perguntar a você.
• Um resumo da fase: Escrito quando a fase é concluída, capturando o que foi feito e as principais decisões.

Conforme o trabalho acontece, o arquivo permanece atualizado: as caixas de seleção são marcadas, os status mudam, os resumos são preenchidos.

O retorno é enorme: qualquer nova sessão do Claude pode retomar o trabalho com zero contexto.

Você abre uma nova sessão amanhã, aponta-a para o arquivo de plano e ela sabe exatamente em que ponto as coisas estão: o que está feito, o que foi decidido e o que verificar antes de continuar.

Trabalhando Através de Repositórios

Projetos reais raramente vivem em um único repositório.

O backend está em um repositório. O frontend está em outro. Talvez haja uma biblioteca compartilhada de contratos em um terceiro.

O arquivo de plano resolve isso elegantemente, porque um arquivo Markdown é portátil.

Aqui está o fluxo para uma funcionalidade que abrange repositórios de backend e frontend:

1. Clone ambos os repositórios lado a lado em sua máquina.
2. Abra o Claude Code e dê a ele acesso a ambas as pastas.
3. Planeje a funcionalidade em ambas as bases de código: o Claude lê os padrões do backend e os padrões do frontend, e o plano cobre ambos os lados com o contrato da API no meio.
4. Implemente as fases do backend no repositório de backend.
5. Copie o arquivo de plano para o repositório frontend e continue lá em uma nova sessão.

A etapa 5 é o truque que a maioria dos desenvolvedores perde.

O arquivo de plano carrega todo o contexto: as decisões, o contrato da API, as fases concluídas e o que resta. A nova sessão no repositório de frontend o lê e continua como se tivesse estado lá o tempo todo.

Passando o Trabalho para Outra Equipe

Às vezes, o frontend não cabe a você construir.

Outro desenvolvedor é o responsável. Ou uma equipe separada de frontend trabalha em seu próprio repositório, com seu próprio fluxo de trabalho, talvez com um agente de IA diferente (ou sem ele).

É aqui que a geração de uma especificação em Markdown brilha.

Depois que o backend estiver pronto, podemos gerar uma especificação de frontend: cada página, cada chamada de API com exemplos exatos de requisição e resposta em JSON, regras de validação que correspondem aos validadores do backend e comportamento de tratamento de erros. Este é o documento exato que mostrei na "Etapa 7: Gerar a Especificação do Frontend".

Esse documento é um artefato de entrega completo e autossuficiente:
• Um desenvolvedor frontend implementa a partir dele sem perguntar sobre o contrato da API;
• Uma equipe de frontend o coloca em seu repositório como o documento de requisitos;
• E se eles usarem IA - Claude, Copilot ou qualquer outra coisa - a especificação é o input perfeito para ela.

A barra de qualidade que busco: um desenvolvedor que nunca viu o backend pode construir a UI a partir da especificação sem uma única pergunta de esclarecimento (Duh, eles ainda farão perguntas a você).

Especificações escritas em Markdown são a interface universal. Elas funcionam para humanos, funcionam para IA e sobrevivem a cada mudança de ferramenta.

Resumo

Assim, o resumo do fluxo de trabalho de produção tem 5 fases e 10 etapas :

Fase 1: Requisitos e Planejamento
• Etapa 1: Definir Requisitos de Negócio
• Etapa 2: Definir Requisitos Não Funcionais

Fase 2: Arquitetura e Especificação
• Etapa 3: Projetar a Arquitetura
• Etapa 4: Gerar a Especificação do Backend

Fase 3: Implementação do Backend
• Etapa 5: Codificar o Backend
• Etapa 6: Revisar e Refinar

Fase 4: Implementação do Frontend
• Etapa 7: Gerar a Especificação do Frontend
• Etapa 8: Codificar o Frontend

Fase 5: Deploy
• Etapa 9: Automatizar o Deploy com CI/CD
• Etapa 10: Revisão Humana, Teste e Deploy

Cada fase produz artefatos que alimentam a próxima fase.

Sua tarefa para hoje: escolha uma pequena funcionalidade futura. Peça ao Claude para entrevistar você sobre ela até que não haja dúvidas em aberto, depois escreva um arquivo de plano com fases, caixas de seleção e etapas de verificação em uma pasta plans/. Não implemente nada ainda — apenas experimente o quanto de clareza a entrevista força.

E estamos conversados..

"E andai em amor, como também Cristo nos amou, e se entregou a si mesmo por nós, em oferta e sacrifício a Deus, em cheiro suave."
Efésios 5:2

Referências:

José Carlos Macoratti