Pular para o conteúdo

Builder OS

&
Builder · OS
L04 · Primeiro projeto
PRÓXIMA L05
~9 MIN DE LEITURA

Lição 4 de 10: Do zero ao primeiro npm run dev

lição 4/10 do Módulo 1
AO FIM, VOCÊ VAI TER
  • Um projeto novo no seu GitHub (uma "pasta na nuvem")
  • O projeto rodando no seu computador
  • O Claude tendo lido o CLAUDE.md, instalado as dependências e ligado o servidor, tudo a pedido seu
Ver transcrição real

Esta lição cria seu primeiro projeto com Claude Code a partir do : um repositório-molde que já vem com CLAUDE.md, rules/ e skills/ configurados.

O que tem dentro do starter

Antes de criar, olha o que você vai herdar. Esta é a estrutura .claude/ do starter:

.claude/
├── settings.json          # permissões (o que o Claude pode rodar sem perguntar)
├── rules/
│   ├── bilingual-content.md
│   ├── no-secrets-in-claude-md.md
│   └── plan-lifecycle.md
└── skills/
    ├── getting-started/   # dispara na primeira conversa
    ├── plan-then-work/
    ├── nextjs-react/
    ├── commit-and-pr/
    └── ui-design/

Mais o CLAUDE.md na raiz, com convenções de stack e comandos. Quando você abrir o Claude Code dentro dessa pasta na primeira vez, o skill getting-started dispara, lê o CLAUDE.md, e te recebe sabendo onde está.

O que você vai conseguir ao fim desta lição

Em 5 minutos você terá:

  1. Um projeto novo no seu GitHub criado a partir do starter
  2. O projeto clonado no seu computador
  3. O Claude lendo o CLAUDE.md, instalando dependências e ligando o servidor, a pedido seu
  4. localhost:3000 aberto no navegador com a página inicial do template

Daqui pra frente, você só vai adicionando coisas em cima dessa base.

Passo 1: Criar o projeto a partir do template

O Claude precisa de uma pasta pra abrir dentro. Esse comando cria essa pasta, e é o único da lição que você roda na mão.

Em vez de uma pasta vazia, você usa o starter como template: um projeto pronto, com CLAUDE.md, regras e skills já configurados.

Antes de colar, navegue no terminal até onde quer que o projeto fique. Por exemplo:

terminal
mkdir -p ~/code && cd ~/code

Agora cole:

prompt · bash
gh repo create  \
--template jpvss/builder-os \
-- \
--clone
NOME_DO_PROJETO[NOME_DO_PROJETO]— só letras minúsculas, números e hífens. Ex: minha-saas-de-recibos
VISIBILIDADE[VISIBILIDADE]— private (só você vê) ou public; comece em private se tiver dúvida

Em uns 4 segundos a saída deve ser parecida com isso (com seu usuário do GitHub no lugar de seu-usuario):

saída esperada
✓ Created repository seu-usuario/{{NOME_DO_PROJETO}} on GitHub
https://github.com/seu-usuario/{{NOME_DO_PROJETO}}
✓ Cloned repository to "{{NOME_DO_PROJETO}}"

Outra coisa qualquer? Copia o erro inteiro e usa o botão de ajuda (?) no canto da página.

Abre o GitHub no navegador pra ver o projeto novo lá.

Passo 2: Entrar na pasta e abrir o Claude

Entra na pasta do projeto (cd <nome>) e abre o Claude Code. Como você abre depende de onde prefere trabalhar:

terminal
cd {{NOME_DO_PROJETO}} && claude

No terminal: é o último comando que você roda na mão nessa lição.

  • Terminal: o comando acima. A interface do Claude abre na própria aba.
  • Cursor / VS Code: abre a pasta do projeto (File → Open Folder) e clica no ícone do Claude na barra lateral. A interface aparece num painel ao lado do código.
  • App desktop: abre o app, clica em "Open project" e escolhe a pasta. A interface aparece na janela do app.

Nos três casos o resultado é o mesmo: o Claude está dentro do seu projeto.

Passo 3: Pedir pro Claude ler, instalar e rodar

Cole o prompt abaixo dentro da interface do Claude e aperte Enter pra enviar (Cmd+V ou Ctrl+V cola; Enter manda):

prompt · text
Leia o CLAUDE.md e me diga em 3 bullets o que este projeto é e quais são as 3 principais convenções que você deve seguir. Depois, rode `npm install` e `npm run dev` pra eu ver o servidor subindo.

O que esperar

O Claude responde em duas etapas.

Primeiro, ele lê o CLAUDE.md e te manda 3 bullets. A resposta deve mencionar:

  1. Next.js 16 (ou versão equivalente) como framework.
  2. Fluxo de planos: todo trabalho não-trivial começa com um arquivo em plans/, e quando termina vai pra plans/archive/. Isso é o "plan lifecycle" do template.
  3. Skills em .claude/skills/.

Se nenhuma dessas três coisas aparecer, o skill getting-started do template provavelmente não disparou. Abre uma issue em jpvss/builder-os com a resposta que veio, e segue mesmo assim: o resto da lição funciona.

Depois, o Claude pede sua permissão pra rodar dois comandos:

saída esperada
Bash command
npm install
Install project dependencies

Do you want to proceed? [y/n]

Esse é o modelo de permissões em ação. A lição 09 vai fundo nele.

Aprove com y (ou yes). O npm install leva 30–60 segundos. Em seguida vem o pedido pra . Aprove de novo. Quando o Claude mostrar a mensagem Ready in X.Ys (X.Y é o tempo em segundos), abre http://localhost:3000 no navegador.

A página inicial do template carrega: preta, com o nome "Builder OS Starter" e um link pro CLAUDE.md.

Veja isso ao vivo

Sessão real, num laptop limpo, com tudo o que você pode encontrar pelo caminho:

Takeaways

  • O starter é um template (gh repo create --template jpvss/builder-os): você herda CLAUDE.md, rules/ e skills/ já configurados, sem montar boilerplate na mão.
  • gh repo create é o único comando que você roda fora do Claude. Depois que o projeto existe, todo o resto passa pelo Claude com sua aprovação.
  • O skill getting-started dispara na primeira conversa e lê o CLAUDE.md por você. Três bullets sobre stack, plan lifecycle e skills é o sinal de que funcionou.
  • Ready in X.Ys no terminal + página preta em localhost:3000 = bootstrap completo. A personalização vem na lição 05.

Você terminou quando