boonkgim/setup-project

Configurer un projet, tranche par tranche

Une tranche par invocation, à travers une boucle fixe :

référence → recherche → câblage → plan → exécution → porte locale → réconciliation → porte production → réconciliation → remettre les étapes manuelles à l'utilisateur → commit

Les fichiers slices/ sont une référence, pas un script. Ils encodent une pile qui a été vérifiée en tant qu'ensemble, et — plus précieusement — les pièges qui ont coûté du temps réel : le bloc devEngines que pnpm init écrit et que corepack rejette, le second espace de travail pnpm que create-next-app ouvre à l'intérieur de apps/web. Ce raisonnement reste valable. Les versions figées, les indicateurs CLI et les formes d'API qui l'entourent, non. L'exécution d'une tranche directement à partir de la référence échouera sur quelque chose qui a changé.

Ainsi, le plan que vous exécutez n'est jamais la référence elle-même. C'est un nouveau plan, écrit dans le projet pour ce projet, à partir de la référence plus ce que la recherche dit être vrai maintenant. Et parce que ce plan est écrit avant d'être prouvé, la boucle ne se termine pas à une porte verte — elle se termine lorsque le plan a été corrigé pour correspondre à ce qui a réellement fonctionné, dans les deux endroits où il vit, et que l'utilisateur a reçu la courte liste des vérifications que seule une personne peut effectuer.

La pile est fixe : espace de travail pnpm · Next.js sur Cloudflare Workers via OpenNext · GraphQL Yoga Worker · Drizzle + Postgres, Docker en local et Neon via Hyperdrive en production · Tailwind + shadcn · optionnellement Resend, Better Auth et Stripe. Si l'utilisateur souhaite une pile différente, dites-le clairement — cette compétence n'en a pas.

0. Envoi

/setup-project [tranche] construit une tranche. L'argument est optionnel et nomme une tranche par son numéro ou son nom — 01, web shell, database, auth. Résolvez-le par rapport à reference/slices.md ; s'il ne correspond à rien, dites-le et listez les noms plutôt que de deviner.

ls docs/setup/ 2>/dev/null    # quelles tranches ce projet a réellement construites
git status --short            # un arbre sale signifie que la dernière tranche est peut-être inachevée

docs/setup/ est l'enregistrement de ce qui a été construit, pas une prévision de ce qui pourrait l'être. Un fichier de tranche s'y trouve parce que cette tranche a été construite et est devenue verte. Ainsi, le fichier avec le numéro le plus élevé est la réponse à « où en sommes-nous », et il n'y a pas de marqueur séparé à maintenir synchronisé.

Aucune tranche nommée — montrez toujours le catalogue avant de recommander. Listez chaque tranche de reference/slices.md avec son numéro, son nom, et si docs/setup/ montre qu'elle est construite, puis recommandez-en une et obtenez la confirmation avant de l'exécuter. Cela s'applique également lors de la toute première exécution : réglez d'abord le nom du projet (§1), puis montrez le catalogue (tout ce qui n'est pas construit, tranche 00 ensuite) et confirmez avant de le construire. Ne sautez jamais le catalogue ou la confirmation parce que la prochaine étape semble évidente.

État	Ce qu'il faut faire
Pas de docs/setup/	Première exécution : régler le nom du projet (§1), montrer le catalogue, confirmer la tranche 00
Tranche nommée	Construire la tranche
Aucune tranche nommée	Montrer le catalogue, recommander la plus élevée construite + 1, et confirmer

La tranche 99 est en dehors de cette arithmétique. C'est l'audit de sécurité : elle ne construit rien, n'a besoin que de la tranche 00, et est réexécutée sur ce qui existe plutôt que d'occuper un échelon de la chaîne. Donc le fait que 99-security-audit.md se trouve dans docs/setup/ ne signifie pas que la chaîne est terminée, et « la plus élevée construite + 1 » doit l'ignorer — un dépôt contenant 00–05 plus 99 est un dépôt dont la prochaine construction est 06. Elle est également exclue des plages --through, car une plage est la chaîne de construction et installer un audit de tranches qui n'existent pas n'audite rien. Recommandez-la après toute tranche qui ajoute une surface publique, et nommez-la explicitement : /setup-project 99.

Ne construisez jamais deux tranches en une seule invocation. Arrêtez-vous lorsque la tranche est commitée.

Une tranche qui saute des étapes. Si l'argument est plus d'un pas au-delà de ce qui est construit, nommez les tranches qu'elle saute et ce qu'elles construisent, puis laissez l'utilisateur décider. La chaîne est réelle : 04 a besoin à la fois de 02 et 03, et 05-07 corrigent des fichiers que les tranches précédentes ont écrits, donc un prérequis manquant est une erreur docs:check dure plutôt qu'un avertissement. reference/slices.md §Dépendances contient le raisonnement.

1. Première exécution uniquement : le nom du projet

Lettres minuscules, chiffres et tirets — il devient le scope npm (@nom/db) et le préfixe Worker (nom-web, nom-graphql). Valeur par défaut : le nom du répertoire du dépôt s'il correspond déjà. Demandez une fois ; chaque tranche suivante le lit dans package.json.

2. Lire la tranche de référence

Lisez le fichier slices/NN-*.md complètement avant toute autre chose, et reference/slices.md pour savoir ce que cette tranche prouve et de quel compte elle a besoin. Le texte entre les blocs de code est la partie qui conserve sa valeur — lisez-la pour le raisonnement, et traitez chaque numéro de version, indicateur et chemin de fichier qu'il contient comme une affirmation à vérifier plutôt qu'un fait.

Si la tranche a besoin d'un compte que l'utilisateur ne possède pas (Cloudflare, Neon, Resend, Stripe), dites-le maintenant. Un compte manquant n'empêche pas d'écrire le plan, mais il bloque la tranche à mi-chemin de sa porte de production, la moitié locale étant déjà commitée.

Regardez en arrière, pas en avant. Lisez ce que le projet a déjà — docs/setup/, CLAUDE.md, les fichiers de compétence que les tranches précédentes ont écrits — et suivez les conventions qu'elles ont établies pour que cette tranche s'intègre plutôt que de les réinventer. L'inverse ne se produit jamais : aucune tranche ne suppose qu'une tranche ultérieure, nommée ou non, sera jamais construite — qu'elle le soit ou non relève de la décision de l'utilisateur lors de l'envoi (§0), pas de quelque chose sur quoi la référence peut compter. Si une convention établie semble maintenant erronée pour ce dont cette tranche a besoin, dites-le et laissez l'utilisateur décider plutôt que de la remplacer silencieusement ou de s'y conformer silencieusement.

Mettez à la retraite les artefacts provisoires que cette tranche remplace. Certaines choses sont construites uniquement pour prouver un mécanisme avant que la chose réelle n'existe — packages/mock est le premier cas le plus clair : La tranche 0 le crée pour prouver le harnais quand il n'y a pas de paquet réel à exécuter dedans. Un artefact provisoire ne nomme jamais son successeur, car la tranche qui le remplace est décidée lors de l'envoi (§0), pas par la référence. L'obligation va dans l'autre sens : chaque tranche regarde ce qui est déjà là et intègre la suppression de ce qu'elle rend désormais redondant dans son propre plan, avec toute ligne CLAUDE.md qui le décrivait.

Donc si packages/mock existe encore, cette tranche est la première chose réelle que l'espace de travail reçoit, et la mettre à la retraite fait partie du travail de cette tranche. La même règle couvre tout ce que les tranches ultérieures laissent derrière elles — un résolveur statique qu'un vrai remplace, une valeur d'espace réservé qui devient une liaison.

Ce mécanisme ne fonctionne que pour les artefacts ayant un successeur, alors déclarez ceux qui n'en ont pas. packages/mock est retiré parce qu'un vrai paquet le remplace évidemment. Rien ne remplace évidemment sendTestEmail : la tranche 6 ajoute un véritable e-mail de vérification en parallèle, la tranche 7 le décrit comme faisant partie du schéma, et une mutation non authentifiée qui envoie un véritable e-mail est livrée comme une fonctionnalité permanente. Aucune tranche n'a tort — la suppression n'a pas de propriétaire. Attendre qu'une tranche ultérieure le remarque n'est pas un mécanisme ; c'est un espoir.

Donc, chaque tranche se termine par un bloc Laisse derrière nommant deux listes, écrites lorsque l'artefact est créé plutôt que lorsque quelqu'un le repère :

• Provisoire — ce que c'est, pourquoi cela existe, et la condition qui le retire. Si aucune tranche ultérieure ne remplirait plausiblement cette condition, dites-le dans la ligne. Une entrée honnête « rien ne retire cela » est celle qui fait le travail.
• Accepté — un risque pris en connaissance de cause, qui peut y accéder, et le raisonnement. Écrit pour qu'une tranche ultérieure puisse le redécider plutôt que de le redécouvrir, et pour qu'une valeur par défaut héritée (Yoga servant GraphiQL en production) soit distinguable d'une valeur choisie.

La tranche 99 les lit comme une vérification croisée — jamais comme son entrée, car un registre ne peut contenir que ce que quelqu'un a déjà pensé à écrire. Elle lit d'abord le code.

3. Rechercher ce qui est vrai actuellement

C'est l'étape qui rend la référence sûre à utiliser, alors faites-la délibérément et à moindre coût. Pour chaque outil que cette tranche installe ou configure, vérifiez la réalité plutôt que la référence :

npm view <pkg> version          # ce que les versions figées devraient réellement être
npx <cli> --help                # les indicateurs, et quelles invites sont non interactives

Lisez ensuite la documentation officielle pour tout ce dont la tranche dépend structurellement — les conseils actuels de l'adaptateur du framework, les indicateurs de compatibilité du runtime, la forme actuelle de l'API d'une bibliothèque. Préférez la documentation du fournisseur au résumé qu'en fait la référence, et notez les points de désaccord.

Lisez ce que l'installation affiche, pas seulement son code de sortie. Un paquet qui a été intégré dans un autre, renommé ou abandonné s'installe toujours, exporte toujours les mêmes noms et compile toujours — npm view <pkg> version signale une version saine pour lui, et les blocs de code de la référence deviennent verts avec lui. La ligne unique de [AVERTISSEMENT] obsolète … dans la sortie de pnpm add est le seul endroit où cela apparaît. La tranche 5 est là où cela a mordu : @react-email/components avait été fusionné dans react-email cinq mois plus tôt et rien d'autre ne le disait.

npm view <pkg> deprecated    # non vide signifie que la référence décrit un paquet mort

Notez ce que vous avez trouvé et où. Les contradictions entre la référence et la documentation actuelle constituent l'intégralité de la sortie de cette étape, et elles vont dans le plan que vous êtes sur le point d'écrire.

3b. Câbler dans ce qui est déjà construit

Une tranche qui atterrit déconnectée est une tranche dont personne ne peut dire qu'elle fonctionne. Avant d'écrire le plan, regardez ce que docs/setup/ dit exister et demandez avec quelles couches cette tranche a maintenant une interface — puis proposez de prouver cette interface dans cette tranche plutôt que de la laisser pour une tranche ultérieure qui ne sera peut-être jamais construite.

Quatre règles empêchent que cela ne se transforme en dérive de périmètre :

• Uniquement en arrière. Câblez dans les tranches déjà construites. Ne spéculez jamais sur celles qui n'existeront peut-être jamais — c'est la même règle que le « adaptant.md » : « une tranche peut citer toute tranche avant elle, jamais une après elle ».
• Une sonde, pas une fonctionnalité. La barre est une chose qui échouerait si l'interface était cassée. Si cela nécessite des décisions sur le produit, c'est une tranche en soi, pas une sonde.
• C'est une offre. Le câblage élargit la tranche, donc il va dans la revue du §4 avec tout le reste et nécessite l'accord de l'utilisateur.
• Cela obtient une ligne de porte, ou cela ne prouve rien.

Une sonde est un artefact provisoire, et la règle du §2 couvre déjà sa suppression : elle ne dit rien sur ce qui le remplacera, et la tranche qui le remplace le retire.

4. Écrire le plan d'exécution dans le projet

node <skill dir>/scripts/install-plan.mjs \
  --repo <repo dir> --name <project> --slices NN

<skill dir> est l'endroit où cette compétence est installée : ~/.claude/skills/setup-project, ~/.agents/skills/setup-project, ou le propre .claude/skills/setup-project d'un projet. Le script résout ses tranches par rapport à lui-même, donc il s'exécute correctement depuis n'importe lequel d'entre eux.

Cela transforme slices/NN-*.md en docs/setup/ avec __PROJECT__ et __DOCS__ résolus, et n'écrit rien d'autre — pas d'index, pas de liste de sources. docs/setup/ ne contient que des fichiers de tranche, un par tranche construite, et ls est l'index. Rien n'est installé, construit ou commité.

Un fichier de tranche déjà présent est laissé intact à moins que vous ne passiez --force, car à ce moment-là, c'est le enregistrement d'exécution de ce projet plutôt qu'une copie de la référence.

Modifiez ensuite ce qu'il a écrit, avant d'exécuter quoi que ce soit — c'est le plan, pas une copie de la référence. Intégrez la recherche du §3 : corrigez les versions figées, corrigez les indicateurs qui ont changé, ajustez les étapes dont l'API a changé, et supprimez ou réécrivez tout ce que la documentation actuelle contredit. Dites pourquoi dans le texte, comme le reste du fichier le fait.

Montrez à l'utilisateur ce que vous avez changé par rapport à la référence et pourquoi, et obtenez son accord avant d'exécuter. Le plan n'est pas prouvé à ce stade et mérite une minute de son attention.

5. Exécuter

Exécutez les blocs du plan dans l'ordre. Les lignes cd sont écrites à partir de l'endroit où le bloc précédent vous a laissé, donc ne réorganisez pas les blocs et n'en exécutez pas un isolément.

Attendez-vous à des échecs. Ce plan n'a jamais été exécuté. Un échec ici est le fonctionnement de la boucle, pas la rupture de la boucle — c'est exactement l'information que le §7 existe pour capturer. Corrigez la cause, notez ce qu'elle était, et continuez.

6. Portes — trois tours, dans cet ordre

Une tranche est prouvée en trois passes, et elles ne sont pas des variations sur une seule chose. Deux sont à vous de les exécuter et d'agir en conséquence ; la troisième est un transfert. Chacune des deux premières se termine par la correction du plan et de cette compétence (§7) — avant que la suivante ne commence, pendant que ce qui s'est cassé est encore devant vous. Réconcilier une seule fois à la fin perd les leçons locales derrière celles de la production.

Tour 1 — automatisé, local

Exécutez le tableau du Tour 1 de la tranche exactement comme écrit, à partir de la colonne Où qu'il nomme — typecheck et les scripts de test depuis la racine du dépôt, les serveurs de développement et preview depuis le paquet. Cette division n'est pas une tenue de livres : la racine répartit les scripts via turbo, donc elle répond à « l'espace de travail est-il vert », qui est la seule question qu'une porte pose. Exécutez le même script à l'intérieur d'un paquet et vous obtenez le décompte de ce paquet, qui reste vert alors qu'un autre paquet brûle. Chaque paquet se trouve à deux niveaux de profondeur, donc cd ../.. revient de n'importe lequel d'entre eux — et le corps de la tranche vous laisse généralement au mauvais endroit, c'est pourquoi chaque ligne nomme où elle s'exécute.

Exécutez les lignes dans l'ordre donné : certaines lignes génèrent ce dont une ligne ultérieure a besoin. Lisez le nombre de tests, pas le code de sortie — passWithNoTests rend une exécution vide verte, donc Tests N passed avec le N que la porte nomme est la seule preuve. Lisez ce que les commandes affichent, pas seulement ce qu'elles retournent : un avis d'obsolescence est la découverte totale dans le pire cas du §3.

Corrigez ce qui échoue, puis réconciliez maintenant (§7) — à la fois le document de tranche du projet et celui de cette compétence.

Tranches dont la porte est encore un tableau combiné. Seules certaines tranches ont traversé cette forme à trois tours ; les autres portent un seul tableau mélangeant des entrées automatisées et manuelles. Chaque fois que vous en rencontrez un, divisez-le en tours pendant la rédaction du plan (étape 4) : déplacez les lignes automatisées vers le Tour 1, les lignes manuelles vers le Tour 3, et laissez le Tour 2 vide. L'engagement d'une porte est de prouver que la tranche fonctionne dans un environnement de production, ce qui signifie que la façon dont vous prouvez cela dépend du fait que vous puissiez ou non réellement déployer. Parfois, vous ne pouvez pas — et dans ce cas, une porte de production qui n'a rien à vérifier est une porte que vous déplacez vers les @@books des tours suivants, pas une porte que vous prétendez avoir franchie.

Tour 2 — automatisé, production

Ce tour exécute les mêmes vérifications que le Tour 1, mais contre une URL live. Il ne diffère du premier que par la cible de l'assertion — l'URL de déploiement, pas localhost — et par ce qu'il prouve : le Tour 1 prouve que l'application se compile et s'exécute ; le Tour 2 prouve qu'elle compile et s'exécute derrière les limites réelles que la production impose — les délais d'attente de l'adaptateur, la taille de la charge utile de Workers, la version du runtime globale. L'état réel du compte est ce qui détermine comment exécuter ce tour : si l'utilisateur possède déjà un compte Neon provisionné avec sa première base de données, le pipeline complet de déploiement est disponible, et la porte s'exécute complète. Si le compte est nouveau et vide, la porte ne peut pas encore s'exécuter, donc elle est marquée comme différée et signalée comme une tâche prête lorsque le compte est prêt.

Tour 3 — manuel, transfert

Listez exactement ce que l'utilisateur doit vérifier avec un navigateur et des yeux humains, et comment le vérifier. C'est une liste de sélecteurs CSS à inspecter, de payloads à coller dans GraphiQL, de logs de déploiement à parcourir. Ne dites pas « vérifier que cela fonctionne » — dites ce qui compte comme preuve pour chaque élément et donnez la commande ou l'URL qui la produit.

7. Réconcilier dans la source de la compétence

Chaque correction que vous avez apportée au plan pendant les §5-6 est également une correction que la référence de cette compétence a besoin. Et l'endroit où elle va est déterminé par ce qu'elle corrige :

• Le fichier de tranche lui-même, si le plan du projet s'écartait de l'ordre de ses blocs, sautait une étape ou fusionnait ce que la référence séparait. La référence a une forme que chaque exécution prouve et peaufine ; une modification qui ne conserve pas cette forme appartient au plan du projet, pas ici.
• reference/slices.md, pour tout ce qui concerne la façon dont cette tranche se connecte aux autres : un prérequis qui s'est avéré plus tôt qu'indiqué, une dépendance de structure de données qui n'était pas encore écrite, une convention de nommage ou de dossier que le plan du projet a établie et que les tranches ultérieures doivent connaître.
• La section Leaves behind du fichier de tranche, si le plan du projet a créé un artefact provisoire ou accepté un risque qui n'a pas été anticipé. C'est la même règle que §2 — écrivez-le maintenant, pas quand quelqu'un trébuche dessus.

Le projet lui-même contient déjà ses corrections dans docs/setup/NN-*.md — c'est ce que vous avez prouvé. La correction que vous écrivez ici est ce que la tranche suivante verra lorsqu'elle lira la référence, donc elle est écrite exactement comme la référence l'était : prose au-dessus des blocs de code qui captent le raisonnement, les blocs de code montrant ce qui a fonctionné. Le dossier de la compétence est le dossier du projet plus généralisé, donc les chemins, les noms de comptes et les valeurs de configuration spécifiques au projet n'ont pas leur place ici — remplacez-les par des espaces réservés __PROJECT__ et __DOCS__, et supprimez les adresses e-mail réelles et les UUID de base de données.

N'écrivez jamais une correction qui n'a pas été exécutée. Si vous avez contourné un problème au lieu de le corriger — car l'utilisateur utilisait macOS et que la correction était pour Linux, ou parce que le correctif complet aurait nécessité de refactorer ce que la tranche suivante de toute façon remplace — notez le contournement ici pour que la référence le sache, mais n'écrivez pas le correctif comme si vous l'aviez prouvé. Une ligne commençant par // NON PROUVÉ dans un commentaire de bloc de code (ou un bloc de devis > NON PROUVÉ dans une prose en dehors d'un bloc de code) le rend clair, et la tranche suivante peut décider de le prouver ou de le laisser.

8. Engagement

git add -A && git commit -m "tranche NN · nom-de-la-tranche" et terminez par un résumé de ce que cette tranche a construit, ce qu'elle a laissé non prouvé, et quelles sont les prochaines étapes évidentes — y compris 99-security-audit.md si la tranche a touché une surface publique.

Le fichier Leaves behind d'une tranche

Chaque tranche se termine par un bloc nommé Leaves behind dans son fichier de plan de projet. C'est une section qui documente les artefacts provisoires et les risques acceptés créés par cette tranche, écrits à la création plutôt que d'être découverts plus tard. Le format est :

### Laisse derrière

**Provisoire**

| Artefact | Raison | Retiré par |
| -------- | ------ | ---------- |
| `packages/mock` | Prouve le harnais avant qu'un vrai paquet n'existe | La première tranche qui ajoute un vrai paquet d'application |
| `sendTestEmail` | … | Rien — muté en fonctionnalité permanente |

**Accepté**

| Risque | Accès | Raisonnement |
| ------ | ----- | ------------ |
| GraphiQL activé en production | Toute personne disposant de l'URL de l'API | Pratique pour le débogage ; la clé API réelle n'est pas exposée via GraphiQL |

La tranche 99 agit comme un chien de garde : elle lit ces tableaux comme une liste de contrôle de choses à examiner, pas comme une liste définitive. La section Accepté est particulièrement importante car elle formalise les décisions de conception prises consciemment, les distinguant des valeurs par défaut héritées qui peuvent ou non convenir.