boonkgim/setup-project

Configurar um projeto, fatia por fatia

Uma fatia por invocação, através de um loop fixo:

referência → pesquisa → integração → plano → execução → gate local → reconciliação → gate de produção → reconciliação → entregar ao usuário as etapas manuais → commit

Os arquivos slices/ são uma referência, não um script. Eles codificam uma stack que foi verificada como um conjunto e, mais valiosamente, as armadilhas que custam tempo real: o bloco devEngines que pnpm init escreve e que o corepack rejeita, o segundo workspace pnpm create-next-app que abre dentro de apps/web. Esse raciocínio se mantém. As fixações de versão, flags de CLI e formas de API ao redor dele não. Uma fatia executada diretamente da referência falhará em algo que mudou.

Portanto, o plano que você executa nunca é a própria referência. É um plano novo, escrito no projeto para este projeto, a partir da referência mais o que a pesquisa diz que é verdade agora. E porque esse plano é escrito antes de ser comprovado, o loop não termina em um gate verde — ele termina quando o plano foi corrigido para corresponder ao que realmente funcionou, em ambos os lugares onde ele vive, e o usuário recebeu a pequena lista de verificações que apenas uma pessoa pode fazer.

A stack é fixa: pnpm workspace · Next.js no Cloudflare Workers via OpenNext · GraphQL Yoga Worker · Drizzle + Postgres, Docker localmente e Neon através de Hyperdrive em produção · Tailwind + shadcn · opcionalmente Resend, Better Auth e Stripe. Se o usuário quiser uma stack diferente, diga isso claramente — esta habilidade não tem uma.

0. Despacho

/setup-project [fatia] constrói uma fatia. O argumento é opcional e nomeia uma fatia por número ou nome — 01, web shell, database, auth. Resolva-o contra reference/slices.md; se não corresponder a nada, diga isso e liste os nomes ao invés de adivinhar.

ls docs/setup/ 2>/dev/null    # quais fatias este projeto realmente construiu
git status --short            # uma árvore suja significa que a última fatia pode estar incompleta

docs/setup/ é o registro do que foi construído, não uma previsão do que pode ser. Um arquivo de fatia está lá porque essa fatia foi construída e ficou verde. Portanto, o arquivo de número mais alto é a resposta para "onde estamos", e não há nenhum marcador separado para manter em sincronia.

Nenhuma fatia nomeada — sempre mostre o catálogo antes de recomendar. Liste cada fatia de reference/slices.md com seu número, nome e se docs/setup/ mostra que foi construída, então recomende uma e obtenha confirmação antes de executá-la. Isso se aplica também na primeira execução: resolva o nome do projeto (§1) primeiro, então mostre o catálogo (tudo não construído, fatia 00 a seguir) e confirme antes de construí-la. Nunca pule o catálogo ou a confirmação porque o próximo passo parece óbvio.

Estado	O que fazer
Sem docs/setup/	Primeira execução: resolva o nome do projeto (§1), mostre o catálogo, confirme a fatia 00
Fatia nomeada	Construa-a
Nenhuma fatia nomeada	Mostre o catálogo, recomende a fatia mais alta construída + 1, e confirme

A fatia 99 está fora dessa aritmética. Ela é a auditoria de segurança: não constrói nada, precisa apenas da fatia 00 e é reexecutada contra o que existe, ao invés de ocupar um degrau da cadeia. Portanto, 99-security-audit.md em docs/setup/ não significa que a cadeia está terminada, e "mais alta construída + 1" deve ignorá-la — um repositório contendo 00–05 mais 99 é um repositório cuja próxima construção é 06. Ela também é excluída de intervalos --through, porque um intervalo é a cadeia de construção e instalar uma auditoria de fatias que não existem não audita nada. Recomende-a após qualquer fatia que adicione superfície pública, e nomeie-a explicitamente: /setup-project 99.

Nunca construa duas fatias em uma invocação. Pare quando a fatia estiver commitada.

Uma fatia que pula adiante. Se o argumento for mais de um além do que foi construído, nomeie as fatias que ele pula e o que elas constroem, então deixe o usuário decidir. A cadeia é real: 04 precisa tanto de 02 quanto de 03, e 05–07 corrigem arquivos que fatias anteriores escreveram, portanto um pré-requisito ausente é um erro docs:check severo, e não um aviso. reference/slices.md §Dependências tem o raciocínio.

1. Apenas na primeira execução: o nome do projeto

Letras minúsculas, dígitos e hífens — ele se torna o escopo npm (@nome/db) e o prefixo do Worker (nome-web, nome-graphql). Use como padrão o nome do diretório do repositório se ele já se encaixar. Pergunte uma vez; toda fatia posterior lê de volta de package.json.

2. Leia a fatia de referência

Leia slices/NN-*.md por completo antes de qualquer outra coisa, e reference/slices.md para o que o gate desta fatia prova e de qual conta ela precisa. A prosa entre os blocos de código é a parte que mantém seu valor — leia-a pelo raciocínio, e trate todo número de versão, flag e caminho de arquivo nela como uma afirmação a ser verificada, e não como um fato.

Se a fatia precisar de uma conta que o usuário não tem (Cloudflare, Neon, Resend, Stripe), diga isso agora. Uma conta ausente não bloqueia a escrita do plano, mas deixa a fatia pela metade durante seu gate de produção com a metade local já commitada.

Olhe para trás, não para frente. Leia o que o projeto já tem — docs/setup/, CLAUDE.md, os arquivos de habilidade que fatias anteriores escreveram — e siga as convenções que eles estabeleceram para que esta fatia se encaixe ao invés de reinventá-las. O oposto nunca acontece: nenhuma fatia assume uma posterior, nomeada ou não, que será construída — se será ou não é decisão do usuário no despacho (§0), não algo em que a referência pode apostar. Se uma convenção estabelecida agora parecer errada para o que esta fatia precisa, diga isso e deixe o usuário decidir, ao invés de substituí-la silenciosamente ou cumprí-la silenciosamente.

Retire os artefatos provisórios que esta fatia substitui. Algumas coisas são construídas apenas para provar um mecanismo antes de a coisa real existir — packages/mock é o primeiro e mais claro caso: a Fatia 0 o cria para provar o harness quando não há nenhum pacote real para executar através dele. Um artefato provisório nunca nomeia seu sucessor, porque qual fatia o substitui é decidido no despacho (§0), não pela referência. A obrigação funciona de outra forma: cada fatia olha para o que já está lá e incorpora a remoção do que agora torna redundante em seu próprio plano, juntamente com qualquer linha CLAUDE.md que o descrevia.

Portanto, se packages/mock ainda existir, esta fatia é a primeira coisa real que o workspace obtém, e retirá-lo faz parte do trabalho desta fatia. A mesma regra cobre qualquer coisa que fatias posteriores deixarem para trás — um resolvedor estático que um real substitui, um valor de placeholder que se torna uma vinculação.

Esse mecanismo só funciona para artefatos com um sucessor, então declare aqueles sem. packages/mock é retirado porque um pacote real obviamente o substitui. Nada substitui obviamente sendTestEmail: a Fatia 6 adiciona e-mail de verificação real junto com ele, a Fatia 7 o descreve como parte do esquema, e uma mutação não autenticada que envia e-mail real é enviada como um recurso permanente. Nenhuma fatia está errada — a remoção não tem dono. Esperar que uma fatia posterior perceba não é um mecanismo; é uma esperança.

Portanto, toda fatia termina com um bloco Deixa para trás nomeando duas listas, escritas quando o artefato é criado, e não quando alguém o percebe:

• Provisório — o que é, por que existe, e a condição que o retira. Se nenhuma fatia posterior provavelmente atender a essa condição, diga isso na linha. Uma declaração honesta "nada retira isso" é a entrada que faz o trabalho.
• Aceito — um risco assumido conscientemente, quem pode alcançá-lo e o raciocínio. Escrito para que uma fatia posterior possa redecidí-lo ao invés de redescobrí-lo, e para que um padrão herdado (Yoga servindo GraphiQL em produção) seja distinguível de um escolhido.

A Fatia 99 lê estes como uma verificação cruzada — nunca como sua entrada, porque um livro-razão só pode conter o que alguém já pensou em escrever. Ela lê o código primeiro.

3. Pesquise o que é verdade atualmente

Este é o passo que torna a referência segura de usar, então faça-o deliberadamente e de forma barata. Para cada ferramenta que esta fatia instala ou configura, verifique a realidade ao invés da referência:

npm view <pkg> version          # quais devem ser as fixações reais
npx <cli> --help                # flags, e quais prompts são não interativos

Depois, leia a documentação oficial para qualquer coisa da qual a fatia dependa estruturalmente — a orientação atual do adaptador do framework, as flags de compatibilidade do runtime, a forma atual da API de uma biblioteca. Prefira os próprios documentos do fornecedor ao resumo da referência sobre eles, e observe onde eles discordam.

Leia o que a instalação imprime, não apenas seu código de saída. Um pacote que foi incorporado a outro, renomeado ou abandonado ainda instala, ainda exporta os mesmos nomes e ainda compila — npm view <pkg> version informa uma versão saudável para ele, e os blocos de código da referência ficam verdes contra ele. A única linha de [WARN] deprecated … na saída de pnpm add é o único lugar que mostra. A Fatia 5 é onde isso aconteceu: @react-email/components havia sido mesclado em react-email cinco meses antes e nada mais disse isso.

npm view <pkg> deprecated    # não vazio significa que a referência está descrevendo um pacote morto

Escreva o que você encontrou e onde. As contradições entre a referência e os documentos atuais são a saída inteira deste passo, e elas vão para o plano que você está prestes a escrever.

3b. Integre com o que já está construído

Uma fatia que chega desconectada é uma fatia que ninguém pode dizer que está funcionando. Antes de escrever o plano, olhe para o que docs/setup/ diz que existe e pergunte com quais dessas camadas esta fatia agora tem uma conexão — então ofereça-se para provar essa conexão nesta fatia, ao invés de deixá-la para uma fatia posterior que pode nunca ser construída.

Quatro regras impedem que isso se transforme em aumento de escopo:

• Apenas para trás. Conecte-se a fatias já construídas. Nunca especule sobre aquelas que podem nunca existir — essa é a mesma regra do adapting.md de "uma fatia pode citar qualquer fatia anterior a ela, nunca uma posterior a ela".
• Uma sonda, não um recurso. O limite é uma coisa que falharia se a conexão fosse quebrada. Se precisar de decisões de produto, é uma fatia própria, não uma sonda.
• É uma oferta. A conexão amplia a fatia, então ela vai para a revisão §4 com todo o resto e precisa da concordância do usuário.
• Ela ganha uma linha de gate, ou não prova nada.

Uma sonda é um artefato provisório, e a regra do §2 já cobre sua remoção: ela não diz nada sobre o que a substituirá, e qualquer fatia que a substitua a retira.

4. Escreva o plano de execução no projeto

node <dir da habilidade>/scripts/install-plan.mjs \
  --repo <dir do repo> --name <projeto> --slices NN

<dir da habilidade> é onde quer que esta habilidade esteja instalada: ~/.claude/skills/setup-project, ~/.agents/skills/setup-project ou o próprio .claude/skills/setup-project do projeto. O script resolve suas fatias em relação a si mesmo, portanto ele é executado corretamente a partir de qualquer um deles.

Isso renderiza slices/NN-*.md em docs/setup/ com __PROJECT__ e __DOCS__ resolvidos, e não escreve mais nada — nenhum índice, nenhuma lista de fontes. docs/setup/ contém apenas arquivos de fatia, um por fatia construída, e ls é o índice. Nada é instalado, construído ou commitado.

Um arquivo de fatia já existente é deixado em paz a menos que você passe --force, porque nesse ponto é o registro de execução deste projeto, e não uma cópia da referência.

Depois, edite o que ele escreveu, antes de executar qualquer coisa — este é o plano, não uma cópia da referência. Incorpore a pesquisa do §3: corrija as fixações, corrija as flags que mudaram, ajuste os passos cuja API mudou, e remova ou reescreva qualquer coisa que os documentos atuais contradigam. Diga por que na prosa, da mesma forma que o resto do arquivo faz.

Mostre ao usuário o que você mudou em relação à referência e por que, e obtenha concordância antes de executar. O plano não foi comprovado neste ponto e vale um minuto da atenção deles.

5. Execute

Execute os blocos do plano em ordem. As linhas cd são escritas a partir de onde o bloco anterior o deixou, portanto não reordene blocos nem execute um isoladamente.

Espere falhas. Este plano nunca foi executado. Uma falha aqui é o loop funcionando, não o loop quebrando — é exatamente a informação que o §7 existe para capturar. Corrija a causa, anote o que foi e continue.

6. Gates — três rodadas, nesta ordem

Uma fatia é comprovada em três passagens, e elas não são variações de uma coisa. Duas são suas para executar e agir; a terceira é uma transferência. Cada uma das duas primeiras termina corrigindo o plano e esta habilidade (§7) — antes da próxima começar, enquanto o que quebrou ainda está diante de você. Reconciliar uma vez no final, em vez disso, perde as lições locais atrás das lições de produção.

Rodada 1 — automatizada, local

Execute a tabela da Rodada 1 da fatia exatamente como escrita, a partir da coluna Onde que ela nomeia — typecheck e os scripts de teste a partir da raiz do repositório, servidores de desenvolvimento e preview a partir do pacote. Essa divisão não é contabilidade: a raiz distribui scripts através do turbo, portanto ela responde "o workspace está verde?", que é a única pergunta que um gate faz. Execute o mesmo script dentro de um pacote e você obtém o total daquele pacote, que permanece verde enquanto outro pacote queima. Cada pacote fica dois níveis abaixo, então cd ../.. retorna de qualquer um deles — e o corpo da fatia geralmente o deixa no lugar errado, que é por que cada linha nomeia onde é executada.

Execute as linhas na ordem dada: algumas linhas geram o que uma linha posterior precisa. Leia a contagem de testes, não o código de saída — passWithNoTests torna uma execução vazia verde, então Testes N passaram com o N que o gate nomeia é a única evidência. Leia o que os comandos imprimem, não apenas o que eles retornam: um aviso de depreciação é toda a descoberta no pior caso do §3.

Corrija o que falhar, então reconcilie agora (§7) — o documento da fatia do projeto e o desta habilidade, ambos.

Fatias cujo gate ainda é uma única tabela combinada. Apenas algumas fatias passaram por esta forma de três rodadas; as demais carregam uma única tabela misturando b…

… [truncado para tradução]