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
maingepusht 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:
opentracesauf Vercel (Umfangjayfareis-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 vonweb/site/aus ausgeführt) - Version: Wird zur Build-Zeit automatisch aus
src/opentraces/__init__.pyvianext.config.tsgelesen - E-Mail-Capture:
EarlyAccessFormsendet an/api/waitlist(Upstash/KV in Prod). Wird auf/(viaHubTeaser) und/hubgerendert. Siehe den Referenzabschnitt für Selektoren + Admin-Lesen.
Phase 0 — Site-Fixes erfassen und landen
-
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 -
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 devauf einem freien Port, verifizieren, dann stoppen.) -
Lokal bauen (fängt Typ-/Build-Fehler, die der Dev-Server versteckt):
cd web/site && npm run buildBehebe alle Build-Fehler, bevor du fortfährst.
-
Auf main committen und pushen. Gemäß Projektkonvention direkt auf
maincommitten (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=tgzursprünglich umgehen sollte (das war ein brew 41.x Endpunkt-Bug;vercel@latesthat 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
--prodweg) 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
1440x900und Mobile390x844(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 (UpstashZREM), 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 billigencurl-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 machtclose --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_VERDICTzurü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:
.vercelignorefiltert 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):
| Datei | Gelesen von | Zweck |
|---|---|---|
src/opentraces/__init__.py | next.config.ts | Versionserkennung für version.json |
skill/SKILL.md | lib/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.