david-samurai/LandingPageSkill

Construindo uma landing page no Claude Code

Uma configuração funcional para construir, enviar e melhorar páginas de marketing com o Claude Code. Cinco coisas fazem a maior parte do trabalho: um repositório, um host, um kit de marca, desempenho e dados de funil. Acertar esses pontos torna todo o resto uma questão de iteração.

Duas maneiras de ver a página antes de enviá-la (seção 4): um servidor de desenvolvimento local para você e o Claude, e o Claude Design para qualquer pessoa não técnica. Se você usar o Design, leia a regra rígida da seção 4 primeiro — não há como desfazer lá.

A linha condutora: o trabalho não termina na implantação. Uma página que está ativa e não rastreada é uma página que você não pode melhorar.

Ordem de operações

Faça na seguinte ordem. Cada uma torna a próxima mais fácil.

1. Repositório primeiro — antes de qualquer código. Controle de versão é o botão de desfazer para todo o resto.
2. Hospedagem + pipeline de implantação em segundo — enquanto o site é trivial e uma implantação quebrada não custa nada.
3. Kit de marca em terceiro — antes de escrever uma palavra de texto, para que o primeiro rascunho já esteja alinhado com a marca.
4. Construir a página — visual/estático primeiro, interatividade depois, rastreamento por último.
5. Enviar com rastreamento mínimo no primeiro dia — depois otimize velocidade e texto com base em dados reais.

---

1. Use um repositório (GitHub ou equivalente)

Se você já usa o Claude Code, isso é óbvio. Se você está apenas começando, este é o aquecimento: um repositório fornece controle de versão, um backup na nuvem e — mais importante — uma estratégia de implantação.

main é produção e nada chega lá exceto por meio de um pull request que você mescla. Coloque essa regra em CLAUDE.md explicitamente — veja starters/CLAUDE.md.

O ciclo

Este é o ciclo completo. Execute-o para cada pedaço de trabalho, por menor que seja.

1. Combine um número de versão. Claude recomenda um, você concorda — ou você apenas diz qual deseja. De qualquer forma, o número é definido antes de qualquer trabalho começar, e a decisão é sua, não do Claude.
2. Claude cria o branch — git checkout -b v1.03.
3. Você faz o trabalho no branch. Os commits ficam lá e em nenhum outro lugar.
4. Claude envia o branch para o GitHub.
5. Claude abre o pull request.
6. Você revisa e aprova no GitHub, e faz o merge. Esta é a implantação. É o único momento em que a produção muda, e é sempre uma decisão humana.
7. git checkout main e depois git pull. Não pule isso. Seu main local está agora atrasado por exatamente uma mesclagem, e iniciar o próximo branch a partir de um main desatualizado é como você obtém divergência, conflitos fantasmas e um git pull que se recusa a fazer fast-forward.
8. Repita a partir do passo 1 com o próximo número de versão.

Claude propõe, você decide, Claude executa. Números de versão, merges e implantações são seus; branching, push e abertura do PR são do Claude. Se uma chamada for ambígua, Claude pergunta.

Nomenclatura de versão que funciona: v1.0x para patches (texto, configuração, pequenas correções), v1.x para trabalho menor (uma nova página, um novo recurso), v2.x para um redesign.

Duas portas de revisão que valem a pena manter:

• Revise todo o diff do branch antes de fazer o merge, não apenas cada commit. Commits individualmente bons podem se combinar em um bug real. Uma passada completa "leia tudo desde o ponto de ramificação" — idealmente por um segundo revisor ou um agente fresco — captura o que a revisão por tarefa estruturalmente não consegue.
• Execute uma revisão de segurança antes de qualquer implantação que colete dados do usuário. Uma passada de revisão em um branch de manipulação de formulários capturou uma vulnerabilidade real onde um spread de objeto bruto permitia que um visitante enviasse valores para campos gerenciados pelo servidor. Trate isso como uma porta, não como um detalhe.

---

2. Hospede em algum lugar com um pipeline de implantação real

O AWS Amplify funciona bem: um nível gratuito que cobre uma landing page de baixo tráfego e uma pequena fatura além disso. Verifique os termos atuais — a AWS reestruturou seu nível gratuito em 2025. Netlify, Vercel e Cloudflare Pages oferecem a mesma estrutura.

A verdadeira vantagem é o caminho de implantação: mescle um PR, o site é reconstruído e fica ativo.

Conectar o repositório ao host é a etapa em que as pessoas param, e é um caminho de cliques, não um arquivo de configuração: no console do host, crie um novo aplicativo web → autorize-o contra sua conta do GitHub → escolha o repositório e o branch main → ele detecta sua especificação de build → a primeira implantação é executada. A partir daí, ele reconstrói a cada push para esse branch. Faça isso enquanto o site é uma única página "olá", para que um pipeline quebrado não lhe custe nada para depurar.

Configure no primeiro dia, enquanto é barato:

• Implantação automática a partir de main.
• Um domínio personalizado com HTTPS.
• Um alarme de cobrança. Você acabou de colocar um cartão contra uma conta na nuvem. Defina um alerta de orçamento em um número que o surpreenderia — leva dois minutos, e converte uma surpresa desagradável de baixa probabilidade em um e-mail.
• Cabeçalhos de segurança — hosts estáticos vêm com nenhum por padrão.
• Cache-Control de cache longo em ativos de build com hash de conteúdo. Fácil, permanente, e, caso contrário, adia para sempre porque nunca bloqueia nada.

Domínio e DNS, onde as armadilhas são previsíveis:

• Um domínio nu não pode usar um CNAME — www.exemplo.com pode, exemplo.com não pode. Você precisa do registro ALIAS/ANAME do seu provedor de DNS ou da opção apex do próprio host. Decida cedo se sua URL canônica tem o www e redirecione a outra para ela.
• O certificado HTTPS precisa de um registro DNS para validar e não será emitido até que esse registro seja resolvido. Dê a qualquer alteração de DNS algumas horas antes de decidir que está errada — o atraso de propagação parece exatamente uma falha.

Armadilhas de implantação que custam tempo real:

• Saiba exatamente quais partes são implantadas automaticamente e quais não são. Se qualquer peça de sua pilha (uma função serverless, um backend, um worker) for implantada por um comando manual separado, escreva isso em CLAUDE.md em letras maiúsculas. A falha silenciosa clássica é mesclar um branch onde o site visível é atualizado, o backend não, e tudo parece bem.
• A implantação automática remove seu último ponto de verificação. Com merge-para-implantação, a revisão do PR é a porta. A verificação tem que acontecer antes do merge, não depois.
• npm ci no host de build é mais rigoroso que seu npm install local. Um arquivo de bloqueio sutilmente fora de sincronia com package.json instala bem localmente em um npm mais recente e falha no build no host mais antigo. O build falha no host, mas não localmente? Suspeite do arquivo de bloqueio primeiro.
• Fixe seu runtime na especificação de build, não apenas em um arquivo de versão. Um .nvmrc sozinho não é respeitado de forma confiável — invoque o gerenciador de versão nos comandos de build também.
• Cada nova variável de ambiente precisa ser adicionada no console do host, separadamente do código que a lê. Esta é uma resposta surpreendentemente frequente para "por que está quebrado?".
• Content-Security-Policy é o cabeçalho que vai te morder. Cada origem de terceiros com a qual sua página realmente se comunica — análises, gerenciador de tags, pixels, fontes, endpoints de formulário — deve estar na lista de permissões, na diretiva correta, ou será silenciosamente bloqueada em produção enquanto funciona perfeitamente no desenvolvimento local. Sintoma: "o rastreamento funciona localmente, não dispara nada ao vivo." Verifique o console do navegador em busca de violações de CSP antes de depurar qualquer outra coisa.
• Verifique contra o artefato implantado, não o arquivo fonte. Confirme uma correção inspecionando a resposta real de produção (curl -I, ferramentas de desenvolvedor do navegador), não lendo a configuração que deveria produzi-la. O mesmo para "minha alteração realmente foi implantada?" — verifique o ID/timestamp do build, não apenas que o merge aconteceu.

Como o formulário realmente envia

A hospedagem estática não tem backend. Um <form> simples em uma página estática não faz nada útil — isso surpreende as pessoas no primeiro dia, e é o objetivo principal da página. Três opções realistas:

Opção	Bom quando	Cuidado com
Um serviço de formulário hospedado	Você quer que funcione ainda esta tarde	Custo mensal por volume; a marca deles; seus dados residem com eles
Uma função serverless (Lambda, Netlify/Cloudflare Functions)	Você quer controle e custo quase zero	Você agora lida com validação, spam e CORS
O formulário incorporado ou webhook do seu CRM	O lead precisa chegar em um CRM de qualquer forma	Peso da incorporação e limites de estilo; geralmente lento para carregar

Qualquer que você escolha:

• CORS será seu primeiro erro. Um endpoint serverless em uma origem diferente da sua página deve permitir explicitamente essa origem, ou o navegador bloqueia a requisição antes mesmo de ser enviada. Adicione localhost à lista de permissões também, ou você não pode testar localmente.
• Adicione um campo honeypot (uma entrada oculta que humanos nunca preenchem e bots sim) e rejeite qualquer coisa que o preencha. O filtro de spam mais barato que existe.
• Nunca espalhe um corpo de requisição bruto diretamente em sua escrita de banco de dados. É assim que um visitante acaba definindo campos que você pretendia controlar no servidor. Selecione explicitamente os campos que você deseja.
• Mantenha o endpoint aquecido se possível. Uma função serverless que sofre cold start faz com que o momento mais importante da página — clicar em enviar — pareça quebrado.

---

3. Dê ao Claude um kit de marca — e force-o a carregar

Esta é a coisa de maior alavancagem na lista. No mínimo, o kit contém:

sua oferta · seu mercado-alvo / perfil de cliente · sua estratégia de mensagens · suas cores · suas fontes · seu logotipo

Coloque em uma pasta (brand/). Modelo: starters/brand-kit/brand.md.

Depois faça com que carregue automaticamente. Uma instrução em CLAUDE.md dizendo "leia o kit de marca" é consultiva — é seguida de forma inconsistente. Um hook SessionStart que cat os arquivos no contexto não é opcional e não é ignorado. Essa única mudança é a diferença entre "às vezes alinhado com a marca" e "alinhado com a marca por padrão." Veja starters/settings.json.

Carregue no início da sessão: o kit de marca, um breve documento de arquitetura (como o site é construído, hospedado, implantado) e o registro de sessão mais recente.

Estruturando bem:

• Divida "como a marca parece" de "como a marca fala." Mantenha o arquivo sempre ativo enxuto — paleta, fontes, logotipos, oferta, público. Aponte para material mais profundo de voz/mensagem como "leia isso ao fazer trabalho de texto." Tudo carregado automaticamente custa contexto em cada sessão, para sempre.
• Dê às cores papéis, não apenas códigos hexadecimais ("acento primário — usado para o CTA principal"). Os papéis são o que impedem Claude de inventar uma cor quando precisa de uma. Declare a regra claramente: nenhuma cor fora do kit aparece em lugar nenhum. Cores fora da marca de modelos e geradores se infiltram silenciosamente caso contrário.
• Dois ou três exemplos de tom antes/depois ensinam voz mais rápido do que qualquer lista de adjetivos.
• Se sua mensagem for comercialmente sensível, coloque-a no gitignore mas ainda faça referência a ela a partir de CLAUDE.md — você obtém carregamento consistente sem publicar estratégia ou preços em um repositório.
• Documentos de marca sincronizados externamente ficam desatualizados. Se um documento de voz ou público for copiado de uma unidade compartilhada, reverifique-o em relação à sua fonte antes de uma passagem de cópia — decisões de marketing são tomadas em conversas que nunca voltam para o documento.

Disciplina de texto que o kit de marca deve impor:

• Nunca prometa "sem cadastro / sem e-mail necessário" em uma página cujo trabalho é capturar um e-mail. Soa como redução de atrito até o formulário aparecer, e então é uma contradição no exato momento em que você precisa de confiança. Tranquilize sobre tempo, custo e resultado — "2 minutos · grátis · seu resultado enviado imediatamente."
• Reavalie o microtexto de garantia sempre que a oferta mudar. Ele é copiado entre variantes de página e sobrevive à oferta para a qual foi escrito, precisamente porque soa útil.
• A promessa do anúncio, a promessa da página e a solicitação real do formulário devem concordar. Uma incompatibilidade aparece como queda na etapa onde a verdade chega, não na etapa onde a incompatibilidade foi introduzida. Quando uma etapa vaza, suspeite da etapa anterior.

---

4. Veja antes de enviar

Duas maneiras de olhar para uma página sem implantá-la. Use ambas — são para pessoas diferentes.

Servidor de desenvolvimento local

Para você e Claude, durante a construção. Claude pode iniciar o servidor de desenvolvimento, controlar um navegador real, capturar a tela do resultado e ler os logs do console e de rede — então "isso renderiza corretamente" é respondido olhando, não inspecionando código.

• Nunca execute dois servidores de desenvolvimento para o mesmo projeto ao mesmo tempo. Verifique primeiro se há um processo existente e mate-o antes de iniciar outro — especialmente se agentes paralelos puderem iniciar um cada um.
• Limite os loops de repetição automática a ~3 tentativas. Um loop aberto "continue recarregando e tentando tempos diferentes até funcionar" em torno de um servidor de desenvolvimento mais automação de navegador é um risco genuíno de exaustão de recursos, não apenas um incômodo — já travou uma máquina completamente.
• Verifique a limpeza em vez de confiar nela. "Parei o servidor e fechei as abas" é uma afirmação não verificada como qualquer outra — verifique a lista de processos.
• Espere que o ambiente local seja diferente da produção por design. Qualquer coisa protegida por um ID de análise real ou um endpoint de API ativo é tipicamente um no-op localmente. Isso é comportamento esperado, não um bug — documente para que não seja rediagnosticado a cada poucas semanas.
• Mantenha seus testes de ponta a ponta apontados para localhost por padrão, com apontá-los para a URL real implantada sendo um ato deliberado e separado — caso contrário, uma execução de teste de rotina realiza uma submissão real contra produção.

Claude Design (claude.ai/design)

Para todos os outros. Claude pode enviar uma página para um projeto Claude Design, dando a você uma URL compartilhável onde um cliente, um designer ou um parceiro não técnico pode editar texto e layout visualmente no navegador com zero configuração local. Excelente para aprovação antes de uma página ser conectada ao site real.

A única regra rígida: nunca escreva cegamente no Design

Antes de escrever qualquer coisa em um projeto Claude Design, Claude deve buscar a versão remota atual, fazer o diff e verificar com você antes de sobrescrever. Todas as vezes.

Não há histórico de versão, desfazer ou lixeira no lado do Design — um arquivo de canvas é mais frágil do que um local não rastreado. Uma sobrescrita cega das edições de um colaborador é permanentemente irrecuperável, e já custou uma noite inteira de texto escrito à mão.

• Crie a página como HTML/CSS/JS estático independente. O Design provavelmente renderizará conteúdo estático puro melhor do que um framework. Se você precisar de interatividade, mantenha-a em um script separado.
• O Design não hospeda imagens. Use placeholder URLs ou incorpore imagens como dados URI.

---

5. Envie com rastreamento mínimo no primeiro dia e otimize a partir de dados reais

Uma página que não está rastreada não é uma página que você pode melhorar. A forma mais rápida de obter melhoria contínua é enviar uma página que você sabe que pode medir, mesmo que a medição seja mínima.

O que rastrear

No primeiro dia:

• Visualizações de página. Quantas pessoas chegam.
• Cliques no CTA. Quantas clicam.
• Envios de formulário. Quantas convertem.
• Tempo de carregamento da página. Quão rápido ela é.

Na primeira semana:

• Taxa de rejeição. Quantas saem imediatamente.
• Profundidade de rolagem. Até onde elas descem.
• Origens de tráfego. De onde elas vêm.
• Taxa de conversão por origem. O que funciona melhor.

Como rastrear

• Use uma ferramenta de análise — Google Analytics, Plausible, Fathom, ou similar. Plausível e Fathom são mais simples e respeitadores da privacidade.
• Adicione o script de rastreamento ao <head> da página.
• Rastreie o envio do formulário — seja um evento de análise ou um webhook que registra a conversão.
• Rastreie cliques no CTA — seja um evento de análise ou um parâmetro de URL que a ferramenta de análise capta.

Otimizando a partir de dados

• Depois que você tiver dados, itere neles. Se a taxa de rejeição for alta, melhore o título e o texto acima da dobra. Se a taxa de conversão for baixa, melhore o CTA e o formulário. Se a página for lenta, otimize imagens e scripts.
• Teste A/B é o padrão ouro — mas requer tráfego suficiente para ser significativo. Até lá, itere com base em dados observacionais e senso comum.
• Nunca otimize para uma métrica às custas de outra. Uma página muito rápida com nenhuma conversão não é melhor do que uma página lenta com alta conversão.

---

6. Arquivos iniciais

starters/ contém modelos e configurações iniciais.

• starters/CLAUDE.md — Modelo de instruções para Claude Code
• starters/brand-kit/brand.md — Modelo de kit de marca
• starters/settings.json — Configurações de sessão do Claude Code (inclui hooks SessionStart)

---

7. A regra de ouro

Claude propõe, você decide, Claude executa.

Números de versão, merges e implantações são seus; branching, push e abertura do PR são do Claude. Se uma chamada for ambígua, Claude pergunta. A decisão final é sempre sua.

---

A página está agora ativa, rastreada e otimizável. Feliz iteração!