Seis decisões antes do seu primeiro prompt, e por que cada uma está ali

Ninguém quer gastar uma tarde com setup. O impulso é abrir um chat e começar a descrever a coisa, e para um protótipo esse é o instinto certo — a primeira semana tem um post próprio e quase todo conselho de lá é vá mais rápido.

Este é o outro post. Ele é para o momento em que você decide que a coisa ainda vai existir mês que vem, e são seis decisões. Cada uma leva minutos. Cada uma fecha um jeito específico de a segunda semana dar errado, e a razão para tomá-las juntas é que as seis são baratas agora e caras depois.

Nenhuma delas é sobre qual modelo é o melhor.

1. GitHub, que é um botão de desfazer com quem você conversa

Se você nunca usou, ignore como costumam descrever. GitHub não é uma rede social para programadores e você não está lá para ler o código de ninguém. É um sistema de save com histórico, hospedado em algum lugar que não é o seu notebook.

Cinco palavras cobrem quase tudo que você precisa:

• Repositório — a pasta do seu projeto, mais todas as versões que ela já teve.
• Commit — um ponto de save com um bilhete junto. “Tela de login funciona” é um commit.
• Branch — uma cópia do projeto onde você pode quebrar coisas sem quebrar o original.
• Push / pull — sincronizar entre a cópia da sua máquina e a cópia no GitHub.
• Pull request — “aqui está uma mudança, olhe antes de ela entrar”. Sozinho você não vai precisar disso; vai precisar no dia em que outra pessoa tocar no projeto.

E aqui está por que quem faz vibe coding se importa especificamente. Em algum momento — não “talvez” — uma sessão vai reescrever algo que já funcionava. Vai refatorar um arquivo de que você gostava, ou apagar uma função que ela decidiu que não era usada, ou consertar um bug introduzindo dois. Sem commits, esse trabalho se foi e a sua única recuperação é descrever tudo de novo de memória. Com commits, a recuperação é uma frase.

O que traz a parte que ninguém conta para iniciantes: você não precisa aprender Git. Você precisa aprender três frases para dizer ao seu agente.

• Faça commit disso com uma mensagem clara.
• O que mudou desde o último commit?
• Desfaça tudo desde o último commit.

Essa é a interface inteira no primeiro mês. O agente roda os comandos.

Configure assim e pare de pensar nisso: crie a conta, deixe o repositório privado por padrão, e antes de qualquer coisa garanta que .env está no .gitignore. Aquela única linha é o que impede as suas chaves de API de serem publicadas na primeira vez que você fizer push. Chaves vazam de repositórios de iniciantes o tempo todo, e são varridas em minutos.

Depois um hábito, que é a coisa de maior retorno deste post inteiro: quando algo funcionar, faça commit. Não no fim do dia. No momento em que funciona.

Isso basta para começar. O resto — ler um diff sem ler código, os quatro tipos diferentes de desfazer e quando cada um se aplica, o que fazer no dia em que você commitar uma chave de API — está no guia completo.

2. Um modelo, e isso importa menos do que você pensa

Claude Code, Codex, ou um modelo de pesos abertos que você mesmo roda. O enquadramento honesto: essa é a decisão que você pode reverter de graça. O repositório é portátil, os seus prompts são portáteis, e nada do que você constrói fica preso à ferramenta que escreveu.

O que de fato separa essas opções não são notas de benchmark, é se a ferramenta mora dentro do seu projeto:

A recomendação: escolha uma ferramenta agêntica paga e fique nela por um mês. Não porque as outras sejam piores, mas porque a habilidade que você está construindo é saber o que pedir e como perceber que a resposta está errada, e essa habilidade transfere devagar enquanto você ainda troca de ferramenta toda semana.

Sobre open source, sendo direto: é real, é mais barato, é privado, e é o primeiro passo errado. Você vai gastar a primeira semana com setup em vez de com a coisa que queria construir, e trabalhos agênticos longos — muitos arquivos, muitos passos, segurar o plano o caminho todo — são exatamente onde a distância ainda é maior. Volte a isso no mês dois, quando você souber o que está comparando.

E seja qual for a escolha, a alavanca não está no modelo. Está no que o modelo consegue ver sobre o seu projeto, que são as decisões 4, 5 e 6.

3. Um host, e uma conta só se você conseguir

Você vai precisar de algum lugar para colocar. As duas respostas óbvias são Cloudflare e Vercel, e a pergunta que decide não é desempenho.

É quantas contas você quer segurar.

Cloudflare é o tudo-em-um: hospedagem, um banco de dados (D1), armazenamento de arquivos (R2), chave-valor, o próprio domínio, DNS, roteamento de e-mail — um login, uma fatura, um lugar onde as coisas estão erradas quando estão erradas. Para quem está começando, essa consolidação vale mais do que qualquer recurso individual. O preço é um runtime que não é exatamente Node, então um punhado de pacotes do npm não vai rodar lá, e você descobre no deploy e não na instalação.

Vercel te dá o deploy mais suave que existe se você está em Next.js. A troca é que as peças de dados vêm de parceiros do marketplace, então o banco de dados é o painel de outra pessoa, o armazenamento é mais outro, e você vai acabar reconectando três serviços num domingo à noite tentando lembrar qual deles tem a credencial que falhou.

Escolha Cloudflare a menos que você tenha um motivo específico para estar em Next.js.

E compre o domínio no primeiro dia, do mesmo provedor. Custa uns dez euros, leva quatro minutos, e muda como você trata o projeto. Uma coisa com domínio é uma coisa que existe.

4. Uma stack — escolhida por você, e por escrito

A tentação é deixar isso para o modelo. Não deixe, e o motivo não é que a escolha dele seria ruim.

É que o modelo escolhe por conversa. A sessão de segunda escolhe Next.js. A de quarta, sem memória da segunda, escolhe Vite e React Router. A de sexta adiciona uma biblioteca de componentes que duplica a que você já tem. Nada dá erro quando isso acontece — você simplesmente termina com um projeto que são três projetos usando um sobretudo, e cada sessão futura precisa adivinhar em qual convenção está.

Então: React + Tailwind, e diga ao modelo para usar shadcn/ui.

Por que essa combinação específica, se existem várias outras perfeitamente boas:

• É a combinação mais bem documentada nos dados de treino de qualquer modelo. Você está escolhendo a região do mapa onde o modelo é mais preciso e menos inventivo, e isso vale mais do que qualquer vantagem técnica no primeiro dia.
• O Tailwind mantém o estilo na marcação, então quando você diz “deixe esse card mais compacto”, o agente muda uma linha no arquivo que você está olhando em vez de caçar uma folha de estilo.
• Os componentes do shadcn são copiados para o seu repositório, não instalados como dependência. Essa é a parte subestimada. Quando você pede uma mudança num botão, o agente edita o seu botão. Com uma biblioteca de componentes tradicional, ele tem que brigar com a API da biblioteca, e normalmente perde envolvendo tudo em três camadas de bobagem.

Uma exceção, e é comum. Se o que você constrói é quase todo conteúdo — um site, uma landing page, um blog, um conjunto de documentação, com uma pequena área administrativa junto — use Astro no lugar. Ele envia quase nenhum JavaScript por padrão, as páginas ficam rápidas sem você fazer nada, e escala até virar uma aplicação de verdade quando você precisar. Este site é Astro.

Skills: como você para de se repetir

Uma skill é uma pasta com um arquivo SKILL.md dentro que o seu agente lê só quando é relevante. Essa última parte é o ponto inteiro: são instruções disponíveis sem estar no caminho.

A anatomia é pequena. Um arquivo em .claude/skills/<nome>/SKILL.md, começando com:

---
name: my-design-system
description: Use ao construir ou reestilizar qualquer UI deste projeto —
  cores, tipografia, espaçamento, padrões de componentes.
---

Tudo o que o agente deveria saber, em markdown comum.

A linha description é a importante, porque é contra ela que o agente compara para decidir se carrega a skill. Descrição vaga, skill que nunca dispara.

Dois lugares para colocá-las: .claude/skills/ dentro do seu projeto, o que significa que vai commitada no GitHub e continua lá amanhã e na sua outra máquina, ou ~/.claude/skills/, para coisas que você quer em todo projeto que tocar. Prefira a do projeto — uma skill que descreve este produto pertence a este produto.

Para instalar uma que alguém te deu: solte a pasta lá, abra uma sessão nova, e pergunte quais skills você tem disponíveis. Se não listar, a descrição é a primeira coisa a checar.

Esse é o formato. Por que a descrição é a única parte que sempre carrega, o que vai numa skill contra o que vai no AGENTS.md, e o jeito mais rápido de escrever a sua primeira — o guia completo.

(Skills são um recurso do Claude Code. Se você foi de Codex, a alavanca equivalente é o arquivo AGENTS.md descrito na seção extra — mesma ideia, com carregamento menos seletivo.)

A de design vale a pena no primeiro dia. Se você tem uma ideia mas nenhuma marca, nenhuma cor e nenhuma opinião visual ainda, vá em startpow.com, escolha o que você gostar, exporte, e escolha o download de skill. Solte em .claude/skills/. A partir desse momento toda tela que o agente construir chega nas suas cores, com a sua tipografia e o seu espaçamento, sem você descrever de novo — o que é a diferença entre um produto e uma demo, e custa uns dez minutos.

5. Algo que lembre, para amanhã não ser uma reconstrução

Esta é a falha de que essa decisão trata, e vale a pena ser preciso porque a versão popular está errada.

O modelo não é malicioso. Ele é prestativo e rápido, em lugares onde errar sai caro. O banco de dados não é derrubado por uma IA rebelde; ele é derrubado porque uma migração estava quebrada, derrubar a tabela era o caminho mais curto para um teste passando, e ninguém foi consultado. O auth não é reescrito num ato de sabotagem; ele é reescrito porque um teste estava falhando e a checagem de auth era o que fazia falhar.

Duas camadas de defesa, e a primeira é de graça:

Os hábitos. Um banco de desenvolvimento que não é o banco de produção. Credenciais de produção que o agente nunca segura. Um commit antes de começar qualquer coisa. E a instrução que quase ninguém dá — o que ele não pode tocar. Modelos são prestativos; vão fazer com prazer uma coisa útil que você não queria.

As ferramentas. É isso que o CommitCycle é: o trabalho começa como uma task com um escopo declarado, o agente ganha acesso preso àquela única task e a um único branch e isso expira sozinho, os paths que de fato doeriam carregam um owner que precisa dizer sim, e cada task fecha com um registro do que foi declarado contra o que foi tocado.

Agora o limite honesto, que é também a frase mais importante daqui: isso não remove a possibilidade. A responsabilidade final é sempre da pessoa que aprova o que o agente pede. O agente executa; você consente. O que a ferramenta remove é a classe de acidente em que ninguém podia dizer não, porque ninguém foi consultado — e essa classe é a maioria deles.

Se você quiser: /plugin install commitcycle@commitcycle no Claude Code, ou npm i -g commitcycle para a CLI. O board hospedado é só por convite enquanto isso é pequeno.

6. E agora? Comece pelo formato, não pela tela

Você tem as seis peças. O instinto é mandar construa a home para mim, e é o primeiro passo errado — não porque a home não importe, mas porque ela é consequência de decisões que você ainda não tomou.

A primeira pergunta útil é: isso precisa de contas? Quase tudo se organiza em quatro superfícies a partir daí.

Se a resposta honesta for “quase toda parte pública, admin pequeno”, construa em Astro e não adicione um sistema de autenticação que você vai manter para um usuário só. Se for “quase todo produto”, o auth e o modelo de dados são a primeira coisa, porque todo o resto pendura neles.

Os prompts

Primeiro, o que não escreve código. Esse é o prompt de maior valor do processo inteiro e é o que a maioria pula:

Quero construir: [descreva em três ou quatro frases, incluindo para
quem é e pelo que pagam, se pagam algo].

Não escreva código ainda. Me entreviste — me faça as perguntas que
você precisa que eu responda para planejar isso direito, em lotes.

Quando tiver o suficiente, me devolva:
1. As telas, agrupadas em público / auth / produto / admin
2. O modelo de dados, como lista de entidades e como se relacionam
3. Qualquer serviço de terceiros que isso precise e por quê
4. O que você construiria primeiro, e o que deixaria
   deliberadamente para depois

Você está fazendo o modelo produzir uma pergunta, e revisar uma pergunta é muito mais barato do que revisar trezentas linhas de uma resposta construída sobre uma suposição que você nunca viu.

Segundo, a fundação. Faça o deploy da coisa vazia no primeiro dia — “colocar no ar” nunca deveria virar um projeto próprio mais tarde:

Monte o esqueleto do projeto:
- [Astro | React + Vite], TypeScript, Tailwind, shadcn/ui
- Destino de deploy: Cloudflare
- Um repositório Git com um primeiro commit, enviado ao GitHub

Deixe uma página vazia com deploy feito e me dê a URL no ar antes de
adicionar qualquer funcionalidade.

Depois escreva AGENTS.md na raiz registrando: a stack e as versões, a
estrutura de pastas, as convenções de nomes, os comandos para rodar e
buildar, e qualquer coisa que você nunca deve fazer neste projeto.

Não adicione autenticação, banco de dados nem nenhuma dependência
além do acima ainda.

Terceiro, as superfícies que precisam de um sistema atrás:

Construa cadastro e login: criar conta, entrar, sair, recuperação de
senha, verificação de e-mail.

Use [o provedor de auth que você escolheu] em vez de fazer na mão.
As telas usam nossos componentes existentes — não introduza uma
segunda biblioteca de componentes.

Me dê também a menor página de admin que liste usuários, porque eu
preciso conseguir ver se isso funciona.

NÃO toque: pagamentos, as páginas de marketing, nada abaixo de [path].
Se você esbarrar numa decisão que eu não tomei — preços, duração da
sessão, o que acontece com contas não verificadas depois de uma
semana — pare e pergunte em vez de escolher.

Repare nas duas linhas que quase ninguém escreve: o que ele não pode tocar, e pare e pergunte em vez de escolher. Essas duas linhas evitam mais retrabalho do que qualquer quantidade de refinamento em prompt engineering.

Quarto, quando funcionar, deixe com a sua cara: instale a skill de design e peça para reestilizar uma tela com ela. Confira essa. Depois deixe rodar no resto.

7. Histórias de usuário, que é onde isso fica real

Se você consegue narrar o que uma pessoa faz, você consegue construir. Pegue a frase do próprio usuário:

Alguém vê um anúncio, cai no site, cria uma conta, assina um plano, paga com cartão, e a assinatura dele libera o acesso.

Leia de novo devagar, porque essa frase única é uma especificação. Ela contém:

• Uma landing page para onde o anúncio aponta, que não é a home
• Cadastro, e portanto verificação, e portanto e-mail que chega de verdade
• Provavelmente onboarding, porque uma conta nova e vazia é onde as pessoas vão embora
• Um provedor de pagamento — Stripe, na prática — e um checkout
• Um webhook, porque o pagamento dá certo nos servidores da Stripe e o seu app tem que descobrir
• Entitlement: algum estado que diga que essa conta agora é assinante
• Feature gating guiado por esse estado, em todo lugar onde importa
• O caminho de falha: cartão recusado, pagamento que deu certo mas webhook que não chegou, assinatura cancelada no meio do mês
• Uma visão de admin, para que quando alguém te escrever dizendo que pagou e nada liberou, você consiga olhar

Uma frase, nove itens de trabalho, e os três últimos são os que são descobertos em produção, por um cliente, se ninguém escreveu.

Isso também é trabalho que o modelo faz bem — entregue a história e pergunte o que ela implica, e ele vai produzir uma lista muito parecida com a de cima. O que ele não consegue é lembrar da lista na terça que vem. É para isso que serve um board: cada item vira uma task com um escopo, uma task vira um branch, e o branch fecha com um registro do que realmente mudou.

Isso soa chato. É, um pouco. E no interesse de não vender demais: três prompts realmente conseguem te dar algo que roda e parece bom, e a emoção de ver funcionando é real e vale a pena ter. Vá lá e tenha.

Mas a coisa que ainda está de pé no mês três, que você consegue entregar para outra pessoa, que você consegue mudar sem prender a respiração — essa foi construída por alguém que escreveu o que ela deveria fazer. Consistência é sem glamour e é a diferença inteira.

Faixa bônus

Coisas pequenas, na ordem aproximada de quanto arrependimento elas evitam:

• AGENTS.md na raiz do repositório. O arquivo de maior retorno que você vai escrever. Stack, convenções, comandos, e a lista de coisas para nunca fazer. Toda ferramenta agêntica lê. O nosso gera um por task e limpa na entrega, mas um escrito à mão já é a maior parte do valor.
• Dois bancos de dados desde o primeiro minuto. Desenvolvimento e produção, nunca as mesmas credenciais, e o agente só segura o de desenvolvimento. Essa é a defesa específica contra o desastre específico.
• Segredos nunca no repositório. .env no .gitignore, valores reais no cofre de segredos do seu host. Rotacione qualquer coisa que chegou a ser commitada — apagar o arquivo não remove do histórico.
• Deploys de preview por branch. Tanto Cloudflare quanto Vercel te dão uma URL por branch de graça. Ver a mudança numa URL real antes de ir ao ar vale mais do que qualquer quantidade de teste local.
• Deixe o agente ver o que ele construiu. Capturas de tela, ou uma ferramenta de navegador que ele possa dirigir. Um agente construindo UI sem nunca olhar está trabalhando às cegas, e dá para perceber.
• Rastreamento de erros, mais exatamente um número de analytics que você olha de verdade. Mais do que um e você não vai olhar nenhum.
• Termos e política de privacidade antes de cobrar um cartão. A Stripe vai pedir um site funcionando com os dois antes de ativar a conta, e descobrir isso no dia do lançamento é um dia ruim.
• Conheça a sua restauração, não só o seu backup. Um backup não testado é uma crença, não um backup.
• Um arquivo de decisões. Três linhas por decisão: o quê, por quê, o que você rejeitou. Seis semanas depois é a única coisa entre você e relitigar tudo com um modelo que não estava lá.
• Espere o modelo custar mais do que a hospedagem. Essa proporção está certa e não é sinal de que você está fazendo errado.

O setup inteiro acima é uma tarde. O que ele compra é que a segunda semana seja uma continuação em vez de um projeto de arqueologia — e se você quer os hábitos que vão em cima disso, esse é o post da primeira semana.