Communitygithub.com

JayFarei/opentraces

Führe alle site-bezogenen Fehlerbehebungen auf main aus, deploye opentraces.ai auf Vercel Production und verifiziere die Funktionalität auf allen Seiten (Desktop + Mobile) sowie im E-Mail-Capture-Flow. Wiederhole den Vorgang (Behebung → Deployment → Verifikation), bis alles grün ist.

Was ist opentraces?

Dieses Skill dient der koordinierten Bereitstellung der Next.js-Marketing-Website von opentraces auf Vercel Production. Es ist als geschlossener Kreislauf konzipiert: Site-Fixes werden identifiziert, lokal verifiziert und auf main gepusht. Anschließend wird die Seite gebaut und deployed. Der Kern des Skills liegt in der umfassenden Verifikation des Live-Systems: Alle Routen werden auf Desktop und Mobile auf korrekte Darstellung und Fehlerfreiheit geprüft, inklusive des E-Mail-Capture-Flows über die Warteliste. Der Skill nutzt ein Workflow-basiertes Test-Harness, das deterministisch arbeitet, Fehler reproduziert und eine Triage ermöglicht. Nur wenn alle Prüfungen bestehen, gilt das Ziel als erreicht. Bei wiederholten Fehlern oder fehlenden Berechtigungen wird der Prozess gestoppt und gemeldet. Der Skill ist für die Verwendung mit Claude Code, Cursor oder ähnlichen KI-Agenten optimiert, die das Ziel ‚Deploy the site‘ ausführen sollen.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JayFarei/opentraces/tree/HEAD/.claude/skills/deploy-site

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Site deployen

Deploye die Next.js-Marketing-Website (web/site/) auf Vercel Production, behandle es aber als Ziel, nicht als einzelnen Befehl: Führe alle site-bezogenen Fehlerbehebungen auf main aus, deploye sie, beweise, dass sie in Production auf allen Seiten und dem E-Mail-Capture-Flow auf Desktop und Mobile funktionieren, und wiederhole das Beheben + Deployen, bis alles grün ist.

Zielvertrag

Führe diesen Skill als geschlossenen Kreislauf aus. Erkläre den Erfolg nicht bereits bei einem sauberen Vercel-Deploy; ein Deploy kann erfolgreich sein, während eine Seite einen 500er Fehler wirft, ein Layout auf Mobilgeräten bricht oder der Wartelisten-Eintrag stillschweigend fehlschlägt.

  • ERLEDIGT, wenn: alle site-bezogenen Fehlerbehebungen committet und auf main gepusht sind, das Production-Deploy erfolgreich war, jede der folgenden Routen einen 200er Status zurückgibt und auf Desktop und Mobile korrekt rendert (keine Konsolen-/Netzwerkfehler), und der E-Mail-Capture-Flow eine Eingabe akzeptiert und speichert (nachgewiesen durch Admin-Lesen), ohne Testzeilen zu hinterlassen.
  • NICHT ERLEDIGT (erneut durchlaufen), wenn: eine Route nicht rendert, ein Layout bei einem Viewport bricht, die Konsole Fehler anzeigt oder der E-Mail-Capture nicht rundläuft. Behebe die Ursache im Quellcode, führe erneut aus, deploye erneut, verifiziere erneut.
  • BLOCKIERT (stoppen und melden), wenn: eine Fehlerbehebung eine Anmeldeinformation/Entscheidung erfordert, die du nicht hast (z.B. KV-Store down, Admin-Token fehlt, Vercel-Authentifizierung abgelaufen), oder derselbe Fehler nach 3 Versuchen weiterhin besteht. Melde den genauen Fehler + was du versucht hast; wiederhole nicht endlos.

Führe ein kurzes fortlaufendes Protokoll jeder Iteration (was fehlgeschlagen ist, was du geändert hast, Ergebnis der erneuten Verifikation), damit der Kreislauf nachvollziehbar ist. Wenn der Benutzer dies als persistentes /goal wünscht, verweise das Ziel auf diesen Skill und verwende dieselben ERLEDIGT/BLOCKIERT-Bedingungen.

Der Kreislauf

Phase 0  Umfang & landen    Site-Fixes sammeln → lokal verifizieren → committen → main pushen
Phase 1  Deploy             build → npx vercel@latest --prod (vom Repository-Stammverzeichnis)
Phase 2  Verifizieren (Prod) Workflow-Fan-out: Routen x Viewports + E-Mail-Capture
Phase 3  Triage             Irgendwas rot? Im Quellcode beheben → zurück zu Phase 0
                            Alles grün? → ERLEDIGT

Kontext

  • Projekt: opentraces auf Vercel (Umfang jayfareis-projects)
  • Framework: Next.js 16 (App Router)
  • Stammverzeichnis: Vercel ist mit Stammverzeichnis web/site/ konfiguriert
  • Domain: opentraces.ai (Production: https://opentraces.ai)
  • Build: next build (wird von web/site/ aus ausgeführt)
  • Version: Wird zur Build-Zeit automatisch aus src/opentraces/__init__.py via next.config.ts gelesen
  • E-Mail-Capture: EarlyAccessForm sendet an /api/waitlist (Upstash/KV in Prod). Wird auf / (via HubTeaser) und /hub gerendert. Siehe den Referenzabschnitt für Selektoren + Admin-Lesen.

Phase 0 — Site-Fixes erfassen und landen

  1. Finde, was site-bezogen und noch nicht gelandet ist. Der Arbeitsbaum enthält oft eine Mischung aus Site + Nicht-Site-Änderungen. Lande hier nur die Site-Fixes (der Rest ist ein separates Thema).

    git status --short web/site/
    git status --short -- ':!web/site/'   # Nicht-Site-Änderungen, diese normalerweise belassen
    git log --oneline origin/main..HEAD -- web/site/   # Site-Commits, noch nicht gepusht
    
  2. Lokal verifizieren vor dem Landen (Tor). Führe die Site gegen den bereits laufenden Dev-Server aus und überprüfe die geänderte Oberfläche mit agent-browser: Hell + Dunkel, Desktop + Mobile, die spezifische Interaktion, die du geändert hast, plus Konsolen-/Netzwerk-Clean. Dies ist das Tor vor dem Landen; committe keine visuelle Regression. (Wenn kein Dev-Server läuft, cd web/site && npm run dev auf einem freien Port, verifizieren, dann stoppen.)

  3. Lokal bauen (fängt Typ-/Build-Fehler, die der Dev-Server versteckt):

    cd web/site && npm run build
    

    Behebe alle Build-Fehler, bevor du fortfährst.

  4. Auf main committen und pushen. Gemäß Projektkonvention direkt auf main committen (keinen Feature-Branch automatisch erstellen, außer aufgefordert). Halte den Commit auf den Site-Fix beschränkt; co-author den Commit gemäß der Repository-Fußzeilenregel.

    git add web/site/   # nur die verifizierten Site-Fixes stagen
    git commit -m "fix(site): <was geändert>"
    git push origin main
    

Phase 1 — Bauen & deployen

Deploye vom Repository-Stammverzeichnis (nicht web/site/), weil Vercel das Stammverzeichnis aus seinen Projekteinstellungen auflöst (rootDirectory=web/site). Ein Ausführen von innerhalb web/site/ verschachtelt den Pfad doppelt. Verwende immer die neueste CLI (npx vercel@latest).

cd /path/to/repo/root
rm -rf web/site/.next kb/app/.next   # alter Build-Output; bläht den Upload auf
npx vercel@latest --prod --yes

Verwende NICHT --archive=tgz (gemessen am 2026-06-26, CLI 54.x). --archive=tgz tarnt den gesamten Arbeitsbaum und umgeht .vercelignore, lädt also .git-minus-nichts-sonst plus kb/, .otbox/, web/site/.next-test/, etc. hoch — ein ~3 GB / 1998 Dateien Upload, der Minuten dauert und einmal für ~20 Min bei „Extracting deployment files" auf der Build-Maschine hängen blieb (ein echter Produktionsstau, den wir hatten). Der standardmäßige Datei-für-Datei-Pfad auf vercel@latest hingegen:

  • respektiert .vercelignore → ~628 Dateien / ~40 MB,
  • lädt in ~2 s hoch und erreicht READY in ~60 s Ende-zu-Ende,
  • trifft nicht auf den Error: Upload aborted, den --archive=tgz ursprünglich umgehen sollte (das war ein brew 41.x Endpunkt-Bug; vercel@latest hat ihn behoben, daher ist der Workaround jetzt netto negativ).

Falls eine zukünftige CLI den Datei-für-Datei-Pfad zurückentwickelt und du auf --archive=tgz zurückfallen musst, erwarte das ~3 GB Archiv und eine mehrere Minuten dauernde (gelegentlich stockende) Extraktion — wiederhole das Deploy, wenn es bei der Extraktion hängt.

Erfasse die Deployment-URL/-ID aus der Ausgabe; du wirst sie im Verifikationsbericht referenzieren.

Tipp: Du kannst zuerst ein Vercel Preview-Deploy verifizieren (lasse --prod weg) und Phase 2 gegen die Preview-URL ausführen, bevor du promotest. So bleiben E-Mail-Capture-Tests vollständig von der Produktionsliste fern.


Phase 2 — In Production verifizieren (JIT-Harness via Workflow / ultracode)

Beweise, dass die Live-Site funktioniert. Diese Phase ist ein Just-in-Time-Harness: Du (der Planer) legst den Umfang für dieses Deploy fest, das Workflow-Tool (die deterministische Laufzeit) führt es aus, und flüchtige Browser-Worker liefern jeweils gegen ein typisiertes Schema zurück. Zwischenzustände leben in den Variablen des Harnesses, nicht in deinem Kontext, sodass die vollständige Matrix läuft, ohne dein Fenster zu füllen. Dieser Skill entscheidet sich explizit für Workflow-Orchestrierung (ultracode).

Das Harness ist gebündelt und eingefroren neben diesem Skill: verify-site-deploy.workflow.js. Füge das Skript nicht inline ein; führe die Datei aus.

Was zu prüfen ist

  • Routen (jede muss 200 + rendern, keine Konsolen-/Netzwerkfehler): /, /explorer, /hub, /schema, /docs, plus eine Stichprobe tiefer Seiten: /schema/0.6.0, /docs/getting-started/installation, /docs/cli/commands, /docs/schema/trace-record.
  • Viewports: Desktop 1440x900 und Mobile 390x844 (iPhone-Klasse). Wenn eine Fehlerbehebung die Thematik betroffen hat, überprüfe auch Hell + Dunkel.
  • Pro Seite: HTTP 200, primärer Inhalt sichtbar, kein Layout-Überlauf/-Abschneiden am Viewport, Konsole sauber, keine fehlgeschlagenen Netzwerkanfragen, Navigation funktioniert.
  • E-Mail-Capture (eigener Agent, siehe unten).

E-Mail-Capture-Verifikation (die Produktionsliste nicht verunreinigen)

/api/waitlist schreibt in einen Live-Store und hat keinen DELETE-Endpunkt, also sei bewusst:

  • Echter Round-Trip (einmal, Desktop): Sende eine getaggte Adresse wie deploy-verify-<timestamp>@opentraces.ai. Erwarte HTTP 200 {ok:true} und dass der Button in den Erfolgszustand wechselt. Bestätige die Persistenz mit dem Admin-Lesen (GET /api/waitlist + Authorization: Bearer $WAITLIST_ADMIN_TOKEN), unter Notierung der Anzahl vorher/nachher. Räume sie dann auf, indem du diese Zeile aus dem Store entfernst (Upstash ZREM), und lies erneut, um zu bestätigen, dass die Anzahl zurück ist. Hinterlasse die Liste unberührt.
  • Dedup-Pfad: Sende dieselbe Adresse zweimal, erwarte „Du bist bereits auf der Liste" mit unveränderter Anzahl.
  • Mobile + wiederholte UI-Prüfungen ohne Schreiben: Fülle das versteckte Honigtopf (input[name=company]) beim Absenden. Der Endpunkt gibt einen stillen Fake-Erfolg zurück und speichert die Zeile nie, sodass du die Erfolgs-UI auf Mobile bestätigen kannst, ohne Müll hinzuzufügen. (Wenn du „Erfolg" siehst, aber die Anzahl sich nicht bewegt, funktioniert das Honigtopf, es ist kein Fehler.)
  • Wenn der Endpunkt 503 zurückgibt („Warteliste ist nicht konfiguriert"), ist der KV-Store bei diesem Deployment nicht verbunden: das ist BLOCKIERT (Umgebungs-/Store-Problem), kein Code-Fix. Melde es.

Führe das Harness aus

Rufe das gebündelte Artefakt mit dem Workflow-Tool auf. Lege den Umfang pro Deploy mit args fest (dies ist der JIT-„Planer"-Schritt):

Workflow({
  scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
  args: {
    baseUrl: "https://www.opentraces.ai",  // kanonischer Host; oder eine Preview-URL, um E-Mails von Prod fernzuhalten
    changed: ["/hub", "/"],             // Routen, die dieses Deploy betroffen hat → tief geprüft; Rest wird nur geraucht
    pagesOnly: false                    // true = E-Mail-Schreiben überspringen (nur lesende Validierung läuft)
  }
})

Es gibt { base, scoped, failures, allGreen } zurück. allGreen: true bedeutet Phase 2 bestanden; andernfalls listet failures genau auf, was in Phase 3 zu beheben ist.

Wie das Harness die JIT-Primitiven anwendet (siehe kb/docs/concept-jit-harnesses-generic.md):

  • Klassifizieren und leiten: Wenn du changed übergibst, erhalten diese Routen eine vollständige Browser-Prüfung (Konsole, Überlauf, Screenshot); jede andere Route wird nur mit einem billigen curl-Status geprüft. Reine JS-Kontrollflusslogik, die die Laufzeit besitzt, kein Modell im Nahtbereich, sodass ein gezieltes Deploy billig bleibt.
  • Ein deterministischer Sweep-Worker pro Viewport (2 Worker, nicht ~18): Jeder führt eine einzelne feste Bash-Batch aus (curl + eine begrenzte Anzahl von agent-browser-Aufrufen pro Route) auf einem billigen Modell (haiku) und gibt das geparste JSON zurück. Keine offene „Verifiziere alles"-Eingabeaufforderung, sodass das Modell nicht schleifen kann; jede Batch öffnet eine Browser-Sitzung und macht close --all, sodass sich keine Chrome-Prozesse stapeln. (Validiert 2026-06-09: ~16 s für einen vollständig tiefen Viewport-Sweep, 1 übriggebliebener Prozess, vs. ursprüngliches Pro-Zellen-Design mit 54 Prozessen / 15+ Min.)
  • Unabhängige adversarial confirmation: Jede Route, die ein Sweep als fehlgeschlagen markiert, wird von einem separaten Worker mit einer sauberen Sitzung (Standardmodell) erneut geprüft, der versucht, sie zu reproduzieren; ein Fehler überlebt nur, wenn die Bestätigung ebenfalls fehlschlägt, sodass ein agent-browser-Fehlgriff nicht als Site-Bug getarnt wird.
  • Typisierte Verträge: Jeder Worker gibt gegen PAGE_VERDICT / EMAIL_VERDICT zurück, sodass Ergebnisse mechanisch zusammengeführt werden.
  • E-Mail-Capture erhält einen eigenen Worker, der den Schreibvorgang über ein unabhängiges Admin-Lesen nachweist und die Testzeile bereinigt (siehe die Nicht-Verschmutzungsregeln oben).

Um die Matrix, die Tiefenrichtlinie oder das Urteilsschema zu ändern, bearbeite die .js -Datei; sie ist die alleinige Quelle der Wahrheit. Wenn die Änderung eine Seite betrifft und du keine Orchestrierung möchtest, kannst du die Prüfung dieser Seite trotzdem sequenziell mit dem agent-browser-Skill in der Hauptsitzung ausführen.


Phase 3 — Triage & iterieren

Lies die Fehler (failures) des Workflows:

  • Leer -> das Ziel ist erreicht. Melde: Deployment-ID/URL, verifizierte Routen, Viewports, E-Mail-Round-Trip nachgewiesen + bereinigt. ERLEDIGT.
  • Nicht leer -> Finde für jeden Fehler die Ursache im web/site/-Quellcode, behebe sie und gehe zurück zu Phase 0 (lokal verifizieren -> committen -> pushen -> deployen -> erneut verifizieren). Führe die erneute Verifikation zuerst nur für die fehlgeschlagenen Routen durch, dann einen vollständigen Durchlauf, sobald sie grün sind.
  • Nach 3 erfolglosen Versuchen für denselben Fehler oder bei einem Anmeldeinformations-/Store-/Auth-Blocker stoppe und melde als BLOCKIERT mit dem genauen Fehler und deinen Versuchen.

Halte jede Iteration im fortlaufenden Protokoll fest, damit der Kreislauf nachvollziehbar ist.


.vercelignore

Der Speicherort ist entscheidend: die wirksame Datei ist das .vercelignore im Repository-Stammverzeichnis. Selbst wenn das Stammverzeichnis des Projekts web/site ist, wird das gesamte Repository hochgeladen (der Build liest ../../src/opentraces/__init__.py und ../../skill/SKILL.md), und das einzige .vercelignore, das der Datei-für-Datei-Upload berücksichtigt, ist das im Repository-Stammverzeichnis — Muster werden relativ zum Repository-Stammverzeichnis abgeglichen. Ein web/site/.vercelignore wird ignoriert; füge keines hinzu (verifiziert 2026-06-26 via npx vercel@latest --debug).

Es ist eine Positiv-Ausnahmeliste (explizit aufgezählte Verzeichnisse, kein *-Catch-All mit !-Negationen — Negationen sind fragil und brechen über CLI-Versionen hinweg). Ohne sie umfasst der Upload die schweren Repository-Bäume. Die großen, die es ausschließen muss (jedes war ein echtes Leck, das wir behoben haben):

  • kb/ (~2,4 GB), .claude/ (~1,5 GB), tests/ (~1,4 GB), .venv*/ (~0,8 GB)
  • .otbox/ (~613 MB an Snapshot-Tarballs)
  • web/site/.next-test/ (~98 MB / 1000+ Dateien — beachte, dass **/.next/ nicht auf das -test-Suffix passt, also braucht .next-test/ eine eigene Regel)
  • web/viewer/, web/coming-soon/, web/metrics-worker/

Einschränkung: .vercelignore filtert nur den Datei-für-Datei-Upload-Pfad. Das --archive=tgz-Flag umgeht es (siehe Phase 1 — ein weiterer Grund, es nicht zu verwenden).

Um zu überprüfen, was nach dem Bearbeiten von .vercelignore hochgeladen würde, führe npx vercel@latest --debug vom Repository-Stammverzeichnis aus und lies die Found N files … M required to upload-Zeile, dann Strg-C — kein vollständiges Deploy nötig. Ein gesundes Site-Deploy hat ~628 Dateien, nicht ~2000.

Dateien, die NICHT ignoriert werden dürfen (der Build liest sie zur Build-Zeit):

DateiGelesen vonZweck
src/opentraces/__init__.pynext.config.tsVersionserkennung für version.json
skill/SKILL.mdlib/docs.ts (getSkillContent())Maschinenansichts-Inhalt auf Dokumentationsseiten

Wenn du eine neue Datei hinzufügst, die die Site zur Build-Zeit über einen relativen Pfad wie ../../foo liest, stelle sicher, dass sie nicht von .vercelignore ausgeschlossen wird.

Referenz

Routen (Phase 2 Matrix): /, /explorer, /hub, /schema, /schema/[version], /docs, /docs/[[...slug]] (~36 Doc-Slugs aus lib/doc-nav.ts). API: /api/waitlist (POST hinzufügen, GET Admin-Lesen), /api/stars.

E-Mail-Formular-Selektoren (EarlyAccessForm.tsx): E-Mail-Eingabe input[type=email] / aria-label="E-Mail-Adresse" / .ea-input; Absenden button.ea-btn („Frühen Zugang erhalten" -> lädt -> Erfolg); verstecktes Honigtopf input[name=company] (Ausfüllen -> stiller Fake-Erfolg, niemals gespeichert).

Wartelisten-Admin-Lesen: GET /api/waitlist mit Authorization: Bearer $WAITLIST_ADMIN_TOKEN.

Konsole/Netzwerk sauber halten

Wenn agent-browser läuft, sorge dafür, dass die Sitzung vor jeder neuen Routenprüfung eine console.reset() ausführt, damit die Konsolenaufzeichnung nicht zwischen Seiten durchläuft. Das Harness macht dies standardmäßig für seine eigenen Sweeps, aber wenn du manuell mit dem agent-browser-Skill in der Hauptsitzung prüfst, gib reset: true in deinem browser_action-Aufruf an.


Weitere Informationen

Dieser Skill wird über die folgenden Auslöser aktiviert: "deploy site", "deploy to vercel", "push site", "ship the site", "deploy-site", "land and verify the site". Für eine vollständig koordinierte Veröffentlichung, die auch die Version erhöht und die Python-Pakete veröffentlicht, verwende stattdessen /release-pack.

Der Skill ist so konzipiert, dass er von KI-Agenten wie Claude Code, Cursor und Codex ausgeführt wird. Er verwendet ein JIT-Harness (Just-in-Time), das deterministisch arbeitet und auf ultracode/Workflow-Orchestrierung aufbaut. Die zugehörige Workflow-Datei verify-site-deploy.workflow.js ist gebündelt und liegt im gleichen Verzeichnis wie dieser Skill.

Verwandte Skills