Fluxo de trabalho greenfield do Claude Code: do repositório vazio à primeira fatia

O que você quer evitar ao começar greenfield

Começar de um repositório vazio parece liberdade, mas frequentemente vira um impulso desordenado: muitos arquivos gerados, um build meia-boca e nenhum lugar claro para colocar a próxima mudança. O objetivo do fluxo de trabalho greenfield do Claude Code é evitar esse caos da primeira semana.

Algumas falhas aparecem repetidamente:

• Código que “funciona na minha máquina” porque a configuração vive na memória de alguém, não em scripts.
• Uma árvore de pastas que reflete a ordem em que as coisas foram criadas, não como o app deve crescer.
• Um loop onde cada novo prompt reescreve escolhas anteriores, então nada vira algo estável.

Decisões iniciais são dolorosas de desfazer porque tudo se empilha sobre elas. Uma estrutura confusa se reforça. Um build manual vira dez setups diferentes. Se você não fixar um comando de dev simples cedo, não dá para saber se uma mudança quebrou o app ou apenas quebrou o ambiente.

Quando este post diz “app em execução”, quer dizer algo específico: um comando que inicia o projeto, imprime saída previsível e falha alto quando algo estiver faltando. Você deve conseguir apagar sua instalação local, clonar o repositório, executar esse comando e ver o mesmo resultado.

Uma “fatia vertical” é o menor recurso ponta a ponta que prova que seu app é real. Não é um mock de UI. Não é só uma tabela de banco de dados. É uma linha fina através de todo o sistema, como uma página com um formulário, um endpoint de API que salva dados, uma escrita/leitura no banco e um resultado visível na página.

Se você consegue rodar o app com um comando e entregar uma fatia vertical, tem uma base para iterar sem adivinhações.

Decida a primeira fatia antes de gerar qualquer coisa

Uma primeira fatia clara mantém o repositório enxuto e seus prompts focados. Este é o momento de decidir o que você quer demonstrar ponta a ponta, não o que espera que o produto completo se torne.

Escolha a menor história de usuário que prove que o app funciona por todo o caminho. Uma boa fatia toca UI, dados e uma ação real. Exemplo: “Como usuário, eu posso adicionar uma tarefa e vê-la aparecer na lista após atualizar.” É pequena, mas força roteamento, validação, armazenamento e uma tela básica.

Escolha uma plataforma alvo para a semana 1 e fixe-se nela. Se começar web, faça só web. Não adicione telas mobile “só por precaução”. Mesmo que planeje usar uma plataforma como Koder.ai depois, você terá melhores resultados se a primeira fatia ficar em uma única pista (React web, ou uma API em Go, ou Flutter).

Defina em termos simples o que significa “concluído para a semana 1”:

• Roda localmente a partir de um clone novo com um comando
• Uma feature funcionando que você consegue navegar ponta a ponta
• Erros mostram uma mensagem humana (não um stack trace)
• Dados persistem em algum lugar simples (mesmo um banco local)

Depois anote três não-objetivos que protejam o escopo. Por exemplo: sem auth, sem sistema de temas, sem jobs em background.

Quando essas decisões estiverem escritas, seu prompt de geração pode ser estrito: construa apenas o que suporta a fatia, e deixe o resto como TODO.

Algumas decisões iniciais que evitam retrabalho

Antes de pedir ao Claude para gerar qualquer coisa, fixe um conjunto de padrões. Eles parecem pequenos, mas evitam o problema de “renomear tudo depois”.

Primeiro, decida a forma do app. Se realmente precisa de UI no navegador e um backend, comece com duas partes claras (frontend + API) e um lugar compartilhado para contratos (tipos de API ou um esquema simples). Se o app pode ser um único web app server-side, mantenha um codebase para que o dev local fique simples.

Em seguida, combine regras de configuração. Use um arquivo .env local, mantenha-o fora do git e comite um template (por exemplo, .env.example) com placeholders seguros e comentários curtos. Isso facilita o onboarding e reduz vazamentos de segredos.

Escolha portas padrão de desenvolvimento e mantenha-as estáveis. Portas acabam em scripts, docs e mensagens de erro, então mudá-las depois é incômodo. Faça o mesmo para nomes: pastas, serviços e pacotes devem seguir uma convenção. Consistência importa mais do que a “conveniência perfeita”.

Um conjunto simples de decisões iniciais:

• Forma do app: app único ou frontend + API
• Config: .env local, .env.example comitado
• Portas: uma para web, uma para API, uma para DB (se necessário)
• Nomes: um estilo de casing para pastas, nomes de serviços consistentes
• Segredos: nunca comitar, rotacionar se expostos

Exemplo: você escolhe web na porta 3000 e api na porta 8080. Seu template de env inclui API_URL=http://localhost:8080 e DATABASE_URL=.... Quando o Claude gerar scripts e docs depois, tudo se encaixa em vez de derivar.

Como solicitar ao Claude Code para manter a estrutura

Comece pedindo um esqueleto executável, não “o app inteiro”. O caminho mais rápido para saída desordenada é solicitar features antes de ter um lugar para colocá-las.

Seja explícito sobre a estrutura. Peça um layout de pastas com comentários curtos que expliquem o que pertence a cada lugar e o que não pertence. Isso força decisões antes de espalhar arquivos.

Uma forma simples de manter disciplina é definir regras no prompt:

• Gere primeiro o menor esqueleto executável (página de hello, endpoint de health ou uma tela)
• Proponha uma estrutura de pastas e explique cada pasta em 1 frase
• Adicione scripts que funcionem em uma máquina limpa (install, dev, test, build) e indique pré-requisitos
• Mantenha mudanças em um único PR e liste exatamente quais arquivos serão criados ou editados
• Pare após scaffolding e diga como rodar

Aqui está um prompt que você pode reutilizar e ajustar:

You are working in an empty repo. Create a minimal runnable skeleton.

Constraints:
- Keep it small: no real features yet.
- Propose a clear folder structure and add brief comments in each folder’s README.
- Add scripts for: setup, dev, test, build. They must work on a fresh machine.
- Tell me exactly how to run it, and what output I should see.
- After generating, stop and wait for my “ran it” confirmation.

Output:
1) File tree
2) Key files (only)
3) Run instructions

Depois mantenha o loop curto. Não peça cinco mudanças ao mesmo tempo. Gere uma pequena alteração, rode, cole o erro exato (ou sucesso), e então peça um ajuste mínimo. Esse ritmo gerar-executar-ajustar mantém o projeto previsível e dificulta que a estrutura derive.

Passo a passo: do repositório vazio a um esqueleto executável

Comece com uma promessa: qualquer pessoa pode clonar o repositório e executar um comando para ver algo funcionando. Isso te dá uma base estável antes de pedir a uma IA para adicionar features reais.

Crie o repo e escreva um README minúsculo enquanto tudo ainda está fresco. Mantenha prático: pré-requisitos, o único comando de dev e como rodar testes (mesmo que os testes estejam vazios por enquanto).

Em seguida, escolha um layout de nível superior que combine com a forma do app que você escolheu.

Se estiver construindo múltiplas peças deployáveis (por exemplo, frontend + API), um layout tipo workspace pode ajudar:

/
  apps/
  packages/
  scripts/
  docs/
  README.md

Se estiver construindo um único app, mantenha mais simples e evite níveis extras até precisar deles.

Agora adicione os guardrails mínimos para que o código fique consistente. Escolha um formatador e um linter, aceite padrões, e adicione um único arquivo de configuração para cada um. O objetivo é diffs limpos, não regras perfeitas no dia um.

Torne a experiência do desenvolvedor previsível com um comando que sempre funcione a partir da raiz do repositório. Aqui está uma forma simples:

{
  "scripts": {
    "dev": "echo \"start dev server here\"",
    "build": "echo \"build here\"",
    "test": "echo \"tests here\"",
    "lint": "echo \"lint here\""
  }
}

Antes de gerar qualquer outra coisa, rode esse comando dev, confirme que ele sai limpo (ou inicia um servidor placeholder), e então faça seu primeiro commit apenas com o scaffolding. Se um colega (ou você no futuro) conseguir reproduzir a configuração do zero, você está pronto para construir a primeira fatia.

Uma estrutura de pastas que você pode manter conforme o app cresce

Uma boa estrutura greenfield faz duas coisas: ajuda a encontrar código rapidamente e dá menos espaço para o Claude inventar novos padrões cada vez que você pede uma mudança. O objetivo não é perfeição. É estabilidade.

Se você estiver trabalhando dentro de um app único (ou dentro de uma pasta apps/<name>/), um layout interno simples costuma se manter bem:

• src/ código do app (features, partes compartilhadas, pontos de entrada)
• config/ configuração não secreta
• tests/ testes de nível mais alto que leem como comportamento do usuário
• scripts/ scripts auxiliares (setup dev, reset db, tarefas de release)
• docs/ notas curtas e checklists que você realmente mantém

Dentro de src/, separe código de feature de código compartilhado baseado em padrões de alteração. Código de feature muda com frequência e deve ficar junto. Código compartilhado deve ser estável e reutilizável.

Uma regra prática: coloque telas de UI, handlers e lógica específica da feature em src/features/<featureName>/.... Coloque coisas como logging, clientes de API, componentes do design system e utilitários genéricos em src/shared/.... Se um helper só faz sentido para uma feature, mantenha-o naquela feature mesmo que pareça reutilizável. Mova quando houver um segundo uso real.

Nomes de pastas devem descrever propósito, não tecnologia. “features” e “shared” continuam significativos se sua stack mudar. Evite nomes como “misc” ou “new”.

Mantenha docs/ pequeno. Um começo bom é docs/checklists.md com algumas linhas: como rodar, como testar, como adicionar uma nova pasta de feature e o que significa “feito”.

Scripts de build que tornam o projeto previsível

Um repositório parece real quando qualquer pessoa pode executar os mesmos comandos e obter o mesmo resultado. Scripts são guardrails: reduzem adivinhação, mantêm mudanças pequenas e deixam claro quando algo quebrou.

Comece com um pequeno conjunto de comandos e mantenha-os simples. Se alguém novo entrar (ou você voltar em duas semanas), não deve precisar de flags especiais ou passos ocultos.

Aqui está uma linha base simples que você pode adaptar a qualquer stack:

{
  "scripts": {
    "dev": "node ./scripts/dev.js",
    "build": "node ./scripts/build.js",
    "test": "node ./scripts/test.js",
    "test:quick": "node ./scripts/test.js --quick",
    "test:full": "node ./scripts/test.js --full",
    "format": "node ./scripts/format.js",
    "lint": "node ./scripts/lint.js",
    "smoke": "node ./scripts/smoke.js"
  }
}

Faça do script dev o caminho feliz. Ele deve iniciar o app, imprimir onde está rodando e manter logs legíveis. Se o servidor não puder iniciar, falhe rápido com uma mensagem clara (variável de ambiente faltando, porta em uso, banco inacessível).

O script de build deve sempre criar um diretório de saída limpo. Delete o output antigo primeiro e então produza artefatos frescos. Isso evita bugs estranhos causados por arquivos de ontem.

Para testes, separe checagens rápidas das lentas. Testes rápidos rodam a cada alteração (unit tests, checagens de tipos). Testes completos incluem integração e rodam antes do merge.

Mantenha estilo consistente com um comando. Uma regra simples: format corrige, lint reclama.

Finalmente, adicione um smoke check que valide o básico antes de perder tempo depurando:

• Variáveis de ambiente obrigatórias estão setadas (e não vazias)
• Portas escolhidas estão livres
• App consegue iniciar e responder a uma requisição simples
• Conexão com o banco funciona (se usado)
• Output de build existe depois do build

Construa a primeira fatia vertical

Sua primeira fatia vertical deve provar que o app funciona ponta a ponta, não só que a UI parece bonita. Isso significa um pequeno recurso que toque a tela, a lógica e algum tipo de armazenamento, mesmo que temporário.

Escolha algo sem graça e útil, tipo “Adicionar uma nota” ou “Criar uma tarefa”. Mantenha pequeno o suficiente para terminar em uma sessão, mas completo o suficiente para clicar e ver mudança de estado real.

Uma boa fatia tem quatro partes: uma rota ou tela, um formulário, uma ação de salvar e uma exibição. Exemplo: uma página “Nova Tarefa” com input de título, botão Salvar que chama uma função, e uma lista que mostra tarefas salvas.

Comece com um store placeholder para ir rápido. Um array em memória, um arquivo JSON local ou uma interface stub é aceitável. O importante é criar a fronteira que você trocará depois. Se seu código chamar taskRepository.save(task) hoje, trocar por um banco real depois vira uma pequena alteração, não uma reescrita.

Mantenha a UI simples. Pule debates de design system, estados vazios e animações.

Checagens de aceitação que você pode fazer em dois minutos:

• A página abre sem erros
• Você digita um valor e aperta Salvar
• O novo item aparece imediatamente
• Recarregar mostra o comportamento esperado (persistência real ou reset se for fake)
• Entrada inválida é tratada (título vazio mostra mensagem e não salva)

Torne estável o suficiente para iterar

Depois de ter um esqueleto executável e uma fatia vertical, o objetivo muda: deixe a quebra óbvia e o conserto rápido. É aqui que muitos starts greenfield desandam, não porque a feature seja difícil, mas porque pequenas mudanças começam a causar surpresas.

Defina uma barra de estabilidade pequena que você atenda toda vez que adicionar uma fatia:

• Um teste smoke que prove que o app sobe e a rota/tela principal renderiza
• Um teste smoke que atinja a fatia ponta a ponta (mesmo que use um banco de testes)
• Mensagens de erro claras que um usuário normal entenda (não stack traces)
• Logs de dev que expliquem o que aconteceu sem vazar segredos
• Dependências mínimas, versões fixas, upgrades feitos de propósito

Exemplo concreto: sua primeira fatia deixa o usuário criar um “Projeto” e vê-lo na lista. Adicione um teste que inicia o servidor, chama o endpoint de criação e depois busca a lista checando que o novo item aparece. Se falhar, que falhe alto com uma mensagem útil, tipo “Create Project endpoint returned 500”, não um monte de saída sem contexto.

Para tratamento de erro, mantenha um pequeno conjunto de respostas consistentes. Erros de validação retornam uma mensagem curta (“Nome é obrigatório”) e o campo. Erros inesperados retornam “Algo deu errado. Tente novamente.” Guarde detalhes para os logs.

Logging é mais útil quando responde: qual requisição, qual usuário (ou anônimo), o que falhou e onde. Em dev, inclua id de requisição e tempo, mas evite despejar tokens, senhas, chaves de API ou payloads completos por padrão.

Adicione uma checagem de saúde pequena. Na web, pode ser um endpoint /health que retorna ok. No mobile, pode ser um estado “Conectado” que vira “Offline” quando o app não alcança o backend. É um sinal rápido antes de debugar a coisa errada.

Armadilhas comuns ao usar IA para projetos greenfield

A maneira mais rápida de desperdiçar um início greenfield é pedir ao modelo o app inteiro e só rodá-lo depois. Gerações grandes escondem erros pequenos: dependências faltando, caminhos de import errados, scripts que assumem ferramentas que você não tem. Trate cada output como algo que você deve conseguir rodar em minutos.

Outra armadilha é desenhar a arquitetura perfeita antes de existir uma feature. Debater nomes de pastas parece produtivo, mas sem uma fatia real você não sabe o que é incômodo. Uma estrutura simples que suporte um caminho funcionando vence uma estrutura inteligente que você não testou.

A deriva de comandos também é comum. A IA adiciona uma nova forma de iniciar o servidor, você adiciona outra para testes e logo ninguém sabe qual é “o” comando. Se um colega clona o repo e pergunta “Como eu rodo isto?”, você já está pagando juros.

Erros que causam mais retrabalho:

• Gerar múltiplos serviços, telas e configs de uma vez em vez de construir um caminho executável primeiro
• Puxar auth, pagamentos, estilização complexa e um modelo de dados completo antes da primeira feature ponta a ponta
• Deixar instruções de setup no chat em vez de scripts (ou um README único)
• Esquecer um template limpo de env, então a próxima máquina não inicia sem adivinhação

Um exemplo simples: você gera um app “completo” com login, theming e billing, mas a primeira execução falha porque uma chave secreta falta e não há .env.example. Você então passa uma hora corrigindo setup em vez de aprender se a feature é útil.

Seja honesto: um comando executável, uma feature pequena, um template de env, então expanda.

Checklist rápido antes de começar a iterar

Antes de adicionar “mais uma feature”, confirme que o projeto é fácil de retomar amanhã (ou por outra pessoa). Velocidade não é o objetivo por si; previsibilidade é.

• Um comando: um novo dev pode copiar um template de env, setar os poucos valores necessários e iniciar o app com um comando. Se precisar de passos extras (setup de DB, migrations, seed), capture-os em um script.
• Scripts cobrem o básico: comandos claros para dev, test, build e um smoke check rápido.
• Estrutura óbvia: o layout conta uma história (código do app, config, scripts, tests) sem ler todo o codebase.
• Caminho de demo da fatia: você consegue descrever a demo em uma frase, tipo “criar um item, ver na lista, atualizar, ele continua lá.”
• Ponto de rollback: antes de mudanças grandes, tenha um ponto seguro para voltar (commit limpo, tag ou snapshot/rollback).

Se algum item falhar, corrija agora. Apertar scripts e nomenclatura é barato quando o repo é pequeno.

Próximos passos: transforme o fluxo em hábito repetível

Um início greenfield só vale se você conseguir repeti-lo. Depois que sua primeira fatia vertical roda ponta a ponta, congele as partes boas em um pequeno template: os mesmos padrões de pasta, os mesmos nomes de scripts e a mesma forma de conectar UI, API e dados.

Trate sua primeira fatia como implementação de referência. Ao começar a fatia #2, copie a forma, não o código. Se a fatia #1 tem rota, handler, camada de acesso a dados e um teste básico, a fatia #2 deve seguir o mesmo caminho.

Mantenha o planejamento leve. Uma página de notas é suficiente para as próximas 2–3 fatias: objetivo e ação do usuário para cada fatia (uma frase), os dados necessários, os checks de “feito” e riscos a testar cedo.

Depois torne manutenção um hábito. Uma vez por semana, faça uma passada rápida de limpeza: aperte scripts, atualize o README com novos passos de setup e atualize o env example para manter o onboarding fácil.

Se preferir um loop de build orientado por chat, Koder.ai (koder.ai) é uma opção que suporta modo de planejamento, snapshots e rollback, e pode exportar o código-fonte quando quiser levar o projeto para outro lugar.

O objetivo é um fluxo que você execute sem pensar: planeje 2–3 fatias, construa uma fatia, estabilize, repita.