daniloduuarte/verify-saas

Wann ausführen (die Regel, die entscheidet)

Mit Bedacht ausführen, nicht reflexartig. Wählen Sie die Stufe je nach Situation:

Situation	Was ausführen
Nur Dokumentation, Notizen, Kommentare, Plan oder Spezifikation	Nichts. Sagen Sie, dass es nicht nötig war.
Mitten in der Arbeit: zwischen Bearbeitungen, Korrekturrunden, „Habe ich die Types kaputt gemacht?“	Schnell: node .claude/skills/verify-saas/driver.mjs --quick (oder nur den Types-Befehl, wenn sich nur ein einziger Typ geändert hat)
Ende jeder Aufgabe oder logischen Einheit, vor dem Commit	Vollständig, einmal
Vor jedem git push, Deployment oder Merge in den Hauptbranch	Vollständig, obligatorisch. Wenn der letzte vollständige Lauf genau den Commit abdeckt, der hochgehen soll, nicht wiederholen.
Neue Migration, Änderung in package.json, Build-Konfiguration, Zugriffs-/Authentifizierungsregeln	Vollständig am Ende dieser Änderung (Risiko struktureller Änderung)
Nach git pull oder Merge von Arbeit einer anderen Person	Vollständig (verankert die Baseline neu)

Nie:

• zweimal hintereinander ohne Änderung dazwischen ausführen;
• eine zweite Runde beginnen, bevor die erste gelesen wurde;
• parallel zu einem anderen Build oder Test im selben Ordner ausführen;
• den vollständigen Modus mitten in einer Anpassungsrunde ausführen (warten Sie auf die Commit-Anfrage).

Immer:

• bestätigen, dass die Tests auf eine Testdatenbank/-umgebung zeigen, niemals auf Produktion (siehe Hinweis in der README);
• vor dem Ausführen das eigene Diff noch einmal lesen: überflüssige Importe und falsche Eigenschaftsnamen werden beim Lesen erwischt, nicht durch das Ausführen einer Runde;
• den gesamten Bericht lesen, nicht nur den Exit-Code.

Wie ausführen

Im Projektstammverzeichnis:

node .claude/skills/verify-saas/driver.mjs            # vollständig
node .claude/skills/verify-saas/driver.mjs --quick    # schnell, verändert die Baseline nicht
node .claude/skills/verify-saas/driver.mjs --baseline # erfasst den aktuellen Zustand als „gut“

Alles, was projektspezifisch ist (Befehle, Ordner, Warnwörter, ein- oder ausgeschaltete Schritte), befindet sich in verify-saas.config.json im Projektstammverzeichnis. Ohne diese Datei gelten die Standardeinstellungen für Next.js + TypeScript + npm.

Exit-Code: 0 = nichts hat sich verschlechtert; 1 = etwas hat sich verschlechtert oder etwas war bereits kaputt (Types, Build oder Tests).

Erste Verwendung: An das Projekt anpassen (für den Agenten, der dies liest)

Wenn der Benutzer die Skill gerade installiert hat und darum bittet, sie an sein SaaS-Projekt anzupassen, gehen Sie in dieser Reihenfolge vor:

1. Lesen Sie das Projekt (package.json oder Äquivalent, Migrationsordner, wie die Tests ausgeführt werden) und passen Sie verify-saas.config.json an: Befehle für Types, Lint, Build und Tests, structure.migrationsDir und alertKeywords. Schalten Sie ("enabled": false) aus, was das Projekt nicht hat.
2. Fragen Sie, was im Geschäftsbetrieb nicht kaputt gehen darf (Termine ohne doppelte Uhrzeit, Bestand ohne negative Werte, ausgeglichener Kontostand, Unternehmen A ohne Einsicht in B, zweimal erhaltener aber nur einmal gutgeschriebener Zahlungseingang...). Erfinden Sie keine Regeln: Bestätigen Sie mit dem Benutzer und schreiben Sie Tests dafür, unter Verwendung von docs/exemplos-por-nicho.md als Vorlage.
3. Bestätigen Sie die Testumgebung. Führen Sie Tests niemals gegen die Produktion aus. Wenn es keine Testdatenbank oder -umgebung gibt, stoppen Sie und informieren Sie den Benutzer.
4. Führen Sie erst dann node .claude/skills/verify-saas/driver.mjs --baseline aus und zeigen Sie den Bericht an, wobei Sie darauf hinweisen, was bereits kaputt war (Schuld) und was bestanden hat.
5. Teilen Sie dem Benutzer mit, was angepasst wurde und dass er die geschriebenen Tests überprüfen sollte.

So lesen Sie den Bericht

In dieser Reihenfolge:

1. Types: bestanden/fehlgeschlagen und Anzahl der Fehler im Vergleich zur Baseline.
2. Lint: verglichen anhand des Fingerabdrucks (Datei:Zeile:Spalte:Regel), nicht nur nach Anzahl. „5 Fehler vorher, 5 nachher“ kann 5 verschiedene Fehler verbergen. Alte Schuld ist nie Ihre Schuld; nur die NEUEN zählen.
3. Build: bestanden/fehlgeschlagen und Liste der Routen (falls konfiguriert).
4. Tests: bestanden/fehlgeschlagen im Vergleich zur Baseline.
5. Struktur: neue, entfernte oder in der Version geänderte Abhängigkeiten; neue Migrationen, markiert mit Warnung, wenn sie Warnwörter enthalten (Sicherheit/Berechtigungen).

Symbole: ✗ Regression (korrigieren), ✓ verbessert, = keine Änderung, ℹ Information, ⚠ prüfen, ob beabsichtigt.

Nach der Ausgabe überschreibt der vollständige Modus die Baseline mit dem aktuellen Zustand. Deshalb: Korrigieren Sie die Regressionen, bevor Sie erneut ausführen, sonst behandelt der zweite Durchlauf den Fehler als „alte Schuld“.

Best Practices

• Die Baseline (verify-saas.baseline.json) sollte im Projekt committet werden; sie ermöglicht den Vergleich „seit dem letzten Mal“ über Sitzungen und Maschinen hinweg.
• Erstes Mal im Projekt: führen Sie mit --baseline in einem Zustand aus, von dem Sie sicher sind, dass er gut ist.
• Migrationen werden nur anhand des Dateinamens verglichen. Die Skill wendet das SQL nicht an und validiert es nicht; sie meldet nur, dass eine neue aufgetaucht ist und ob sie die Sicherheit betrifft.
• Die Skill installiert keine Abhängigkeiten (npm install ist eine größere Aktion, als eine Überprüfung allein durchführen sollte).
• Wenn der Bericht ein „neues“ Problem anzeigt, das Sie nicht verursacht haben, prüfen Sie, ob jemand das Repository zwischen den Läufen geändert hat (git log -3 --oneline).
• Der eigentliche Schutz kommt von den Tests, die Sie schreiben (siehe docs/exemplos-por-nicho.md). Die Skill stellt nur sicher, dass sie ausgeführt werden, und meldet, wenn sich etwas ändert.