Fluxo de trabalho

Você já usou o terminal sem saber: quando o Claude Code roda, é ali que ele está. Toda ferramenta séria de desenvolvimento — git, npm, Vercel, Astro — nasce como comando de terminal e só depois, às vezes, ganha uma interface gráfica.

A diferença prática é esta: no mouse, renomear 40 arquivos são 40 operações manuais. No terminal, é uma linha. E a linha você pode salvar, repetir no mês seguinte e mandar para outra pessoa.

No Windows, use o PowerShell ou, melhor ainda, o Windows Terminal (grátis na Microsoft Store). Atalho: tecla Windows, digite "terminal", Enter. Se você instalar o Git, ganha também o Git Bash, que fala a mesma língua do Mac e do Linux — é o que eu recomendo para começar, porque todo tutorial que você achar na internet vai assumir essa sintaxe.

No Mac, é o Terminal (Cmd+Espaço, digite "terminal"). No Linux, Ctrl+Alt+T na maioria das distribuições.

Dentro do VS Code, qualquer sistema: Ctrl+' (ou Ctrl+Shift+P → "toggle terminal"). Esse é o que você mais vai usar, porque ele já abre na pasta do projeto aberto.

O terminal sempre está dentro de uma pasta. Todo comando age a partir dali. Se você entender só isso, metade da confusão some.

pwd              # "print working directory" — onde estou agora
ls               # lista o que tem aqui   (Windows PowerShell: dir)
ls -la           # lista tudo, inclusive arquivos ocultos, com detalhes

cd projetos      # entra na pasta "projetos"
cd ..            # sobe um nível
cd ../..         # sobe dois
cd ~             # vai para a sua pasta de usuário
cd -             # volta para a pasta anterior (o "voltar" do navegador)

Caminho relativo parte de onde você está: cd site/imagens. Caminho absoluto parte da raiz e funciona de qualquer lugar: cd /Users/gustavo/projetos/site no Mac, cd C:\Users\gustavo\projetos\site no Windows.

mkdir cliente-vanessa          # cria pasta
mkdir -p cliente/img/hero      # cria a árvore inteira de uma vez

touch index.html               # cria arquivo vazio (Git Bash, Mac, Linux)
New-Item index.html            # equivalente no PowerShell

cp index.html backup.html      # copia
cp -r site/ site-backup/       # copia pasta inteira (-r = recursivo)

mv antigo.html novo.html       # renomeia
mv index.html site/            # move para dentro de uma pasta

rm arquivo.html                # apaga arquivo
rm -r pasta/                   # apaga pasta inteira

code .                         # abre a pasta atual no VS Code
open .                         # abre no Finder (Mac)  |  explorer . no Windows

Repare que renomear e mover são o mesmo comando. Faz sentido: mover é mudar o caminho, renomear é mudar o final do caminho.

Quatro hábitos separam quem sofre no terminal de quem voa nele.

E os curingas, que é onde a economia vira absurda:

ls *.html              # só os arquivos .html
cp *.jpg fotos/        # copia todos os jpg de uma vez
rm *.tmp               # apaga todos os temporários

# quantas linhas tem cada página do site?
wc -l *.html

# em quais arquivos aparece o telefone antigo do cliente?
grep -rl "3321-4455" .

Três operadores, e você monta rotinas inteiras.

mkdir site && cd site        # só entra se conseguiu criar
git add . && git commit -m "hero pronta"   # só commita se o add deu certo

ls *.html | wc -l            # o "|" joga a saída de um na entrada do outro
                             # = "liste os html e conte quantas linhas saíram"

ls -la > lista.txt           # manda a saída para um arquivo (sobrescreve)
echo "nova linha" >> log.txt # acrescenta ao final do arquivo

O && é o mais útil no dia a dia, justamente porque ele para se algo falhar. Se o git add der erro, você não quer que o commit aconteça mesmo assim.

No terminal não existe lixeira. rm apaga de verdade, na hora, sem perguntar.

# SEMPRE veja antes de apagar
ls *.tmp          # confere o que vai sumir
rm *.tmp          # aí sim

rm -i arquivo     # -i pergunta antes de cada um

# nunca, em hipótese alguma:
rm -rf /          # apaga o sistema inteiro
rm -rf ~          # apaga sua pasta de usuário inteira

E aqui está o melhor argumento para a parte seguinte: se o projeto estiver no Git, apagar arquivo errado deixa de ser tragédia e vira um comando de recuperação. É por isso que Git vem logo depois do terminal, e não depois de mais nada.

Você já viveu isto: index-final.html, index-final2.html, index-FINAL-agora-vai.html. E na hora de saber o que mudou entre um e outro, ninguém sabe.

Git responde quatro perguntas que a pasta de arquivos não responde:

Para o seu caso específico tem uma quinta: quando o Claude Code muda dez arquivos de uma vez, o Git é o que te mostra exatamente o que ele fez — e o que te devolve o estado anterior se ele fez besteira. Sem isso, você está aceitando mudança no escuro.

Todo comando de Git move arquivo entre três lugares. Entenda os três e o resto se explica.

Por que existe a bandeja do meio? Porque numa tarde você mexe no menu, corrige um telefone e começa uma seção nova. Isso é três assuntos. Se virar um commit só, a história fica inútil — e daqui a um mês, quando o telefone estiver errado, você não consegue desfazer só aquilo.

Um commit é uma foto do projeto inteiro mais uma mensagem explicando por quê. A foto o Git tira sozinho; a mensagem é sua, e é ela que decide se a história vai servir para alguma coisa.

# ruim — não diz nada que o diff já não diga
"alterações"
"update"
"ajustes finais"
"asdasd"

# bom — diz o QUÊ e, quando não é óbvio, o PORQUÊ
"hero da Vanessa: troca foto e encurta headline"
"corrige telefone no rodapé das 10 paginas"
"menu vira dropdown agrupado — 10 links na barra nao cabiam no mobile"
"revert: volta animação da hero, estava atrasando o LCP"

Duas regras de tamanho que resolvem quase tudo: um commit, um assunto; e se a mensagem precisa de "e", provavelmente são dois commits. "Corrige telefone e adiciona seção de FAQ" é dois.

Três confusões que custam caro:

Git não é GitHub. Git é o programa que roda no seu computador e guarda a história localmente — funciona sem internet, para sempre. GitHub é um site que hospeda cópias desses repositórios. Existem outros (GitLab, Bitbucket, Codeberg). Você pode usar Git a vida toda sem nunca criar conta em lugar nenhum.

Git não é backup. Ele guarda a história do que você mandou ele guardar. Arquivo que nunca entrou num commit não existe para ele. E se o HD morrer, morre o repositório junto — a cópia no GitHub é que cumpre o papel de backup, e é por isso que push importa.

Git não é para arquivo grande. Ele foi feito para texto, onde consegue guardar só a diferença entre versões. Foto de 8 MB da obra do cliente entra inteira, e de novo inteira a cada versão. Imagem de site (comprimida, uns 200 KB) tudo bem. Vídeo, PSD, pasta de fotos brutas do fotógrafo — não.

Baixe em git-scm.com. No Windows, aceite os padrões e marque a opção que instala o Git Bash. No Mac, rodar git --version no Terminal já oferece a instalação.

git --version                       # confirma que instalou

git config --global user.name "Gustavo"
git config --global user.email "seu@email.com"

git config --global init.defaultBranch main   # nome moderno do ramo principal
git config --global core.editor "code --wait" # usa o VS Code quando pedir texto
git config --list                             # confere tudo

mkdir lp-vanessa && cd lp-vanessa
git init                    # cria a pasta oculta .git — é o repositório inteiro

# ou, para trazer um projeto que já existe no GitHub:
git clone https://github.com/JaumNf/gustavo-tutorial.git
cd gustavo-tutorial

O git init cria uma pasta .git escondida. Ela é o repositório: toda a história mora ali. Copiar a pasta do projeto copia a história junto; apagar a .git apaga a história e deixa só os arquivos atuais.

Este é o Git inteiro do dia a dia. Você vai repetir isso dez vezes por dia e vai parar de pensar nele.

git status                  # o comando mais importante: o que mudou, o que está preparado

git add index.html          # prepara um arquivo
git add css/ js/            # prepara pastas inteiras
git add .                   # prepara tudo que mudou
git add -p                  # prepara pedaço por pedaço, perguntando (ótimo para separar assuntos)

git commit -m "hero: nova foto e headline mais curta"

git status                  # confirma: "working tree clean"

git status é o comando que responde "e agora?". Rode-o sempre que estiver em dúvida — ele inclusive sugere o próximo comando no texto da resposta.

Um arquivo chamado .gitignore na raiz do projeto lista o que o Git deve fingir que não existe.

# dependências — se reinstalam, não se versionam
node_modules/

# segredos — a linha mais importante deste arquivo
.env
.env.local
*.key

# lixo de sistema
.DS_Store
Thumbs.db

# saída de build
dist/
.vercel/

# originais pesados do cliente
fotos-brutas/
*.psd

git log                              # história completa (q sai)
git log --oneline                    # uma linha por commit — o que você mais usa
git log --oneline -10                # os dez últimos
git log --oneline --graph --all      # desenha os ramos
git log -p index.html                # história de UM arquivo, com as mudanças

git diff                             # o que mudei e ainda não preparei
git diff --staged                    # o que está preparado, prestes a virar commit
git diff HEAD~1                      # o que mudou desde o commit anterior

git diff é o hábito que mais protege você: leia o diff antes de todo commit. É onde você pega o console.log esquecido, o texto de teste que ficou na página e a linha que o Claude Code mudou sem avisar.

Aqui mora o medo, e ele acaba quando você percebe que são só três situações.

# 1 · estraguei o arquivo e ainda NÃO commitei
git restore index.html          # joga fora a alteração e volta ao último commit
git restore .                   # em todos os arquivos — cuidado, não tem volta

# 2 · preparei errado (fiz add do que não queria)
git restore --staged index.html # tira da bandeja, mantém a alteração

# 3 · commitei e me arrependi
git commit --amend -m "mensagem certa"   # corrige o ÚLTIMO commit (só se ainda não deu push)
git revert abc1234                       # cria um commit novo que desfaz aquele — seguro
git reset --soft HEAD~1                  # desfaz o commit, mantém as alterações preparadas
git reset --hard HEAD~1                  # desfaz o commit E joga as alterações fora

O cenário real: o cliente diz que a página de ontem estava melhor.

git log --oneline               # ache o código do commit, ex: 9f3a1c2

# só olhar como o site estava naquele dia:
git checkout 9f3a1c2            # o projeto inteiro volta no tempo
git switch -                    # e volta para o presente

# trazer UM arquivo daquela versão para o presente:
git restore --source=9f3a1c2 index.html

# apagou um arquivo sem querer e já commitou?
git restore --source=HEAD~1 arquivo-que-sumiu.html

Um branch é uma linha paralela da história. Você sai do principal, faz o que quiser, e ou junta de volta ou joga fora. Nada do que acontece ali afeta o site no ar.

git switch -c hero-nova       # cria e entra no branch (antes: git checkout -b)
# ... trabalha, commita à vontade ...

git switch main               # volta para o principal
git merge hero-nova           # traz as mudanças para cá
git branch -d hero-nova       # apaga o branch, já cumpriu o papel

git branch                    # lista os que existem
git branch -D hero-nova       # apaga mesmo sem ter juntado (a ideia não prestou)

Conflito acontece quando dois branches mudaram a mesma linha do mesmo arquivo e o Git não tem como adivinhar qual vale. Ele para, marca o trecho e pede que você decida.

<<<<<<< HEAD
<h1>Arquitetura que cabe no seu prazo</h1>
=======
<h1>Projetos de interiores em Campo Grande</h1>
>>>>>>> hero-nova

Em cima, o que está no branch atual. Embaixo, o que vem do outro. Você apaga as três linhas de marcação e deixa o texto que quer ficar — pode ser um dos dois, pode ser uma mistura. Depois:

git add index.html
git commit                      # finaliza o merge

git merge --abort               # ou desiste e volta tudo como estava

git remote -v                              # quais servidores este projeto conhece
git remote add origin https://github.com/JaumNf/gustavo-tutorial.git

git push -u origin main    # manda pela primeira vez e guarda o destino
git push                   # daí em diante, só isso

git pull                   # traz o que mudou no servidor para cá
git fetch                  # só verifica, sem mexer nos seus arquivos

origin é só um apelido para o endereço do servidor — o nome padrão, nada mágico. main é o branch.

É aqui que tudo se junta. Com o repositório ligado à Vercel — que é como o seu site já está hoje — publicar deixa de ser uma tarefa:

git add .
git commit -m "trilha de fluxo de trabalho"
git push

# pronto. A Vercel detecta, constrói e publica sozinha em ~30 segundos.

E tem o bônus que quase ninguém usa: todo branch ganha uma URL de pré-visualização própria. Você faz git push -u origin hero-nova e a Vercel publica aquele branch num endereço separado. Isso resolve um problema real do seu ofício — mandar para o cliente ver a proposta nova sem tocar no site que está no ar.

Vale registrar porque é o erro mais comum de quem sobe arquivo pelo navegador: você arrastou a pasta gustavo-tutorial-site/ para o GitHub. Os arquivos foram parar em /gustavo-tutorial-site/index.html, e a Vercel serve a raiz — então o site respondeu 404.

O diagnóstico foi comparar duas URLs: /estilo.css deu 404 e /gustavo-tutorial-site/estilo.css deu 200. Isso localiza o problema em dez segundos e serve para qualquer site quebrado.

# com Git, o mesmo erro não acontece — você trabalha DENTRO da pasta certa:
cd gustavo-tutorial     # o clone do repositório
cp ~/Downloads/gustavo-tutorial-site/*.html .
cp ~/Downloads/gustavo-tutorial-site/*.css .
cp ~/Downloads/gustavo-tutorial-site/*.js .
git status              # confere: os arquivos estão na raiz
git add . && git commit -m "laboratorio de movimento" && git push

Esta é a parte que muda mais o seu dia, porque o problema de trabalhar com IA em código é exatamente o problema que o Git resolve: como eu sei o que mudou e como eu volto?

O ciclo completo fica assim:

git switch -c secao-faq          # ponto de partida limpo
# ... pede a seção ao Claude Code ...
git status                       # o que ele tocou?
git diff                         # o que exatamente ele escreveu?
git add . && git commit -m "faq: quatro perguntas com acordeão"
git switch main && git merge secao-faq && git push

F12, ou Ctrl+Shift+I (Cmd+Option+I no Mac). Mas o jeito que economiza mais tempo é outro: botão direito no elemento → Inspecionar. Isso abre já com aquele elemento selecionado.

No painel Elements, o lado esquerdo é o HTML e o direito é o CSS aplicado àquele elemento. Tudo é editável, e a página responde na hora. Nada disso é salvo — recarregou, voltou ao normal.

Como você estiliza :hover se o estilo some quando você tira o mouse para ir até as DevTools? Você força o estado.

No painel Styles, o botão :hov abre caixas para :hover, :active, :focus, :focus-visible e :visited. Marque e o elemento fica travado naquele estado enquanto você ajusta.

Logo ao lado, o ícone de pincel (Rendering, ou Ctrl+Shift+P → "rendering") tem as simulações que mais importam para o seu trabalho:

Os três problemas de layout que mais aparecem e onde exatamente olhar:

"Por que tem espaço em branco aqui?" — passe o mouse sobre os elementos no painel Elements. O navegador pinta o box model por cima da página: azul é o conteúdo, verde é o padding, laranja é a margem. O culpado costuma estar na faixa laranja.

"Por que a página rola para o lado no celular?" — cole isto no Console e o elemento culpado fica com borda vermelha:

document.querySelectorAll('body *').forEach(el => {
  if (el.getBoundingClientRect().right > window.innerWidth) {
    el.style.outline = '2px solid red';
    console.log(el);
  }
});

"Meu grid/flex não está fazendo o que eu quero" — ao lado do elemento aparece um selo grid ou flex. Clique: o navegador desenha as linhas, numera as colunas e mostra os espaçamentos sobre a página.

Uma distinção que confunde muita gente: Ctrl+U mostra o HTML que veio do servidor. O painel Elements mostra o DOM depois de todo o JavaScript ter rodado. Num site feito em React, o primeiro vem quase vazio e o segundo está cheio.

Isso tem consequência direta no seu trabalho: o Google, quando rastreia, começa pelo primeiro. É a razão técnica de HTML puro ter vantagem em SEO — o conteúdo já está lá, sem depender de nada rodar.

Quando algo de JavaScript quebra, a página simplesmente para de fazer aquilo — sem aviso na tela. O Console é o único lugar onde o erro aparece. Primeira coisa a fazer quando "não está funcionando": abrir o Console.

Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
→ o querySelector não achou o elemento. Erro de digitação na classe,
  ou o script rodou antes do HTML existir.

Uncaught ReferenceError: gsap is not defined
→ a biblioteca não carregou. Veja a aba Network: o arquivo veio?

Failed to load resource: 404 (Not Found)
→ caminho de arquivo errado. Foi exatamente o seu erro da pasta no GitHub.

Refused to load ... violates Content Security Policy
→ o servidor bloqueou um script externo.

E o Console também é um laboratório: qualquer JavaScript roda ali, na página aberta, na hora.

$0                          // o elemento selecionado no painel Elements
$$('a')                     // atalho para querySelectorAll
$$('img').filter(i => !i.alt)          // toda imagem sem texto alternativo
$$('a').filter(a => !a.href)           // todo link quebrado
document.querySelectorAll('h1').length // tem mais de um h1? (problema de SEO)

Abra a aba Network e recarregue com ela aberta (senão vem vazia). Cada linha é um arquivo que a página pediu.

Ordene pela coluna Size, do maior para o menor. Em nove de dez sites lentos, as três primeiras linhas são imagens — e a conversa sobre performance acaba ali. No rodapé o navegador soma tudo: requests e transferred.

Os filtros no topo (Doc, CSS, JS, Img, Font) isolam por tipo. E a coluna Waterfall mostra a ordem: o que está segurando o resto aparece como uma barra longa antes das outras.

Ctrl+Shift+M liga o modo dispositivo: a página passa a ser renderizada numa largura de celular, com toque simulado.

Use larguras reais, não as do menu apenas: 360px (Android popular), 390px (iPhone atual), 430px (iPhone grande), 768px (tablet). Se funciona em 360, funciona em quase tudo.

Dá para abrir as DevTools do computador apontando para a página que está rodando no aparelho. É o que resolve o "só no meu iPhone que quebra".

Android + Chrome: no celular, Configurações → Sobre o telefone → toque 7 vezes em "Número da versão" para liberar as opções de desenvolvedor; ative a Depuração USB. Conecte o cabo, aceite o aviso, e no computador abra chrome://inspect. A aba aberta no celular aparece na lista com um botão inspect.

iPhone + Safari: no iPhone, Ajustes → Apps → Safari → Avançado → Inspetor da Web. No Mac, Safari → Ajustes → Avançado → "Mostrar recursos para desenvolvedores". Conecte o cabo e o aparelho aparece no menu Desenvolvedor do Safari.

A aba Lighthouse roda uma auditoria automática e devolve quatro notas: Performance, Acessibilidade, Boas práticas e SEO. Marque "Mobile" — é o que o Google usa para ranquear.

Duas ressalvas para você não se enganar com o número:

Rode em aba anônima. Extensões do Chrome entram na conta e derrubam a nota de uma página que está ótima.

É laboratório, não realidade. Lighthouse simula um aparelho e uma rede. O dado que o Google realmente usa vem dos usuários de verdade e aparece no PageSpeed Insights (pagespeed.web.dev), na seção de dados de campo — que só existe depois que o site tem tráfego.

Você corrige, publica, abre e a versão antiga continua lá. Não está louco: o navegador guardou o CSS antigo.

Quando este site ganhou a trilha de Movimento, o menu precisou de um link novo. Dez arquivos. Quando virou dropdown agrupado, foram dez blocos de HTML substituídos. Numa das vezes o trafego.html ficou de fora e ninguém percebeu na hora — porque conferir dez arquivos no olho é exatamente o tipo de tarefa em que o olho falha.

Esse é o único problema real do HTML puro em site de várias páginas. Não é performance, não é SEO, não é capacidade: é repetição de trecho comum — cabeçalho, menu, rodapé, scripts.

O HTML continua repetido, mas você nunca edita as dez cópias na mão: um script faz a substituição em todos os arquivos e você confere o resultado.

import glob, re

NOVO = open('menu.html', encoding='utf-8').read()

for arquivo in glob.glob('*.html'):
    h = open(arquivo, encoding='utf-8').read()
    # troca tudo entre <nav class="navmenu"> e </nav>
    h = re.sub(r'<nav class="navmenu".*?</nav>', NOVO, h, flags=re.S)
    open(arquivo, 'w', encoding='utf-8').write(h)
    print(arquivo, 'ok')

É feio e funciona. Foi assim que o menu deste site foi trocado nas dez páginas, e é assim que se corrige um telefone errado em vinte arquivos de um site antigo.

O menu vira um arquivo só, e cada página o busca ao carregar.

<!-- em toda página -->
<div data-incluir="parciais/menu.html"></div>

<script>
document.querySelectorAll('[data-incluir]').forEach(async (el) => {
  const r = await fetch(el.dataset.incluir);
  el.innerHTML = await r.text();
  // marca a página atual depois que o menu existe
  const aqui = location.pathname.split('/').pop() || 'index.html';
  el.querySelector(`a[href="${aqui}"]`)?.classList.add('is-atual');
});
</script>

<template> é HTML que o navegador lê mas não mostra, e que você clona quantas vezes quiser. Não resolve o menu entre páginas — resolve o card que se repete dentro de uma página, a partir de uma lista de dados.

<template id="tpl-servico">
  <article class="servico">
    <h3></h3>
    <p></p>
    <a class="cta">Pedir orçamento</a>
  </article>
</template>
<div id="servicos"></div>

<script>
const SERVICOS = [
  { titulo: 'Reforma completa',  texto: 'Do projeto à entrega da obra.' },
  { titulo: 'Interiores',        texto: 'Marcenaria, iluminação e acabamento.' },
  { titulo: 'Consultoria',       texto: 'Uma visita, um diagnóstico, um caminho.' },
];

const tpl = document.querySelector('#tpl-servico');
const destino = document.querySelector('#servicos');

SERVICOS.forEach(s => {
  const no = tpl.content.cloneNode(true);
  no.querySelector('h3').textContent = s.titulo;
  no.querySelector('p').textContent  = s.texto;
  no.querySelector('.cta').href =
    'https://wa.me/5567999999999?text=' + encodeURIComponent('Quero saber sobre ' + s.titulo);
  destino.appendChild(no);
});
</script>

Repare no textContent em vez de innerHTML: com textContent, texto que vem de fora nunca vira código. É a defesa contra XSS embutida no hábito.

É o recurso nativo do navegador para criar sua própria tag. Sem framework, sem build.

class BotaoZap extends HTMLElement {
  connectedCallback() {
    const texto = this.getAttribute('texto') || 'Falar no WhatsApp';
    const msg   = this.getAttribute('mensagem') || 'Olá! Vim pelo site.';
    this.innerHTML = `<a class="cta" target="_blank" rel="noopener"
        href="https://wa.me/5567999999999?text=${encodeURIComponent(msg)}">${texto}</a>`;
  }
}
customElements.define('botao-zap', BotaoZap);

<botao-zap texto="Quero um orçamento"
           mensagem="Vi a página de reforma e quero um orçamento"></botao-zap>

É a resposta certa para a maioria dos sites com mais de cinco páginas, e a que dá mais preguiça de aceitar — porque parece que você está abandonando o HTML puro. Não está: o resultado publicado continua sendo HTML, CSS e JS estáticos. A diferença é que o computador monta as páginas antes de publicar, em vez de o navegador montar depois.

---
import Menu from '../componentes/Menu.astro';
---
<html lang="pt-BR">
<head><title>Movimento</title></head>
<body>
  <Menu atual="movimento" />
  <main>...</main>
</body>
</html>

O menu passa a existir em um arquivo. npm run build gera as dez páginas com o HTML completo dentro. SEO idêntico ao do HTML escrito na mão, porque é HTML escrito na mão — só que escrito uma vez.