Template de projeto que não quebra com o tempo

O problema

Todo projeto começa igual: create-next-app, uma pasta de componentes, o primeiro commit direto na main. Teste "depois". Documentação "quando estabilizar". Regra de arquitetura "quando o time crescer".

Seis meses depois o projeto existe, tem usuário, e você descobre o que ficou pra depois: um CLAUDE.md de dois mil linhas que nenhum agente lê inteiro, dependência circular que ninguém sabe desfazer, componente que importa componente que importa componente, string solta em todo lugar quando surge o segundo idioma, e a pergunta que dói, "isso aqui tem teste?", respondida com silêncio.

Com IA no meio o problema fica mais rápido, não menor. Um agente sem regra escrita inventa a regra a cada sessão. Sem gate, o que ele entrega passa. Sem doc-mapa, ele lê o arquivo errado e reimplementa o que já existe. O código cresce em semanas o que antes crescia em anos, e a dívida junto.

Adicionar tudo isso a um projeto vivo custa uma tarde por item, e uma reunião pra convencer alguém de que vale a pena. Nascer com tudo custa zero.

O que o template faz

É um projeto completo e funcionando, não um esqueleto, que já traz, no primeiro commit, o que projetos de longa vida acumulam em anos:

Uma rede de verificação inteira, ligada. Testes de unidade e de componente com cobertura total exigida, testes de ponta a ponta, teste de mutação (que mede se os testes testam), verificação de arquitetura (nenhum ciclo, nenhuma camada pulando outra), detecção de código morto, contraste de acessibilidade em duas camadas (sobre a paleta e sobre as telas renderizadas), auditoria de dependências, limite de complexidade por função e por arquivo. Um comando roda tudo e diz o que está vermelho. Nada sobe vermelho.

Documentação que um agente consegue usar. O CLAUDE.md é um mapa curto (cabe numa leitura) que aponta para os documentos certos: arquitetura, convenções, checklist de segurança, catálogo de gates, decisões registradas com o trade-off de cada uma (ADRs), especificações antes do código, e um DESIGN.md que fixa a identidade visual em tokens, de onde o CSS nasce. Inclui as quatro regras de trabalho com LLM que separam agente útil de agente que "melhora" o que você não pediu.

O ferramental do agente já configurado. Hooks que impedem o Claude Code de apagar o que não deve, ler segredo ou pular a verificação; skills que dão ritmo ao trabalho (uma para começar uma tarefa isolada, uma para testar, consertar até verde e abrir o PR, uma para especificar antes de codar, uma para revisar UI); a configuração de MCP; e os plugins do dia a dia que deixam o agente terso, preguiçoso no bom sentido e legível para quem tem pouca atenção sobrando.

Dois caminhos de uso, um prompt cada. Aponte o Claude Code para a pasta e diga "crie um projeto novo a partir desse template": ele pergunta nome, destino e identidade visual, monta o projeto, roda a rede inteira até verde e entrega um relatório do que criou. Ou abra o Claude Code no seu projeto atual e diga "melhore meu projeto legado com as boas práticas desse template": ele audita o que você tem contra o padrão, propõe um plano por prioridade, aplica em ondas commitáveis (documentação, ferramental, gates, CI) sem trocar seu framework nem seu runner de teste, e termina com um relatório antes → depois. Toda skill termina com relatório; é regra, não cortesia.

O que vem no pacote

• O código-fonte completo do template, em zip, com tudo que um repositório esconde em arquivos com ponto: .claude/ (hooks, skills, configuração), .mcp.json, .docs/ com 17 decisões registradas, .specs/, .husky/, .github/workflows, configurações de lint, teste, cobertura, mutação, arquitetura e código morto. Sem trava, sem placeholder oculto, sem "versão pro".
• Um app de exemplo que exercita o padrão: landing com formulário, área logada com os três estados de dado (carregando, vazio, preenchido), rotas de API, i18n em dois idiomas, rastreamento de eventos configurado sem vazar dado pessoal.
• CLAUDE.md, AGENTS.md, DESIGN.md e README.md escritos por inteiro.
• Guia de uso: os dois prompts prontos para copiar, o que acontece em cada um, e como ler o relatório final.
• Exemplo de relatório que o agente entrega ao terminar.

Stack do template: Next.js 16, React 19, TypeScript estrito, Tailwind v4, pnpm, Node 24. É a nossa recomendação, não um requisito: o caminho de adaptação respeita a stack que você já tem.

O que NÃO faz

Não é um SaaS pronto: não tem autenticação, banco, cobrança nem painel de admin. É a fundação sobre a qual essas coisas nascem certas, e cada uma delas nasce de uma especificação, com teste, passando pelo gate.

Não substitui julgamento. Os gates barram o que está errado; não decidem o que é certo construir.

Não adapta um projeto legado sozinho num clique. A skill de adaptação faz a auditoria, o plano e as ondas, mas o plano passa por você, e um projeto grande leva mais de uma sessão. Cobertura total, no legado, começa pelo que ganhar teste e cresce arquivo a arquivo. O template é explícito em não fingir o contrário.

Não troca sua stack. Se o seu projeto é Vue, Jest, npm ou Python, o agente recomenda em documento e adapta o padrão ao que existe; ele não reescreve seu código para caber no template.

Precisa de: Claude Code, Node 24, pnpm e uma conta no GitHub (o fluxo de PR usa o gh). Os plugins do dia a dia são gratuitos e o Claude Code oferece instalar ao abrir o projeto.

Atualizações

Quem compra recebe a versão atual e as próximas na mesma página do produto.

• v5 (11/09/2026): Atomic Design deixou de ser regra em prosa e virou gate. Nenhum componente fora dos quatro níveis ou da pasta de componentes da sua feature, nenhuma UI solta ao lado da página. O teste nomeia o arquivo que está no lugar errado, e a skill de adaptar legado ganhou o roteiro de migração em lotes (foi escrito para os cinco projetos auditados, que agora o executam). E o teste de mutação, que mede se os seus testes testam, passou a medir de verdade: três causas de "score zero" falso foram achadas e corrigidas, e a última exigiu fixar a versão do Vitest, com o teste de aceitação escrito para saber quando voltar a subir.
• v4 (11/09/2026): saiu no mesmo dia da v3, por um motivo que merece ser dito. As adoções acharam um defeito real no que estava à venda. A verificação de arquitetura tinha uma régua que nunca casava (um import de React dentro de lógica pura passava em silêncio); está corrigida, com o controle que prova. Junto, o CLAUDE.md deixa de ser mapa por convenção e passa a ser por gate (teto de linhas, nenhuma seção que domine o arquivo, todo link vivo, todo documento indexado), e a skill de adaptar legado ganhou quatro lições novas. Comprador da v1, v2 ou v3 baixa a v4 na mesma página.
• v3 (11/09/2026): o template foi aplicado de verdade nos cinco projetos, por seis sessões de agente em paralelo. O que elas descobriram voltou no mesmo dia: um teste que executa os cinco hooks de segurança (hook que morre no load devolve vazio, e vazio libera tudo em silêncio; já aconteceu), réguas dos hooks que não juntam pedaços de comandos vizinhos nem deixam rm -rf ~/Projetos passar, --max-warnings=0 no lint (variável morta e imagem sem alt commitavam limpos), headers de segurança medidos também na página 404 e na API, e um gotchas.md que deixou de ser vazio: 14 armadilhas medidas, cada uma com sintoma, causa e conserto. A skill de adaptar legado ganhou o que cinco adoções ensinaram sobre cobertura, lint, env e CI.
• v2 (11/09/2026): o template auditou cinco projetos reais (uma comunidade com loja, duas olimpíadas com inscrição paga, um site de produto e um SaaS de imagem). Trouxe de volta o que eles faziam melhor: gate de contraste sobre as telas renderizadas (axe em toda rota, e2e/a11y.spec.ts, com um caso de controle que prova que o scanner enxerga), verificador de tokens que compõe cor com transparência do jeito que o navegador pinta e mantém um ledger de dívida que só encolhe, teste que amarra o .env.example ao schema de ambiente, e a decisão registrada com as alternativas (ADR-0017). Vem com NOVIDADES.md e o caminho para atualizar um projeto criado com a v1 sem recomeçar.
• v1 (10/09/2026): o template completo, o guia de uso com os dois prompts e o exemplo de relatório final.

Pra quem é

Para quem programa há anos, usa LLM no dia a dia e cansou de ver o agente entregar rápido e o projeto cobrar depois: quer engenharia de verdade no que o agente produz, sem escrever a régua à mão em cada repositório. E para quem já entrega com IA e quer a fronteira: o método completo de um monorepo de produção, destilado para caber num projeto só e ser copiado em uma tarde.

Não é para quem está começando a programar. O template pressupõe que você sabe o que é um teste, um PR e um lint, e que quer que o agente respeite isso.