← A Trilha

🧪 Roteiro: sua primeira página com o Claude Code

Do zero até no ar, sem git e sem GitHub. Você faz uma página bonita de verdade e publica num endereço público, de graça, pedindo tudo pela aba "Code".

🎯 O que você vai ter no final

Uma página HTML sozinha, com visual caprichado, salva numa pasta do seu computador e no ar num endereço público exclusivo dela, para mandar pra quem você quiser. Tudo pedindo em português, sem decorar comando nenhum e sem gastar nada. Reserve uns 40 a 50 minutos na primeira vez.

💻 Seu sistema

Escolha aqui e os comandos e atalhos do roteiro se ajustam ao seu sistema. O miolo (os pedidos pra IA, a conta, a publicação) é igual nos dois.

✅ Antes de começar

1

Criar a pasta onde seus projetos vão morar

uma vez só, serve para todos os projetos futuros

A IA precisa de uma pasta para trabalhar. Vamos criar uma agora, num lugar que não vai te dar dor de cabeça depois. Dois jeitos de fazer a mesma coisa — escolha o que te deixa mais à vontade.

  1. 1Aperte Win + E para abrir o Explorador de Arquivos.
  2. 2Clique na barra de endereço lá em cima (onde aparece o caminho), apague o que estiver lá, digite %USERPROFILE% e aperte Enter. Isso te leva direto para a sua pasta de usuário, algo como C:\Users\voce.
  3. 3Clique com o botão direito num espaço vazio → Novo → Pasta. Chame de projetos.
  4. 4Entre em projetos e crie outra pasta dentro dela, chamada primeira-pagina.
✅ Nos dois caminhos você fica com: C:\Users\seu-nome\projetos\primeira-pagina, vazia. É nela que a IA vai trabalhar.
⚠️ Evite criar dentro de "Documentos" ou da "Área de Trabalho". No Windows atual, essas duas costumam estar sincronizadas com o OneDrive — e o OneDrive mexendo nos arquivos ao mesmo tempo que a IA pode gerar cópias em conflito ou um arquivo momentaneamente travado. Não impede o Claude de funcionar, mas é atrito à toa. Uma pasta direto no seu usuário (o ~ do comando, ou o %USERPROFILE% pelo mouse) normalmente fica fora do OneDrive — por isso a usamos.
💡 Por que sem espaço e sem acento no nome?
Usamos primeira-pagina em vez de "Primeira Página". Nome com espaço ou acento funciona, mas pede cuidado — um espaço, por exemplo, precisa de aspas em quase todo comando, e é fácil esquecer e ver o comando falhar. Enquanto você está começando, um nome simples (minúsculas, sem acento, hífen no lugar do espaço) tira esse tropeço do caminho, sem você nem pensar nele. É o costume de quem trabalha com código, e é por isso.
2

Abrir a sessão apontando para essa pasta

as 4 escolhas antes do primeiro prompt

Abra o Claude Desktop e vá na aba "Code". Antes de mandar a primeira mensagem, ele pede 4 coisas. Não é instalação, é configuração da sessão (a página das ferramentas explica cada uma com calma):

  1. 1Environment → escolha Local. É o seu próprio computador.
  2. 2Project folder → clique em "Select folder" e aponte a pasta primeira-pagina que você acabou de criar. Esta é a única obrigatória.
  3. 3Model → deixe o padrão.
  4. 4Permission mode → deixe em Manual (a opção que pede sua permissão a cada mudança). É o mais cauteloso e já vem selecionado como padrão, então provavelmente você nem precisa mexer. Na primeira vez isso é ótimo: antes de editar um arquivo ou rodar um comando, ele te mostra o que pretende fazer e espera você aprovar.
✅ Você deve ver o nome da pasta primeira-pagina indicado na sessão. Ainda não digite nada.
💡 Sobre trocar de pasta: a pasta é escolhida por sessão. Para mexer em outro projeto, o caminho normal é abrir uma sessão nova e apontar a pasta dele. Cada sessão tem sua própria conversa, sua própria pasta e suas próprias mudanças.
3

Pedir a página

o prompt é o projeto: quanto mais concreto, melhor o resultado

Aqui está o pulo do gato, e vale mais que o resto do roteiro: a página sai boa na medida em que você diz do que ela trata. Se você pedir "faz uma página bonita", a IA inventa o assunto e cai no genérico, porque não tem de onde tirar decisão nenhuma. Se você disser o assunto, o público e para que a página serve, ela tem matéria-prima para escolher cor, fonte e layout.

Copie o prompt abaixo e mande na caixa de mensagem (o assunto é um exemplo, troque à vontade — só mantenha o mesmo nível de detalhe):

Prompt 1 · criar a página
Crie um arquivo index.html nesta pasta: uma página única que é um mini-guia da região da Vila (o centro histórico de Ilhabela) e das praias em volta, em português do Brasil. É o guia de quem vai todo ano e conhece a ilha, não o de folheto turístico. Detalhes que a página precisa passar: - A base é a Vila (o centro histórico à beira-mar) e as praias mais calmas em volta dela. - Precisa ter: as praias que valem a pena por ali (Perequê, Itaguaçu, Engenho d'Água, Saco da Capela); pescar nos píeres (o da Vila, no fim da Rua do Meio, e o do Perequê); comer bem e barato no Cheiro Verde (comida caseira, na Vila); e o pôr do sol no píer do Perequê. - O público é família, que curte sossego e o jeito local, não balada. - Um aviso honesto de quem já foi: leve repelente, os borrachudos de Ilhabela são famosos. Sobre o visual: um clima de mar e ilha, com personalidade. Não precisa ser espalhafatoso, só não pode parecer template genérico. Faça tudo num arquivo HTML só, com o CSS dentro dele — sem usar fontes, imagens ou bibliotecas carregadas de sites externos. E deixe funcionando bem no celular.
💡 Por que o prompt é escrito assim?
O prompt dá assunto concreto (um guia da região da Vila em Ilhabela, de quem vai todo ano — não "uma viagem" genérica), público (família atrás de sossego), o trabalho da página (guiar o passeio) e uma restrição técnica (um arquivo só, sem puxar nada de fora). Os três primeiros são o que dá à IA de onde tirar o visual. O último deixa este primeiro exercício mais simples: CSS é a parte que diz como a página se parece (cores, fontes, espaçamento), e botar tudo num arquivo só significa que não há vários arquivos pra organizar nem links entre HTML e CSS pra digitar errado. Mais adiante, dá pra separar tudo normalmente (HTML, CSS, imagens).
💡 Por que o arquivo se chama index.html?
São duas coisas num nome só, e a segunda vale guardar.

O .html é o formato: é isso que o navegador sabe abrir e mostrar na tela.

Já index não é um nome qualquer que a gente escolheu: é uma palavra especial. Seus arquivos podem se chamar o que você quiser (ilhabela.html, receita.html, qualquer-coisa.html), e todos esses são nomes comuns: para abrir cada um, a pessoa tem que digitar o nome dele no fim do endereço. Em serviços como o Cloudflare (e na maioria dos servidores web), o index.html é o que ele entrega sozinho quando o endereço não diz qual arquivo quer. Ele é a porta de entrada da pasta publicada, e quem manda nisso é o nome, não o conteúdo: renomear uma página para index.html, ali na raiz, faz dela a porta de entrada. (Não é uma mágica do HTML — é uma convenção do servidor.)

É por isso que lá no passo 6 a sua página vai atender em primeira-pagina.pages.dev, limpo assim. Se ela se chamasse ilhabela.html, você teria que mandar pras pessoas primeira-pagina.pages.dev/ilhabela.html, com o nome pendurado no fim.

Ele vai pedir permissão para criar o arquivo. Aceite. Ele escreve o HTML e, no fim, te resume o que fez.

✅ Você deve ver: um arquivo index.html aparecendo na pasta primeira-pagina. É só isso que precisa acontecer aqui.
💡 Se sair com cara de "página de IA" (fundo creme, letra serifada grandona, degradê roxo), não é azar nem limite da ferramenta: é o que ela produz quando o pedido não a obriga a escolher. Reclame como reclamaria com uma pessoa: "isso está parecendo template. É uma ilha no litoral: mar, mata atlântica, barco de pescador. Puxa o visual pra esse mundo." Quanto mais você aponta o mundo da coisa, menos genérico ela fica.
4

Ver a página com os próprios olhos

antes de publicar, sempre

A IA te descreve o que fez, mas descrição não é a página. E você nem precisa sair do Claude para ver com os próprios olhos: a aba "Code" agora tem um navegador embutido (o "Browser pane"), que abre a sua página ali do lado da conversa.

  1. 1No resumo que a IA te deu, clique no caminho do index.html que aparece no chat. A página abre no navegador embutido, dentro da própria janela do Claude. Se o painel não estiver à vista, chame ele com Ctrl + Shift + B ou pelo menu Views.
  2. 2Olhe de verdade: o texto está certo? O visual combina com o que você pediu? Nada quebrado ou apertado? Essa conferência é o passo. Publicar sem olhar é como mandar um e-mail sem reler.
✅ Na maior parte das vezes a página já vai estar ali antes de você pedir: por padrão a IA abre e confere a própria página no painel a cada mudança (é o "auto-verify"). Ainda assim, o olho final é seu — a IA verifica sozinha o funcionamento básico, você julga se ficou bom.

Prefere ver no seu navegador de sempre, em vez do embutido? Também dá — e serve pra ver a página como um visitante veria:

No Explorador de Arquivos, entre na pasta primeira-pagina e dê dois cliques no index.html. Ele abre no seu navegador. A cada mudança que você pedir, aperte F5 ali para atualizar.

💡 Sinal de que ainda é só seu: nos dois jeitos o endereço começa com file:/// — a página está só no seu computador, ninguém mais vê. Deixá-la pública é o passo 6.
5

Pedir ajustes

é aqui que a coisa fica boa de verdade

Quase nunca sai perfeito de primeira, e não precisa sair. O jeito de trabalhar é conversando: você olha, aponta o que incomoda, ele arruma. Sem mexer em código, sem copiar e colar nada.

Alguns pedidos para experimentar (um de cada vez, olhando o resultado entre um e outro):

Prompt 2 · mudar o conteúdo
Põe lá no topo uma linha de "como chegar" pela balsa de São Sebastião. E deixa o Cheiro Verde com o endereço à mostra: Rua da Padroeira, 109, na Vila.
Prompt 3 · mexer no visual
Gostei do conjunto, mas o título está discreto demais para o clima da coisa. Aumenta ele e dá mais presença. E a seção das praias está apertada contra a de baixo, respira mais aí.
Prompt 4 · conferir no celular
Abre essa página numa tela de celular e me diz se está tudo legível e clicável. Se tiver algo quebrado ou apertado, corrige.
💡 A IA confere de verdade, ou só imagina pelo código?
Com o navegador embutido do passo 4, a IA pode abrir a página e olhar — tira print, estreita a tela como num celular, aperta os botões — em vez de avaliar só o código. Se achar algo apertado, corrige e olha de novo. Antes desse navegador, esse tipo de pedido dependia de a IA adivinhar pelo HTML.
💡 Repare no que você acabou de fazer: em nenhum momento você abriu o HTML, procurou a linha certa, editou e salvou. Você olhou e falou. Essa é a diferença entre pedir o HTML no chat e trabalhar na aba Code: lá você seria o carteiro, levando o código da conversa até o arquivo. Aqui ele faz o trajeto inteiro.
6

Publicar no ar

de graça, e pedindo para a IA fazer

Até aqui a página existe só na sua máquina. Agora ela ganha um endereço de verdade, que você pode mandar pra qualquer pessoa. E quem vai publicar é a própria IA.

Vamos usar o Cloudflare Pages: hospedagem grátis para páginas como a sua, sem cartão de crédito. O motivo de ser ele, e não a sua hospedagem paga, é simples: este é um teste, e teste não deve encostar em site que já está no ar. Aqui você ganha um endereço exclusivo pra ela (um algum-nome.pages.dev gratuito, do Cloudflare), sem mexer no site que já está no ar. E tem um bônus: é o mesmo tipo de publicação que o próximo capítulo automatiza com o GitHub — o que você faz aqui emenda direto lá.

⏱️ Este é o passo mais longo do roteiro — mas não se assuste: quase tudo aqui é "uma vez na vida". Instalar o Node, criar a conta, pegar o token são preparação: você faz uma vez e pronto. Publicar mesmo é o último pedido (6.5), e é só ele que se repete — um pedido em português. Os selos ao lado de cada parte dizem o que é preparação e o que é o dia a dia.

6.1 — Instalar o Node. só na 1ª vez Para publicar no Cloudflare, a IA usa um programa chamado Wrangler, e o Wrangler roda sobre o Node — que precisa existir na máquina, do mesmo jeito que o Git lá do começo. Instala uma vez e pronto:

  1. 1Baixe o instalador em nodejs.org — pegue a versão LTS (a recomendada).
  2. 2Abra o instalador e vá avançando nas telas (os botões "Next") — os padrões servem.
  3. 3Feche e reabra o Claude Desktop inteiro (o app, não só a sessão), pra ele reconhecer o Node — igual você fez com o Git no começo.
💡 Só o Node, mais nada. O Wrangler a IA não instala à parte: ela chama com npx, que baixa e roda o Wrangler quando precisa. Você só precisa do Node na máquina.

6.2 — Criar a conta no Cloudflare (grátis, sem cartão). só na 1ª vez Vá em dash.cloudflare.com/sign-up, crie a conta com e-mail e senha e confirme o e-mail. Não pede cartão, e você não precisa configurar domínio nenhum: o endereço .pages.dev sai de graça no passo de publicar.

🔑 Use uma senha exclusiva dessa conta. Não reaproveite senha de e-mail ou banco — é bom hábito para qualquer cadastro novo. (E ela não chega perto da IA: a publicação vai usar um token, não a sua senha — é o próximo passo.)

6.3 — Pegar o token de acesso. só na 1ª vez Para a IA publicar sem você entregar a senha, o Cloudflare te dá um token de API: um código com permissão limitada ao Cloudflare Pages — não à sua senha nem ao resto da conta — que você pode revogar depois. Você cria e copia ele do painel:

  1. 1No Cloudflare logado, abra dash.cloudflare.com/profile/api-tokens (o My Profile → API Tokens) e clique em Create Token.
  2. 2Desça até "Create Custom Token" e clique em Get started. Em Permissions, escolha Account · Cloudflare Pages · Edit — só isso. Depois Continue to summary → Create Token.
  3. 3Copie o token — ele aparece uma vez só. Assim que copiar, vá direto ao 6.4 e cole no editor antes de copiar qualquer outra coisa: a área de transferência guarda um valor por vez, e este token não reaparece. (O Account ID você pega logo em seguida, no 6.4 — esse fica sempre disponível.)
✅ Token copiado. No próximo passo você o guarda num lugar seguro do Claude — e pega o Account ID junto. Repare que você não deu sua senha para a IA: só um token limitado ao Cloudflare Pages — não a sua senha nem o resto da conta — que você revoga quando quiser.
🔌 O que é esse token, afinal (e por que não a senha)?
É o jeito padrão de dois sistemas conversarem. Um token de API deixa um programa agir em nome do outro sem trafegar a senha — é o que está por trás de "conectar com a sua conta do Google", de uma loja cobrar via Stripe, ou de acessar a AWS pela linha de comando. Você quase sempre o pega copiando de um painel, exatamente como acabou de fazer. E repare no escopo: esse token vale só para "Cloudflare Pages: Edit" — então, mesmo se vazasse, o estrago ficaria preso ao Cloudflare Pages: não daria acesso à sua senha nem às outras áreas da conta. Ele faz só o que esse escopo permite e pode ser revogado sozinho.

6.4 — Guardar o token (e o Account ID) no Claude. só na 1ª vez Em vez de colar o token na conversa toda vez, você o guarda uma vez, num lugar seguro do próprio Claude. Aí o Wrangler pega ele sozinho na hora de publicar, e você nunca mais mexe nisso — em nenhuma conversa.

  1. 1Na caixa de mensagem, abra o menu do ambiente (onde aparece "Local"), passe o mouse sobre Local e clique na engrenagem (⚙️).
  2. 2Crie a variável CLOUDFLARE_API_TOKEN e cole nela o token que você acabou de copiar no 6.3. Faça isto primeiro, enquanto ele ainda está na área de transferência.
  3. 3Agora crie a variável CLOUDFLARE_ACCOUNT_ID. Para o valor, volte ao Cloudflare e copie o Account ID — ele fica sempre disponível (no menu Workers & Pages, na coluna da direita, ou no endereço do painel depois de dash.cloudflare.com/). Cole aqui e confira que os nomes das duas variáveis estão exatos.
  4. 4Salve. Se o Claude já estava aberto, abra uma sessão nova pra ele enxergar as variáveis — se mesmo assim não achar, feche e reabra o app inteiro.
✅ Pronto. O Claude guarda os dois encriptados na sua máquina — fora da conversa e fora da pasta do projeto. Valem pra qualquer sessão, e o token nunca mais precisa aparecer no chat.
💡 Por que não guardar o token num arquivo ou no CLAUDE.md?
Porque segredo não pode ficar em texto plano nem em nada que vá pro GitHub ou volte pra conversa. Um arquivo na pasta do projeto vira commitado no capítulo 2 e vaza no GitHub (é o erro clássico — há bots varrendo o GitHub atrás de chaves). O CLAUDE.md é pior: vai pro GitHub e é lido em toda sessão. O editor de variáveis é o único desses caminhos que não peca por nenhum lado: encriptado, fora do repo, e o Wrangler lê direto do ambiente, sem o valor passar pela conversa.

6.5 — Publicar. 🔄 isto você repete Agora é um pedido só, em português — sem colar token nenhum, ele já está guardado:

Prompt 5 · botar no ar
Publica o index.html desta pasta no Cloudflare Pages usando o Wrangler, num projeto chamado primeira-pagina (se esse nome já estiver em uso, escolha um parecido e me avisa qual). O token e o Account ID já estão nas variáveis de ambiente CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID. Cria o projeto se ainda não existir. No fim, me diz o endereço .pages.dev onde a página ficou, abre ele e confirma que respondeu e que é a página certa.

Você diz o que quer (publicar e conferir); o como fica com a IA. Se a curiosidade bater, dá para espiar os comandos que ela roda — mas para publicar você não precisa disso:

O que ela faz por baixo do capô (opcional)
npx wrangler pages project create primeira-pagina npx wrangler pages deploy . --project-name=primeira-pagina

O Wrangler lê o token e o Account ID das variáveis de ambiente que você salvou no passo 6.4 (CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID) — é como ele se autentica, sem o valor passar pela conversa. O primeiro comando cria o projeto (uma vez); o segundo sobe os arquivos da pasta. O npx baixa o Wrangler na estreia, por isso a primeira vez demora um pouco mais.

🎉 Abra o endereço .pages.dev que a IA te deu (algo como primeira-pagina.pages.dev). Está no ar. A página que a IA desenhou, que você ajustou conversando, num endereço público que você pode mandar pra quem quiser. Sem nunca ter aberto o HTML.
📉 E repare como fica daqui pra frente — o esforço só cai:

▸ Da próxima vez que publicar (esta página ou outra qualquer, hoje ou daqui a um mês): é só o Prompt 5. O Node, a conta e o token já estão guardados — inclusive em conversa nova, você não recola nada.
▸ No próximo capítulo: nem o prompt. Você salva, faz git push, e o site se atualiza sozinho.

O passo de hoje foi o degrau mais alto — a partir daqui, só desce. Quer sentir agora? Volta, pede uma mudança na página (troca uma cor, um texto) e manda publicar de novo: é só o Prompt 5, e a página troca no ar rápido. Sem setup nenhum — porque setup não se repete.

Se travar: os poucos tropeços possíveis.

  1. 1"node" ou "npx" não é reconhecido. O Node foi instalado agora e o Claude ainda não o enxergou. Feche e reabra o Claude Desktop inteiro (não só a sessão) e peça de novo.
  2. 2Erro de autenticação (Authentication error, código 10000). Duas causas comuns: (a) as variáveis do passo 6.4 não foram salvas com os nomes exatos, ou você não abriu uma sessão nova depois de salvar — confira e abra uma sessão nova; (b) o token não tem a permissão certa — gere um novo com Account · Cloudflare Pages · Edit e atualize a variável.
  3. 3Nome do projeto em uso. O endereço .pages.dev é único no mundo todo. Se primeira-pagina já estiver ocupado, o Cloudflare acrescenta alguns caracteres ao endereço sozinho (ou a IA usa um nome parecido) — de um jeito ou de outro, ela te diz o endereço final.
🔒 O token não fica na conversa — está guardado encriptado (passo 6.4), fora do chat e fora do projeto. Se um dia quiser fechar a porta de vez, é só revogá-lo em API Tokens no Cloudflare: o acesso some na hora, sem trocar senha de nada. É a vantagem de usar token em vez de senha.

🔜 O que ficou de fora de propósito

Este roteiro é o capítulo 1, e ele deixa quatro buracos conhecidos. Não são esquecimento, são a próxima conversa:

De onde saiu cada afirmação (verificado em 15/07/2026, revisto em 19/07):

📌 Por que Cloudflare Pages e não a sua hospedagem paga: é grátis e sem cartão, te dá um endereço .pages.dev só seu, autentica por token revogável e escopado (só "Cloudflare Pages: Edit") em vez de senha, e principalmente: um teste não deve encostar num site que já está no ar. Ele pede o Node instalado (o Wrangler roda sobre ele), mas em troca é o mesmo tipo de deploy que o próximo capítulo automatiza com o GitHub — o teste de hoje já é o primeiro degrau de lá.