Estudo de Caso 4: Um Site de Conteúdo que Você Não Precisa Cuidar

A ideia

Um hobbista queria transformar uma pasta de notas em Markdown — resenhas de restaurantes de anos de viagens — em um site público pesquisável, sem CMS para fazer login e sem mensalidade. Adicionar uma nota, dar push, pronto.

A especificação

A static site generated from a folder of Markdown files, one file
per review (title, city, rating, body in frontmatter). Build a
homepage that lists reviews newest-first, a page per review, and
client-side search by city or name. No database, no login, no
build step I have to run by hand. Pushing a new .md file should
publish it.

O requisito escondido está na última frase. "No build step I have to run by hand" (nenhuma etapa de build que eu tenha que rodar na mão) significa que a especificação é na verdade sobre o fluxo de trabalho, não só sobre o resultado — e requisitos de fluxo de trabalho são os que as IAs pulam a menos que você os nomeie, porque eles não aparecem no app em funcionamento.

A stack

Um gerador de site estático que lê Markdown no momento da build, implantado em uma hospedagem CDN com builds acionadas por Git. Push para o repositório, a hospedagem reconstrói, a CDN serve. A busca é do lado do cliente, sobre um pequeno índice JSON gerado na build, então não há servidor nem custo de consulta — uma boa troca com algumas centenas de resenhas, e uma troca deliberada que nomeamos em vez de descobrir.

Todo o fluxo de trabalho é uma única flecha: um push aciona uma build que publica. Nada roda no momento da requisição, exceto o próprio navegador do visitante filtrando um índice:

  add review.md          ┌──────────────────┐
  git push  ───────────▶ │  CDN HOST        │
                         │  build step:     │
                         │  read all *.md   │──▶ static HTML pages
                         │  emit search.json│──▶ tiny search index
                         └────────┬─────────┘
                                  │ serves
                                  ▼
                         ┌──────────────────┐
                         │  VISITOR BROWSER │  filters search.json
                         │  (client-side)   │  locally — no server
                         └──────────────────┘
        no database · no login · no build step run by hand

Os prompts principais

Ancoramos a IA na forma dos dados primeiro, antes de qualquer interface:

Set up a static site that reads every .md file in /reviews. Each
file's frontmatter has title, city, rating (1-5), date. Parse all
of them at build time into a sorted list (newest first) and
generate: a homepage listing them, and one page per review at
/reviews/<slug>. Show me the data-loading code first, before any
styling.

"Before any styling" (antes de qualquer estilo) é uma alavanca deliberada. Peça a coisa toda de uma vez e você recebe uma página bonita conectada a dados nos quais você não pode confiar; peça a camada de dados primeiro e você pode verificar a base antes de um único pixel te distrair. Depois a busca, mantida propositalmente barata:

Generate a search.json at build time with {title, city, slug} for
every review. On the homepage, add a search box that filters the
visible list client-side by matching city or title — no network
calls, just filter the already-loaded index. Keep it under 50
lines of JS.

O obstáculo

A build passava localmente, mas o site implantado dava 404 em cada página de resenha individual. A página inicial funcionava; as páginas de resenha, não. Colamos o sintoma e a configuração em vez de ficar teorizando:

Homepage works live, but /reviews/<slug> pages all 404 in
production while working in local dev. Here's my build output
directory listing and my host's deploy config: [pasted]. Why does
local dev serve these pages but production doesn't?

The AI traced it to the difference between dev-server routing (which
resolves paths dynamically) and static hosting (which serves only
files that physically exist). The build was generating the review
pages into the wrong output folder, so they never got uploaded —
dev had hidden the bug because its router faked the routes that
production couldn't.

Apontamos o diretório de saída para o que a hospedagem realmente implantava, as páginas apareceram, e adicionamos uma linha à checklist de lançamento: clique em um link profundo no site ao vivo, não só na página inicial. A lição mais ampla é que "funciona em dev" e "funciona implantado" são afirmações diferentes, e a exportação estática é exatamente onde elas divergem — servidores de desenvolvimento são tolerantes com rotas de um jeito que hospedagem baseada em arquivos reais nunca é.

O lançamento

Fizemos push de uma resenha real, vimos a hospedagem reconstruir, e carregamos um link profundo para aquela resenha específica no domínio ao vivo — exatamente o caso sobre o qual o dev tinha mentido. Depois pesquisamos pela cidade dela para confirmar que o índice a tinha captado. Adicionar a próxima resenha foi um commit de uma linha, que era todo o objetivo: o lançamento não foi um momento, foi um fluxo de trabalho que continua funcionando sem nós.