kikita-labs/kikita-create-nestjs-app

Was macht kikita-create-nestjs-app?

Richtet ein neues NestJS-Projekt ein und generiert dessen AGENTS.md-/.agents/-Dokumentationsbaum, sodass jeder KI-Agent (Claude Code, Codex usw.), der später im Projekt arbeitet, eine vollständige, selbstwartende Wissensbasis vorfindet.

0. Moduserkennung (immer zuerst durchführen)

Prüfe im Zielverzeichnis auf .agents/.kikita-scaffold.json.

• Fehlt → Neuinstallation. Fahre mit Abschnitt 1 unten fort, dann plan.md.
• Vorhanden → Dieses Projekt wurde bereits von diesem Skill gerüstet. Folge stattdessen update.md – führe den Fragebogen nicht erneut durch und erstelle kein neues Gerüst. update.md übernimmt das Einspielen der neuesten Vorlage, das Vergleichen seit dem aufgezeichneten Commit und das Einarbeiten von Änderungen in die (möglicherweise angepassten) .agents/-Dateien des Projekts.

0.5 Voraussetzungen (nur bei Neuinstallation)

• Bestätige, dass das Arbeitsverzeichnis leer ist oder der Nutzer hier ausdrücklich initialisieren möchte.
• Führe dies niemals gegen ein Verzeichnis aus, das bereits ein nicht zusammenhängendes Projekt enthält, ohne vorher nachzufragen.

1. Fragebogen (immer vor dem Ändern des Dateisystems fragen)

Befolge plan.md Schritt für Schritt ab hier. Überspringe den Fragebogen nicht. Wenn du fertig bist, durchlaufe checklist.md, bevor du dem Nutzer mitteilst, dass alles erledigt ist.

Frage in zwei Schritten, nicht als 12 auf einmal gestellte Fragen – die erste Antwort bestimmt, welche der späteren Fragen überhaupt relevant sind, sodass alle auf einmal zu stellen bedeutet, einem Nur-Bot-Nutzer eine „Authentifizierung für deine REST-API“-Frage zu präsentieren, die nicht auf ihn zutrifft.

Schritt 1 – Die Verzweigungsfrage allein:

1. Anwendungstyp: REST-API, Bot oder beides in derselben App?
   • Wenn Bot (oder beides): welche Plattform? Telegram (nestjs-telegraf) oder Discord – und für Discord speziell ist necord die empfohlene Standardbibliothek (am wenigsten Klebecode, um das generische Ereignis→Handler→Service-Muster über natives Nest-DI/Guards/Pipes zu erfüllen), aber nicht zwingend: wenn der Nutzer stattdessen discord.js wünscht (vorhandenes Team-Know-how, ein discord.js-Feature, das necord noch nicht einkleidet), ist das eine legitime Wahl – behandele es genauso wie „andere Plattform“ unten, passe das generische Muster von Hand an, anstatt es kostenlos zu erhalten.
   • Jede andere Plattform/Bibliothek (benenne sie – das generische Bot-Transportmuster in architecture/transport-adapter.md passt sich an, aber der konkrete Adaptercode muss für alles außerhalb von nestjs-telegraf/necord von Hand geschrieben werden).

Schritt 2 – Alles andere, gebündelt (Frage 3 wird nur gestellt, wenn Schritt 1 REST oder „beides“ ergeben hat; jede weitere Frage unten gilt unabhängig vom Anwendungstyp):

2. Tests: keine oder Unit- / e2e-Tests (Supertest) / beides? „Beides“ bindet auch Testcontainer für Integrationstests ein, die eine echte Postgres-Instanz anstelle von Mocks verwenden.
3. Authentifizierung (überspringe dies vollständig, wenn Schritt 1 „Nur Bot“ war): erforderlich oder nicht? Ein „Ja“ erstellt ein einziges festgelegtes, kampferprobtes Muster, kein Menü – siehe core/auth.md-Gerüstblock: kurzlebiges Zugriffstoken (5–15 Min., niemals in einem Cookie) + Refresh-Token in einem httpOnly-Cookie mit Geltungsbereich /auth/refresh + Rotation (Einmalnutzung, gehasht in der DB) + csrf-csrf auf dem Refresh-Endpunkt + argon2id-Passwort-Hashing + einen RolesGuard. Biete keine Alternativen an (Sessions, reines JWT ohne Rotation) – dies ist die eine Standardeinstellung.
4. Hintergrund-Jobs: BullMQ (Redis-basierte Warteschlangen) oder nicht?
5. Caching: @nestjs/cache-manager + @keyv/redis (Cache-Aside) oder nicht? Standardmäßige Empfehlung ist nein – füge es hinzu, wenn ein echter Leistungsbedarf besteht, nicht spekulativ bei jedem CRUD-Endpunkt.
6. Datei-Uploads: erforderlich oder nicht? Wenn ja, keine weitere Unterfrage – der Speicheranbieter (lokale Festplatte in der Entwicklung, beliebiger S3-kompatibler Bucket in der Produktion: AWS S3, MinIO, R2, Spaces) ist eine Umgebungsvariable, keine Gerüst-Auswahl.
7. Asynchrone Nachrichtenübertragung / ereignisübergreifende Dienste: erforderlich oder nicht? Wenn ja, auch keine Broker-Unterfrage – RabbitMQ ist die festgelegte Standardbibliothek (Aufgabenwarteschlangen, Routing, DLQ decken die überwältigende Mehrheit der Anwendungsfälle ab). architecture/messaging.md dokumentiert Kafka als späteren Migrationspfad für Event-Streaming/Wiederholung/Höchstdurchsatz-Anforderungen, nicht als Gerüst-Option.
8. i18n: Benötigt dieses Projekt mehrere Gebietsschemata – übersetzte REST-Fehler-/Validierungsmeldungen und/oder Bot-Antworten in mehr als einer Sprache? Wenn ja, keine weitere Unterfrage – nestjs-i18n ist die festgelegte Bibliothek; die Gebietsschema-Auflösung unterscheidet sich je nach Transport (REST: Accept-Language-Header; Bot: das plattformeigene, benutzerspezifische Gebietsschema-Feld, niemals Accept-Language) und beides wird in core/i18n.md behandelt. Wenn nein, überspringe – ein Projekt, das nur in einer Sprache laufen wird, benötigt dies nicht.
9. JSDoc/TSDoc für die öffentliche API: Erzwinge obligatorische Dokumentationskommentare für jedes exportierte Symbol oder überspringe es? Steuert, ob .agents/agent-surface.md generiert wird (empfohlene Standardeinstellung: ja).
10. Git-Richtlinie: Darf der Agent ohne Rückfrage committen und pushen, oder muss jeder Commit/Push bestätigt werden?
11. Paketmanager: npm, pnpm oder yarn? Standardempfehlung: pnpm.
12. Git-Remote: Hat der Nutzer bereits eine Repo-URL zum Pushen? Wenn ja, zeichne sie auf – git remote add origin <url> wird direkt nach git init ausgeführt (siehe plan.md). Wenn keine URL angegeben wird, überspringe dies; der Nutzer richtet das Remote später selbst ein.

Zeichne jede Antwort auf – sie steuern sowohl das Gerüst als auch, welche Dokumentdateien generiert werden. Gehe niemals stillschweigend über das oben ausdrücklich Festgelegte hinaus von einem Standard aus; wenn der Nutzer eine Frage überspringt, frage für diese eine Frage erneut nach. Dieser Skill zielt auf ein einzelnes NestJS-Projekt ab, nicht auf ein Monorepo/Nx-Workspace und nicht auf eine dezentrale Microservices-Topologie (mehrere bereitstellbare Dienste/Repositories) – wenn der Nutzer etwas davon möchte, sage, dass dieser Skill das nicht abdeckt, und stoppe, anstatt zu improvisieren. Ein Nachrichtenbroker (siehe Frage 7) bindet nur eine Hybrid-App (app.connectMicroservice() innerhalb derselben einzelnen App) – er startet niemals einen zweiten Dienst.

Feste Standardeinstellungen – frage niemals nach diesen, sie sind vom Design her festgelegt:

• ORM/DB: Prisma + Postgres. Kein TypeORM (für neue Projekte nicht empfohlen), kein Drizzle (Nischen- Leistungs-/Grenzfall), kein NoSQL/MongoDB-Zweig in v1 dieses Skills.
• Validierung: class-validator + class-transformer auf der HTTP-Ebene, globaler ValidationPipe in main.ts bedingungslos mit whitelist, forbidNonWhitelisted, forbidUnknownValues und transform alle auf true aktiviert. Zod für die Umgebungs-/Konfigurationsvalidierung (@nestjs/config + validate), erzwungen durch eine ESLint-Regel, die direkte process.env-Zugriffe außerhalb der Schema-Datei blockiert – siehe testing-and-quality.md's „Mechanisch erzwungene Regeln“. Verschachtelte DTO-Felder erfordern sowohl @ValidateNested() als auch @Type(() => NestedDto) – siehe code-style/dto-and-validation.md. DTO-Wiederverwendung über PartialType/OmitType/PickType, importiert aus @nestjs/swagger, niemals aus @nestjs/mapped-types – ESLint-blockiert, nicht nur dokumentiert (gleicher Abschnitt).
• Antwortform: Ein globaler ClassSerializerInterceptor + @Exclude() auf DTO-Feldern ist der eine feste Serialisierungsmechanismus – niemals eine rohe Prisma-Entität zurückgegeben, niemals ein zweiter Serialisierungsansatz ohne eine ADR eingeführt.
• Swagger/OpenAPI: immer für den REST-Zweig eingerichtet.
• CORS: immer in main.ts über eine umgebungsgesteuerte Ursprungs-Zulassungsliste konfiguriert, niemals *.
• API-Versionierung: Nest-URI-Versionierung (/v1/...), festgelegt in architecture/transport-adapter.md.
• Rate-Limiting: @nestjs/throttler immer installiert für REST und/oder Bot, IP-basiert für REST- Routen, Benutzer-/Chat-ID-basiert für Bot-Handler – niemals als „noch nicht benötigt“ übersprungen.
• Logging: nestjs-pino, immer – strukturierte JSON-Logs, keine einfache Logger-Option angeboten.
• Health Checks: @nestjs/terminus, immer eingerichtet, nicht durch den Fragebogen gated – zwei separate Routen, GET /health/live (nur Prozess, keine externen Prüfungen) und GET /health/ready (Prisma + beliebige ausgewählte Redis/RabbitMQ-Abhängigkeit), niemals zu einer zusammengeführt. Siehe core/health.md.
• Sanftes Herunterfahren: app.enableShutdownHooks() immer in main.ts aufgerufen – ohne dies wird der OnModuleDestroy-Verbindungsschließungs-Hook von Prisma bei einem Container-Neustart niemals ausgelöst.
• Prisma-Fehlerzuordnung: Ein globaler PrismaExceptionFilter (APP_FILTER) bildet PrismaClientKnownRequestError-Codes auf die passende Nest-HTTP-Ausnahme ab – ein Prisma-Fehler tritt niemals als roher, unbehandelter 500-Fehler auf.
• Prisma-Client-Generierung: package.json erhält immer "postinstall": "prisma generate" – der generierte Client wird in .gitignore ausgeschlossen, sodass ein frischer Clone/CI dies benötigt, um überhaupt zu kompilieren.
• docker-compose.yml: immer generiert (nur für Entwicklung/Tests, niemals von der Produktionsbereitstellung referenziert) – Postgres immer vorhanden; Redis wird nur hinzugefügt, wenn BullMQ und/oder Caching ausgewählt wurde (eine gemeinsame Instanz für beide); RabbitMQ wird nur hinzugefügt, wenn Nachrichtenübertragung ausgewählt wurde.

2. Generieren

Befolge plan.md. Kopiere Dateien aus templates/ in das Zielprojekt, einschließlich der Punktdateien (.gitignore, .gitattributes, .editorconfig, .prettierrc, .prettierignore, .nvmrc, .vscode/extensions.json, .env.example, docker-compose.yml).

Mit den Antworten aus dem Fragebogen werden zwei verschiedene Dinge gemacht. Vermische sie nicht:

• Textplatzhalter – suche und ersetze jedes {{TOKEN}} durch den tatsächlichen Wert, lasse keine zurück: {{PROJECT_NAME}}, {{APP_TYPE}}, {{BOT_PLATFORM}}, {{TESTS}}, {{GIT_POLICY}}, {{PACKAGE_MANAGER}}, {{NODE_VERSION}}, {{DATE}}.
• Einbindungsgatter – Antworten zu Anwendungstyp, Bot-Plattform, Tests, Authentifizierung, Warteschlange, Cache, Speicher, Nachrichten, i18n und obligatorischem TSDoc füllen keinen Platzhalter; sie entscheiden, ob eine gesamte Datei (oder ein mit <!-- SCAFFOLD --> markierter Block darin) überhaupt kopiert wird. Ein „Nein“ bedeutet, dass die Datei/der Block gelöscht wird, nicht mit einer leeren Zeichenkette gefüllt wird. Gatterdateien müssen dennoch von AGENTS.md / dem entsprechenden README verlinkt werden, wenn sie behalten werden, und ihre Links müssen entfernt werden, wenn sie übersprungen werden.

3. Überprüfen

Führe checklist.md vollständig aus, bevor du den Erfolg meldest.

Hinweise zur Dokumentationsstruktur (einmal lesen, dann die Vorlagen/ wörtlich befolgen)

• CLAUDE.md ist immer ein einzeiliger Stub, der auf AGENTS.md verweist.
• AGENTS.md ist der obligatorische Einstiegspunkt: eine kurze „Must Read“-Liste plus nicht verhandelbare Regeln, im Projektstammverzeichnis.
• .agents/README.md ist ein flaches Inhaltsverzeichnis von allem unter .agents/ – halte es synchron, wenn eine bedingte Datei (Authentifizierung, Warteschlange, Cache, Speicher, Nachrichten, i18n, Agent-Surface) hinzugefügt oder übersprungen wird.
• Themen, die tatsächlich ein kurzes Dokument darstellen, bleiben flach in .agents/*.md (Workflow, Git-Richtlinie, Dokumentation, Testen und Qualität, Agent-Surface, Refactoring, Fortschritt).
• Themen, die sich auf mehrere Dokumente oder funktionsspezifische Register verteilen, erhalten einen Unterordner mit einem eigenen README.md-Hub: .agents/code-style/, .agents/architecture/, .agents/shared/, .agents/core/, .agents/decisions/.
• .agents/shared/README.md registriert src/common/ (Framework-unabhängige Hilfsprogramme – null @nestjs/*-Importe – plus generische Pipes/Filter/Interceptor/Decoratoren). .agents/core/README.md registriert src/core/-appweite Singletons (Authentifizierung, Prisma-Client-Provider, Logger, Warteschlange, Cache, Speicher, i18n – jedes mit einer eigenen bedingten Dokumentdatei, wenn dieses Feature ausgewählt wurde).
• .agents/decisions/README.md erklärt, wann eine kurze ADR erforderlich ist (Schichtrichtung, Nachrichtenbroker-Migration, Änderung der Versionierungsstrategie) – wird immer generiert, beginnt ohne ADR-Dateien.
• Der gesamte Inhalt nachverfolgter Dateien – einschließlich TSDoc – ist nur auf Englisch. Kein Kyrillisch, kein Mojibake.
• Alle Dokumente in .agents/ müssen wie die Vorlagen von kikita-create-angular-app klingen: imperativ, kurz, beispielgestützt und endend mit einer Überprüfungs-/Verifikations-Checkliste.