boonkgim/setup-project

Ein Projekt aufbauen, Schicht für Schicht

Eine Schicht pro Aufruf, in einer festen Schleife:

Referenz → Recherche → Einbinden → Plan → Ausführung → lokales Gate → Abgleich → Produktions-Gate → Abgleich → manuelle Schritte an den Benutzer übergeben → Commit

Die Dateien in slices/ sind eine Referenz, kein Skript. Sie kodieren einen Stack, der als Ganzes verifiziert wurde, und – was wertvoller ist – die Fallstricke, die echte Zeit gekostet haben: der devEngines-Block, den pnpm init schreibt und den corepack dann ablehnt, der zweite pnpm-Workspace, den create-next-app innerhalb von apps/web öffnet. Diese Überlegungen bleiben gültig. Die Versions-Pins, CLI-Flags und API-Strukturen darum herum tun das nicht. Eine direkt aus der Referenz ausgeführte Schicht wird an etwas scheitern, das sich geändert hat.

Der Plan, den Sie ausführen, ist also nie die Referenz selbst. Es ist ein neuer Plan, der für dieses Projekt in das Projekt geschrieben wird, basierend auf der Referenz plus dem, was die Recherche als aktuell gültig ergibt. Und da dieser Plan geschrieben wird, bevor er bewiesen ist, endet die Schleife nicht an einem grünen Gate – sie endet, wenn der Plan korrigiert wurde, um dem zu entsprechen, was tatsächlich funktioniert hat, an beiden Stellen, an denen er lebt, und der Benutzer die kurze Liste der Überprüfungen erhalten hat, die nur ein Mensch durchführen kann.

Der Stack ist festgelegt: pnpm-Workspace · Next.js auf Cloudflare Workers via OpenNext · GraphQL Yoga Worker · Drizzle + Postgres, Docker lokal und Neon durch Hyperdrive in Produktion · Tailwind + shadcn · optional Resend, Better Auth und Stripe. Wenn der Benutzer einen anderen Stack wünscht, sagen Sie das deutlich – dieses Skill hat keinen.

0. Dispatch

/setup-project [slice] baut eine Schicht. Das Argument ist optional und benennt eine Schicht nach Nummer oder Namen – 01, web shell, database, auth. Lösen Sie es gegen reference/slices.md auf; wenn es nichts findet, sagen Sie das und listen Sie die Namen auf, anstatt zu raten.

ls docs/setup/ 2>/dev/null    # welche Schichten dieses Projekt tatsächlich gebaut hat
git status --short            # ein schmutziger Baum bedeutet, dass die letzte Schicht möglicherweise unvollständig ist

docs/setup/ ist die Aufzeichnung dessen, was gebaut wurde, keine Vorhersage dessen, was kommen könnte. Eine Schichtdatei ist dort, weil diese Schicht gebaut wurde und grün war. Die Datei mit der höchsten Nummer ist also die Antwort auf „Wo stehen wir“, und es gibt keinen separaten Marker, der synchron gehalten werden muss.

Keine Schicht benannt – zeigen Sie immer zuerst den Katalog, bevor Sie etwas empfehlen. Listen Sie jede Schicht aus reference/slices.md mit ihrer Nummer, ihrem Namen und ob docs/setup/ sie als gebaut anzeigt auf, empfehlen Sie dann eine und holen Sie eine Bestätigung ein, bevor Sie sie ausführen. Dies gilt auch beim ersten Durchlauf: Klären Sie zuerst den Projektnamen (§1), zeigen Sie dann den Katalog (alles ungebaut, Schicht 00 als nächstes) und bestätigen Sie, bevor Sie diese bauen. Überspringen Sie niemals den Katalog oder die Bestätigung, weil der nächste Schritt offensichtlich erscheint.

Zustand	Was zu tun ist
Kein docs/setup/	Erster Durchlauf: Projektnamen festlegen (§1), Katalog anzeigen, Schicht 00 bestätigen
Schicht benannt	Bauen Sie sie
Keine Schicht benannt	Zeigen Sie den Katalog an, empfehlen Sie die höchste gebaute + 1, und bestätigen Sie

Schicht 99 fällt aus dieser Arithmetik heraus. Es ist das Sicherheitsaudit: Es baut nichts, benötigt nur Schicht 00 und wird gegen das neu ausgeführt, was existiert, anstatt eine Stufe der Kette zu besetzen. Eine 99-security-audit.md in docs/setup/ bedeutet also nicht, dass die Kette abgeschlossen ist, und „höchste gebaute + 1“ muss sie ignorieren – ein Repository mit 00–05 plus 99 ist ein Repository, dessen nächster Bau 06 ist. Es ist auch von --through-Bereichen ausgeschlossen, da ein Bereich die Build-Kette ist und die Installation eines Audits von Schichten, die nicht existieren, nichts prüft. Empfehlen Sie es nach jeder Schicht, die eine öffentliche Oberfläche hinzufügt, und nennen Sie es explizit: /setup-project 99.

Bauen Sie niemals zwei Schichten in einem Aufruf. Stoppen Sie, wenn die Schicht committet ist.

Eine Schicht, die vorspringt. Wenn das Argument mehr als eins über dem liegt, was gebaut ist, nennen Sie die Schichten, die es überspringt, und was sie bauen, und lassen Sie dann den Benutzer entscheiden. Die Kette ist real: 04 benötigt sowohl 02 als auch 03, und 05–07 patchen Dateien, die frühere Schichten geschrieben haben, daher ist eine fehlende Voraussetzung ein harter docs:check-Fehler und keine Warnung. reference/slices.md §Abhängigkeiten enthält die Begründung.

1. Nur beim ersten Durchlauf: der Projektname

Kleinbuchstaben, Ziffern und Bindestriche – es wird der npm-Scope (@name/db) und das Worker-Präfix (name-web, name-graphql). Standardmäßig den Namen des Repository-Verzeichnisses verwenden, wenn dieser bereits passt. Einmal fragen; jede spätere Schicht liest es aus package.json zurück.

2. Die Referenzschicht lesen

Lesen Sie slices/NN-*.md vollständig, bevor Sie etwas anderes tun, und reference/slices.md für das, was das Gate dieser Schicht beweist und welches Konto es benötigt. Der Text zwischen den Codeblöcken ist der Teil, der seinen Wert behält – lesen Sie ihn für die Begründung und behandeln Sie jede Versionsnummer, jedes Flag und jeden Dateipfad darin als eine Behauptung, die zu überprüfen ist, nicht als eine Tatsache.

Wenn die Schicht ein Konto benötigt, das der Benutzer nicht hat (Cloudflare, Neon, Resend, Stripe), sagen Sie das jetzt. Ein fehlendes Konto hindert nicht daran, den Plan zu schreiben, aber es bringt die Schicht auf halbem Weg durch ihr Produktions-Gate mit dem bereits committeten lokalen Teil zum Stillstand.

Schauen Sie zurück, nicht nach vorne. Lesen Sie, was das Projekt bereits hat – docs/setup/, CLAUDE.md, die Skill-Dateien, die frühere Schichten geschrieben haben – und folgen Sie den Konventionen, die sie festgelegt haben, damit diese Schicht hineinpasst, anstatt sie neu zu erfinden. Das Gegenteil passiert nie: Keine Schicht geht von einer späteren aus, ob benannt oder nicht, die jemals gebaut wird – ob das der Fall ist, ist die Entscheidung des Benutzers beim Dispatch (§0), nicht etwas, auf das sich die Referenz verlassen kann. Wenn eine etablierte Konvention jetzt falsch für das erscheint, was diese Schicht benötigt, sagen Sie das und lassen Sie den Benutzer entscheiden, anstatt sie stillschweigend zu überschreiben oder stillschweigend zu befolgen.

Entfernen Sie die provisorischen Artefakte, die diese Schicht ersetzt. Einige Dinge werden nur gebaut, um einen Mechanismus zu beweisen, bevor das eigentliche Ding existiert – packages/mock ist der erste und klarste Fall: Schicht 0 erstellt es, um das Gerüst zu beweisen, wenn es kein echtes Paket gibt, um es durchlaufen zu lassen. Ein provisorisches Artefakt nennt niemals seinen Nachfolger, da welche Schicht es ersetzt, beim Dispatch (§0) entschieden wird, nicht von der Referenz. Die Verpflichtung läuft in die andere Richtung: Jede Schicht schaut, was bereits vorhanden ist, und integriert die Entfernung dessen, was sie jetzt überflüssig macht, in ihren eigenen Plan, zusammen mit allen CLAUDE.md-Zeilen, die es beschrieben haben.

Wenn also packages/mock noch existiert, ist diese Schicht das erste echte Ding, das der Workspace bekommt, und seine Pensionierung ist Teil der Arbeit dieser Schicht. Die gleiche Regel gilt für alles, was spätere Schichten hinterlassen – einen statischen Resolver, den ein echter ersetzt, einen Platzhalterwert, der zu einer Bindung wird.

Dieser Mechanismus funktioniert nur für Artefakte mit einem Nachfolger, also deklarieren Sie die ohne. packages/mock wird in Rente geschickt, weil ein echtes Paket es offensichtlich ersetzt. Nichts ersetzt offensichtlich sendTestEmail: Schicht 6 fügt echte Verifizierungs-Mail daneben hinzu, Schicht 7 beschreibt es als Teil des Schemas, und eine nicht authentifizierte Mutation, die echte Mail sendet, wird als permanentes Feature ausgeliefert. Keine Schicht ist falsch – die Entfernung hat keinen Besitzer. Zu warten, bis eine spätere Schicht es bemerkt, ist kein Mechanismus; es ist eine Hoffnung.

Also endet jede Schicht mit einem Hinterlässt-Block, der zwei Listen benennt, die beim Erstellen des Artefakts geschrieben werden, nicht wenn jemand es bemerkt:

• Provisorisch – was es ist, warum es existiert und die Bedingung, die es in Rente schickt. Wenn keine spätere Schicht diese Bedingung plausibel erfüllen würde, sagen Sie das in der Zeile. Ein ehrliches „nichts ersetzt dies“ ist der Eintrag, der die Arbeit erledigt.
• Akzeptiert – ein bewusst eingegangenes Risiko, wer darauf zugreifen kann, und die Begründung. Aufgeschrieben, damit eine spätere Schicht es neu entscheiden kann, anstatt es wiederzuentdecken, und damit eine geerbte Voreinstellung (Yoga, das GraphiQL in Produktion ausliefert) von einer gewählten unterscheidbar ist.

Schicht 99 liest diese als Querverweis – niemals als seine Eingabe, da ein Hauptbuch nur enthalten kann, was jemand bereits dachte, aufzuschreiben. Es liest zuerst den Code.

3. Recherchieren, was aktuell gültig ist

Dies ist der Schritt, der die Referenz sicher macht, also tun Sie es bewusst und kostengünstig. Für jedes Tool, das diese Schicht installiert oder konfiguriert, überprüfen Sie die Realität und nicht die Referenz:

npm view <pkg> version          # was die Pins tatsächlich sein sollten
npx <cli> --help                # Flags und welche Aufforderungen nicht interaktiv sind

Lesen Sie dann die offizielle Dokumentation für alles, wovon die Schicht strukturell abhängt – die aktuellen Adapter-Richtlinien des Frameworks, die Kompatibilitätsflags der Laufzeit, die aktuelle API-Struktur einer Bibliothek. Bevorzugen Sie die eigene Dokumentation des Anbieters gegenüber der Zusammenfassung der Referenz und notieren Sie, wo sie widersprechen.

Lesen Sie, was die Installation ausgibt, nicht nur ihren Exit-Code. Ein Paket, das in ein anderes integriert, umbenannt oder aufgegeben wurde, installiert sich immer noch, exportiert immer noch die gleichen Namen und kompiliert immer noch – npm view <pkg> version meldet eine gesunde Version dafür, und die Codeblöcke der Referenz werden dagegen grün. Die einzelne Zeile [WARN] deprecated … in der Ausgabe von pnpm add ist der einzige Ort, der es zeigt. Schicht 5 ist, wo das passiert: @react-email/components war fünf Monate zuvor in react-email integriert worden und nichts anderes sagte es.

npm view <pkg> deprecated    # nicht leer bedeutet, dass die Referenz ein totes Paket beschreibt

Schreiben Sie auf, was Sie gefunden haben und wo. Widersprüche zwischen der Referenz und den aktuellen Dokumenten sind das gesamte Ergebnis dieses Schritts und sie gehen in den Plan ein, den Sie gleich schreiben werden.

3b. In das bereits Gebaute einbinden

Eine Schicht, die unverbunden landet, ist eine Schicht, von der niemand sagen kann, ob sie funktioniert. Bevor Sie den Plan schreiben, schauen Sie, was docs/setup/ als existierend angibt, und fragen Sie, mit welchen dieser Schichten diese Schicht jetzt eine Verbindung hat – und bieten Sie dann an, diese Verbindung in dieser Schicht zu beweisen, anstatt sie für eine spätere Schicht zu hinterlassen, die vielleicht nie gebaut wird.

Vier Regeln verhindern, dass dies zu einer Ausweitung des Umfangs führt:

• Nur rückwärts. Verbinden Sie sich mit bereits gebauten Schichten. Spekulieren Sie niemals über solche, die vielleicht nie existieren – das ist die gleiche Regel wie adapting.md's „eine Schicht darf sich auf jede Schicht vor ihr beziehen, niemals auf eine nach ihr“.
• Ein Test, kein Feature. Die Messlatte ist eine Sache, die fehlschlagen würde, wenn die Verbindung unterbrochen wäre. Wenn es Produktentscheidungen erfordert, ist es eine eigene Schicht, kein Test.
• Es ist ein Angebot. Die Verbindung erweitert die Schicht, also geht es in die §4-Überprüfung mit allem anderen und benötigt die Zustimmung des Benutzers.
• Es bekommt eine Gate-Zeile, oder es beweist nichts.

Ein Test ist ein provisorisches Artefakt, und die Regel aus §2 deckt bereits seine Entfernung ab: Sie sagt nichts darüber, was es ersetzen wird, und welche Schicht es ersetzt, pensioniert es.

4. Den Ausführungsplan in das Projekt schreiben

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

<skill dir> ist der Ort, an dem dieses Skill installiert ist: ~/.claude/skills/setup-project, ~/.agents/skills/setup-project oder ein projekteigenes .claude/skills/setup-project. Das Skript löst seine Schichten relativ zu sich selbst auf, sodass es von jedem dieser Orte korrekt läuft.

Das rendert slices/NN-*.md in docs/setup/ mit aufgelösten __PROJECT__ und __DOCS__ und schreibt nichts anderes – kein Index, keine Quellenliste. docs/setup/ enthält nur Schichtdateien, eine pro gebauter Schicht, und ls ist der Index. Nichts wird installiert, gebaut oder committet.

Eine bereits vorhandene Schichtdatei wird unverändert gelassen, es sei denn, Sie übergeben --force, da es sich dann um den Ausführungsdatensatz dieses Projekts und nicht um eine Kopie der Referenz handelt.

Bearbeiten Sie dann, was es geschrieben hat, bevor Sie etwas davon ausführen – das ist der Plan, keine Kopie der Referenz. Integrieren Sie die Recherche aus §3: Korrigieren Sie die Pins, beheben Sie Flags, die sich verschoben haben, passen Sie Schritte an, deren API sich geändert hat, und entfernen oder überschreiben Sie alles, was die aktuellen Dokumente widersprechen. Sagen Sie warum im Text, so wie es der Rest der Datei tut.

Zeigen Sie dem Benutzer, was Sie relativ zur Referenz geändert haben und warum, und holen Sie die Zustimmung ein, bevor Sie ausführen. Der Plan ist an diesem Punkt unbewiesen und eine Minute ihrer Aufmerksamkeit wert.

5. Ausführen

Führen Sie die Blöcke des Plans in der Reihenfolge aus. cd-Zeilen werden von dort geschrieben, wo Sie der vorherige Block zurückgelassen hat, also ordnen Sie Blöcke nicht neu oder führen Sie einen isoliert aus.

Erwarten Sie Fehler. Dieser Plan wurde noch nie ausgeführt. Ein Fehler hier bedeutet, dass die Schleife funktioniert, nicht dass die Schleife bricht – es ist genau die Information, deren Erfassung §7 dient. Beheben Sie die Ursache, notieren Sie, was es war, und machen Sie weiter.

6. Gates – drei Runden, in dieser Reihenfolge

Eine Schicht wird in drei Durchgängen bewiesen, und sie sind keine Variationen einer Sache. Zwei liegen in Ihrer Verantwortung, ausgeführt und darauf reagiert zu werden; der dritte ist eine Übergabe. Jeder der ersten beiden endet damit, den Plan und dieses Skill (§7) zu korrigieren – bevor der nächste beginnt, während das, was kaputt gegangen ist, noch vor Ihnen liegt. Einmal am Ende abzugleichen, verliert die lokalen Lehren hinter den Produktionslehren.

Runde 1 – automatisiert, lokal

Führen Sie die Tabelle von Runde 1 der Schicht genau wie geschrieben aus, von der Spalte Wo, die sie benennt – typecheck und die Testskripte vom Repository-Stammverzeichnis, Entwicklungsserver und preview vom Paket. Diese Aufteilung ist keine Buchhaltung: Der Stamm sendet Skripte über turbo aus, also beantwortet er die Frage „Ist der Workspace grün?“, was die einzige Frage ist, die ein Gate stellt. Führen Sie dasselbe Skript innerhalb eines Pakets aus und Sie erhalten die Aufstellung dieses Pakets, die grün bleibt, während ein anderes Paket brennt. Jedes Paket sitzt zwei Ebenen tiefer, also kehrt cd ../.. von jedem von ihnen zurück – und der Schichtkörper lässt Sie normalerweise an der falschen Stelle, weshalb jede Zeile benennt, wo sie ausgeführt wird.

Führen Sie die Zeilen in der angegebenen Reihenfolge aus: Einige Zeilen generieren, was eine spätere Zeile benötigt. Lesen Sie die Testanzahl, nicht den Exit-Code – passWithNoTests macht einen leeren Durchlauf grün, also sind Tests N bestanden mit dem N, das das Gate benennt, der einzige Beweis. Lesen Sie, was Befehle ausgeben, nicht nur, was sie zurückgeben: Ein Deprecation-Hinweis ist der gesamte Befund im schlimmsten Fall von §3.

Beheben Sie, was fehlschlägt, und gleichen Sie dann sofort ab (§7) – sowohl die Schichtdokumentation des Projekts als auch die dieses Skills.

Schichten, deren Gate immer noch eine kombinierte Tabelle ist. Nur einige Schichten wurden durch diese Dre-Runden-Form gebracht; der Rest trägt eine einzelne Tabelle, die b…

…[truncated for translation]