Was macht App Builder?
Ein wiederholbarer Weg, um eine Idee in eine deployed, getestete, sichere Web-App zu verwandeln – auf jedem Stack. Er wurde aus der Entwicklung eines echten Projekts (einer KI-Debattierarena: Next.js, Drizzle, Better Auth, Vercel, Turso, QStash, Vitest, Playwright) destilliert, inklusive aller dabei gemachten Fehler. Der Kern (diese Datei, profiles/, reference/) ist stack-unabhängig; produktspezifische Details leben in stacks/ und werden nur von Projekten gelesen, die sie nutzen. Folge ihm; improvisiere den Prozess nicht.
Start hier (jede Session)
- Finde den Projektstatus. Wenn
docs/plan.mdexistiert, lies es zuerst: Es enthält das Profil, die getroffenen Entscheidungen und den aktuellen Meilenstein. Mache dort weiter; stelle keine bereits geklärten Fragen erneut. - Wähle das Profil (nur für neue Projekte). Frage einmal in einfachen Worten:
"Möchtest du in technische Entscheidungen (Code, Hosting, Datenbanken) eingebunden werden, oder soll ich diese übernehmen und dich nur fragen, was die App tut und wie sie aussieht?"
- Eingebunden → lies
profiles/technical.md - Nicht eingebunden → lies
profiles/guided.mdTrage die Antwort indocs/plan.mdunter "Wie wir arbeiten" ein. Das Profil bestimmt, wie du fragst und erklärst; der Prozess und die Qualitätsstandards sind für beide gleich.
- Eingebunden → lies
- Lies die Stack-Notizen des Projekts (siehe "Stack-Notizen" unten).
- Lies
reference/process.mdund folge seinen Phasen in der Reihenfolge. Lade die anderen Referenzen nur, wenn eine Phase darauf verweist, nicht alle auf einmal.
Stack-Notizen
stacks/ enthält eine Datei pro Technologie: Einrichtungsschritte, Stolperfallen und Lösungen aus echten Projekten.
- Welche lesen: Der Abschnitt "Wie wir arbeiten" im Plan listet sie auf ("Stack-Notizen: nextjs, vercel, …"). Lese genau diese zu Beginn jeder Session. Wirf auch einen Blick auf die Manifeste des Projekts (
package.json,vercel.json,docker-compose.yml…) und das Betriebssystem des Benutzers: Wenn sie etwas verwenden, zu dem es eine Notiz gibt, die der Plan nicht auflistet, lies sie und füge sie zur Liste hinzu. Neue Projekte wählen ihre Notizen, wenn der Stack feststeht (Prozess-Phase 2). - Mach es unübersehbar: Die Projekt-Anweisungsdatei (
CLAUDE.mdoderAGENTS.md, die in jeder Session geladen wird) sagt, dassdocs/plan.mdund seine Stack-Notizen zu Beginn jeder Session gelesen werden sollen, unabhängig von der Anfrage. Sonst sieht eine Session, die diese Fähigkeit nie auslöst, die Liste nie. Die Fähigkeit lebt außerhalb des Repos, also formuliere sie so, dass sie sich anmutig zurückzieht: Der Plan ist in sich abgeschlossen; die Stack-Notizen werden nur gelesen, "wenn die App-Builder-Fähigkeit installiert ist". - Bevor du einen neuen Dienst oder eine Bibliothek einführst, prüfe, ob eine Notiz existiert.
- Wohin eine neue Lektion gehört: Wenn sie nur bei der Verwendung eines Produkts gilt, kommt sie in die Notiz dieses Produkts (erstelle eine, falls keine vorhanden:
stacks/<produkt.md>, beginnend mit "Laden, wenn…"). Wenn sie überall gilt, kommt sie inreference/in allgemeinen Begriffen, mit dem Produkt als Beispiel und einem Hinweis auf die entsprechende Notiz. Beispiel: "Einmal wiederholen, wenn ein entfernter Dienst eine Leerlaufverbindung fallen lässt" steht inreference/lessons.md; der libSQL-Fetch-Wrapper, der dies tut, steht instacks/turso-libsql.md. - Notizen zeichnen datierte Fakten auf (Limits, Modelllisten, Preise) zum Zeitpunkt des Lernens: Überprüfe sie erneut.
Vorhandenes Projekt prüfen
Wenn du gebeten wirst, diese Fähigkeit auf ein bestehendes Projekt anzuwenden (oder nach einer großen Änderung), starte den Prozess nicht neu, sondern prüfe und berichte:
- Vergleiche
docs/plan.mdmittemplates/plan.mdund liste fehlende Abschnitte auf. - Gehe die
reference/quality-gates.mdAbschnitt für Abschnitt durch (Sicherheit, Resilienz, Performance mit echten Messungen und Lighthouse, UI-Checkliste, Barrierefreiheit in beiden Themes, Betrieb und Kontingente). - Durchsuche den Code nach den Anti-Patterns in
reference/lessons.mdund den Stack-Notizen des Projekts. - Stelle die Kickoff-Fragen, die das Projekt nie beantwortet hat (z.B. Account-Lebenszyklus, Kontingentmissbrauch).
- Berichte Lücken, priorisiert (echte Lücken, Plan-Lücken, niedrige Priorität, was bereits gut ist), mit Korrekturen. Lücken, die der Eigentümer ablehnt, kommen in die Tabelle "Akzeptierte Risiken" des Plans. Ändere nichts, bis der Eigentümer zustimmt.
Nicht verhandelbar (beide Profile)
- Phasen und Meilensteine: Arbeite die Phasen in
reference/process.mddurch, baue in kleinen Meilensteinen, die jeweils lauffähig, getestet, demonstriert und committet sind, bevor der nächste beginnt. Stimme die Meilensteinliste mit dem Benutzer beim Kickoff ab und halte sie indocs/plan.mdaktuell. - Die App funktioniert wie beabsichtigt: Jeder Meilenstein endet lauffähig, demonstriert in einem echten Browser, mit dem Ergebnis, das dem Benutzer gezeigt wird.
- Resilienz: Jede externe Abhängigkeit und jeder langlaufende Prozess hat eine geplante Antwort auf die Frage "Was, wenn es scheitert?" (ausgefallen, langsam, ratenbegrenzt, abgestürzt, zweimal zugestellt), festgehalten in der Fehlermodus-Tabelle des Plans, im Code behandelt, für den Benutzer in einfachen Worten sichtbar und getestet.
- Performance: Vereinbarte Ziele (z.B. Seiten antworten innerhalb einer Sekunde in der Nähe des Publikums), gemessen nach dem Deployment; keine offensichtlich ineffiziente Arbeit (nicht indizierte Abfragen, unnötiges Polling, überdimensionierte Payloads).
- Qualität: Jeder Meilenstein besteht die Prüfungen in
reference/quality-gates.md(Lint, Typen, Unit-Tests, End-to-End-Tests, Build, CI, die UI-Review-Checkliste). Kein bekannter schwerwiegender Fehler bleibt offen. - Sicherheit: Die Sicherheits-Checkliste in
reference/quality-gates.mdgilt bei jedem Meilenstein, nicht als endgültiger Durchlauf. - Wartbares Design: Geschäftsregeln leben in einfachen, framework-freien Modulen mit Unit-Tests; externe Dienste sitzen hinter kleinen Schnittstellen (eine Datei zum Austauschen); Plan und README bleiben aktuell.
- Tests auf der richtigen Ebene: Unit-Tests für Regeln, End-to-End-Browser-Tests für Benutzerabläufe, ein skriptierter Fake für jeden kostenpflichtigen oder langsamen externen Dienst (KI-Modelle, Zahlungen).
- Kosten unter Kontrolle: Das Budget des Benutzers ist im Plan explizit; alles, was Geld kosten kann, hat eine Obergrenze, einen kostenlosen Tarif ohne hinterlegte Kreditkarte oder den eigenen Schlüssel des Benutzers.
- Geheimnisse gehen nie durch den Chat: Der Benutzer trägt Geheimnisse selbst in
.env.localund das Hosting-Dashboard ein, oder eine Marketplace-Integration injiziert sie (siehereference/third-party-setup.md). - Überprüfe es zuerst selbst: Überprüfe nach einer Änderung oder einem Deployment das Ergebnis selbst (den Browser, die Logs der Hosting-Plattform und den Deployment-Status über deren CLI, ein Probe-Skript), bevor du berichtest oder den Benutzer bittest, es anzusehen. Frage den Benutzer nur nach Dingen, die ihn erfordern: Anmeldung, Geheimnisse, Geld, Genehmigungen. Die Produktion selbst zu überprüfen ist der Weg, wie versteckte Fehler auftauchen.
- Ehrliche Berichterstattung: Sage, was überprüft wurde und wie, was nicht und was fehlgeschlagen ist. Beantworte keine Prüfung, die du nicht durchgeführt hast.
- Überprüfe Fakten, die sich ändern: Preise, Limits von kostenlosen Tarifen, Bibliotheks-APIs und Versionen werden anhand aktueller Quellen (Dokumentation in
node_modules, offizielle Seiten) überprüft, bevor du dich auf sie verlässt, und die Quellen werden zitiert.
Dateien in dieser Fähigkeit
| Datei | Verwendung |
|---|---|
profiles/technical.md | Wie man mit einem technischen Eigentümer arbeitet: was fragen, was entscheiden und ankündigen |
profiles/guided.md | Wie man mit einem nicht-technischen Eigentümer arbeitet: Sprache, Entscheidungen, Schritt-für-Schritt-Anweisungen |
reference/process.md | Die Phasen, vom Kickoff bis zur Übergabe, mit dem, was jede hervorbringen muss |
reference/quality-gates.md | Definition of Done, Teststrategie, Resilienz, Performance, Sicherheits- und UI-Review-Checklisten |
reference/stack-defaults.md | Standard-Stack und -Architektur, Budgetstufen, wann abweichen |
reference/environment.md | Pre-Flight-Check und Berechtigungseinstellungen, die die meisten Unterbrechungen beseitigen |
reference/third-party-setup.md | Konten, Geheimnisse und Konfiguration von Hosting/Datenbank/Queue mit minimaler manueller Arbeit |
reference/lessons.md | Konkrete Fallstricke, die bereits einmal aufgetreten sind, und ihre Lösungen, in stack-unabhängigen Begriffen. Überfliege vor jedem Meilenstein |
templates/plan.md | Gerüst für die docs/plan.md des Projekts |
Stack-Notizen (nur lesen, wenn das Projekt sie verwendet):
| Datei | Deckt ab |
|---|---|
stacks/nextjs.md | Next.js App Router, Cache Components, Proxy, Route Handler, Server Actions, React 19 Forms, Dev Server |
stacks/vercel.md | Vercel Hosting: Regionen, Umgebungsvariablen und Redeploys, CLI, Logs, Build-Time-Setup |
stacks/turso-libsql.md | SQLite/libSQL mit Drizzle, Turso: Setup, Migrationen, Remote Fetch, tote Leerlaufverbindungen |
stacks/better-auth.md | Better Auth: E-Mail-Bestätigung, Passwort-Reset, Account-Verknüpfung, Session-Stolperfallen |
stacks/upstash-qstash.md | Upstash QStash: lokaler Dev-Server, Signaturen, Verzögerungen, Zeitpläne, Kontingent |
stacks/ai-providers.md | Vercel AI SDK, Groq, Google AI Studio, OpenRouter (Verbindungsablauf, kostenlose Modelle), Ollama |
stacks/gmail-smtp.md | Senden von Account-E-Mails über Gmail ohne eigene Domain |
stacks/playwright.md | Playwright End-to-End-Tests: Selektoren, versteckte Seiten, lokale Fakes |
stacks/github.md | GitHub-Repo, Actions CI, GitHub-Anmeldung |
stacks/google-oauth.md | Google-Anmeldung: Cloud-Projekt, Zustimmungsbildschirm, Branding, ein Client für lokal und Produktion |
stacks/windows.md | Entwicklung unter Windows: Smart App Control, PowerShell, Docker, CLIs |