Construtor de Apps
Uma maneira repetível de levar uma ideia a um aplicativo web implantado, testado e seguro, em qualquer pilha. Foi destilado a partir da construção de um projeto real do início ao fim (uma arena de debate de IA: Next.js, Drizzle, Better Auth, Vercel, Turso, QStash, Vitest, Playwright), incluindo todos os erros cometidos ao longo do caminho. O núcleo (este arquivo, profiles/, reference/) é independente de pilha; o que é específico de um produto ou estrutura fica em stacks/ e é lido apenas por projetos que o utilizam. Siga-o; não improvise o processo.
Comece aqui (a cada sessão)
- Encontre o estado do projeto. Se
docs/plan.mdexistir, leia-o primeiro: ele registra o perfil, as decisões tomadas e o marco atual. Continue a partir daí; não pergunte novamente sobre questões já resolvidas. - Escolha o perfil (apenas para novos projetos). Pergunte uma vez, em palavras simples:
"Você quer se envolver nas escolhas técnicas (código, hospedagem, bancos de dados), ou devo lidar com elas e perguntar apenas sobre o que o aplicativo faz e como ele se parece?"
- Envolvido → leia
profiles/technical.md - Sem intervenção → leia
profiles/guided.mdRegistre a resposta emdocs/plan.mdsob "Como trabalhamos". O perfil decide como você pergunta e explica; o processo e o padrão de qualidade abaixo são os mesmos para ambos.
- Envolvido → leia
- Leia as notas da pilha que o projeto usa (veja "Notas da pilha" abaixo).
- Leia
reference/process.mde siga suas fases em ordem. Carregue as outras referências quando uma fase as apontar, não todas de uma vez.
Notas da pilha
stacks/ contém um arquivo por tecnologia: etapas de configuração, armadilhas e correções aprendidas em projetos reais.
- Quais ler: a seção "Como trabalhamos" do plano as lista ("Notas da pilha: nextjs, vercel, …"). Leia exatamente essas no início de cada sessão. Dê também uma olhada nos manifestos do projeto (
package.json,vercel.json,docker-compose.yml…) e no sistema operacional do usuário: se eles usarem algo com uma nota que o plano não lista, leia-a e adicione-a à lista. Novos projetos escolhem suas notas quando a pilha é definida (fase 2 do processo). - Torne-o impossível de perder: o arquivo de instruções do projeto (
CLAUDE.mdouAGENTS.md, carregado em cada sessão) diz para lerdocs/plan.mde suas notas da pilha no início de cada sessão, qualquer que seja a solicitação. Caso contrário, uma sessão que nunca aciona esta skill nunca verá a lista. A skill vive fora do repositório, então formule-a para degradar graciosamente: o plano é autocontido; as notas da pilha são lidas apenas "se a skill construtor-de-apps estiver instalada". - Antes de adotar um novo serviço ou biblioteca, verifique se existe uma nota.
- Para onde vai uma nova lição: se ela só vale quando se usa um produto, vai na nota desse produto (crie uma se não houver:
stacks/<produto>.md, começando com "Carregar quando…"). Se vale em qualquer lugar, vai emreference/em termos genéricos, com o produto como exemplo e um ponteiro para sua nota. Exemplo: "tentar novamente uma vez quando um serviço remoto abandonar uma conexão ociosa" está emreference/lessons.md; o wrapper de busca libSQL que o faz está emstacks/turso-libsql.md. - As notas registram fatos datados (limites, listas de modelos, preços) conforme aprendidos: verifique-os novamente.
Auditando um projeto existente
Quando solicitado a aplicar esta skill a um projeto que já existe (ou após uma grande mudança), não reinicie o processo; audite e relate:
- Compare
docs/plan.mdcomtemplates/plan.mde liste as seções ausentes. - Percorra
reference/quality-gates.mdseção por seção (segurança, resiliência, desempenho com medições reais e Lighthouse, checklist de UI, acessibilidade em ambos os temas, operações e cotas). - Pesquise o código em busca dos antipadrões em
reference/lessons.mde nas notas da pilha do projeto. - Faça as perguntas iniciais que o projeto nunca respondeu (ex.: ciclo de vida da conta, abuso de cota).
- Relate as lacunas classificadas (lacunas reais, lacunas no plano, baixa prioridade, o que já está bom), com correções. Lacunas que o proprietário recusa vão para a tabela "Riscos aceitos" do plano. Não altere nada até que o proprietário concorde.
Inegociáveis (ambos os perfis)
- Fases e marcos: trabalhe através das fases em
reference/process.md, construindo em pequenos marcos que cada um termina executável, testado, demonstrado e commitado antes do próximo começar. Concorde a lista de marcos com o usuário no início e mantenha-a atualizada emdocs/plan.md. - O aplicativo funciona como pretendido: cada marco termina executável, demonstrado em um navegador real, com o resultado mostrado ao usuário.
- Resiliência: toda dependência externa e processo de longa duração tem uma resposta planejada para "e se falhar?" (lento, limitado, travado no meio, entregue duas vezes), registrada na tabela de modos de falha do plano, tratada no código, visível aos usuários em palavras simples e testada.
- Desempenho: metas acordadas (ex.: páginas respondem em menos de um segundo perto do público), medidas após a implantação; nenhum trabalho obviamente desperdiçado (consultas não indexadas, polling desnecessário, payloads superdimensionados).
- Qualidade: cada marco passa pelos portões em
reference/quality-gates.md(lint, tipos, testes unitários, testes ponta a ponta, build, CI, checklist de revisão de UI). Nenhum defeito importante conhecido é deixado em aberto. - Segurança: o checklist de segurança em
reference/quality-gates.mdvale em cada marco, não como uma passagem final. - Design sustentável: as regras de negócio vivem em módulos simples, sem framework, com testes unitários; os serviços externos ficam atrás de pequenas costuras (um arquivo para trocar); o plano e o README permanecem atualizados.
- Testes no nível certo: testes unitários para regras, testes de navegador ponta a ponta para fluxos de usuário, um simulado com script para qualquer serviço externo pago ou lento (modelos de IA, pagamentos).
- Custo sob controle: o orçamento do usuário está explícito no plano; qualquer coisa que possa custar dinheiro tem um limite, um nível gratuito sem cartão associado ou a própria chave do usuário.
- Segredos nunca passam pelo chat: o usuário coloca segredos em
.env.locale no painel de hospedagem ele mesmo, ou uma integração de marketplace os injeta (vejareference/third-party-setup.md). - Verifique você mesmo primeiro: após uma alteração ou implantação, verifique o resultado você mesmo (o navegador, os logs da plataforma de hospedagem e o status de implantação através de sua CLI, um script de sonda) antes de relatar ou pedir ao usuário para olhar. Peça ao usuário apenas o que precisa dele: login, segredos, dinheiro, aprovações. Verificar a produção você mesmo é como bugs ocultos vêm à tona.
- Relato honesto: diga o que foi verificado e como, o que não foi e o que falhou. Nunca afirme uma verificação que você não executou.
- Verifique fatos que mudam: preços, limites de nível gratuito, APIs de bibliotecas e versões são verificados em relação a fontes atuais (docs em
node_modules, páginas oficiais) antes de confiar neles, e as fontes são citadas.
Arquivos nesta skill
| Arquivo | Use para |
|---|---|
profiles/technical.md | Como trabalhar com um proprietário técnico: o que perguntar, o que decidir e anunciar |
profiles/guided.md | Como trabalhar com um proprietário não técnico: linguagem, escolhas, instruções passo a passo |
reference/process.md | As fases, desde o início até a entrega, com o que cada uma deve produzir |
reference/quality-gates.md | Definição de pronto, estratégia de teste, resiliência, desempenho, segurança e checklists de revisão de UI |
reference/stack-defaults.md | Pilha e arquitetura padrão, níveis de orçamento, quando desviar |
reference/environment.md | Verificação pré-voo e configurações de permissão que removem a maioria das interrupções |
reference/third-party-setup.md | Contas, segredos e configuração de hospedagem/banco de dados/fila com o mínimo de trabalho manual |
reference/lessons.md | Armadilhas concretas já encontradas e suas correções, em termos independentes de pilha. Folheie antes de cada marco |
templates/plan.md | Esqueleto para o docs/plan.md do projeto |
Notas da pilha (leia apenas quando o projeto as usar):
| Arquivo | Abrange |
|---|---|
stacks/nextjs.md | Next.js App Router, Cache Components, proxy, route handlers, server actions, React 19 forms, servidor de desenvolvimento |
stacks/vercel.md | Hospedagem Vercel: regiões, env vars e reimplantações, CLI, logs, configuração de build |
stacks/turso-libsql.md | SQLite/libSQL com Drizzle, Turso: configuração, migrações, fetch remoto, conexões ociosas mortas |
stacks/better-auth.md | Better Auth: confirmação de e-mail, redefinição de senha, vinculação de conta, armadilhas de sessão |
stacks/upstash-qstash.md | Upstash QStash: servidor de desenvolvimento local, assinaturas, atrasos, agendamentos, cota |
stacks/ai-providers.md | Vercel AI SDK, Groq, Google AI Studio, OpenRouter (fluxo de conexão, modelos gratuitos), Ollama |
stacks/gmail-smtp.md | Envio de e-mails da conta através do Gmail sem um domínio |
stacks/playwright.md | Testes ponta a ponta com Playwright: seletores, páginas ocultas, simulações locais |
stacks/github.md | Repositório GitHub, Actions CI, login do GitHub |
stacks/google-oauth.md | Login do Google: projeto Cloud, tela de consentimento, branding, um cliente para local e produção |
stacks/windows.md | Desenvolvendo no Windows: Smart App Control, PowerShell, Docker, CLIs |