wp-dev: Lokale Entwicklung von Live-WordPress-Seiten

wp-dev: Arbeiten an einer Live-WordPress-Seite lokal

Führe wpsync als ${CLAUDE_PLUGIN_ROOT}/bin/wpsync aus (im Folgenden: wpsync). Der Entwickler ist normalerweise nicht derjenige, der dieses System gebaut hat, erkläre daher jeden Schritt in einfachen Worten und sage, wann etwas von ihm benötigt wird.

Lies zuerst ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md. Dort steht, wie Fortschritte angezeigt werden (eine Checkliste der Phasenschritte), wie Fragen gestellt werden (ein Fragendialog für jede Entscheidung und jede Wartezeit) und was zu tun ist, wenn die App dies nicht bietet. Die Ask-Zeilen unten nennen die zu verwendenden Dialoge.

Prinzipien: Überprüfe alles, bevor du etwas änderst, und melde jedes Problem sofort mit seiner Lösung. Jeder Schritt ist sicher wiederholbar, sodass der Entwickler nach einer Unterbrechung einfach "mein wp-dev-Projekt fortsetzen" sagt und du dort weitermachst, wo es aufgehört hat.

Bevor irgendetwas anderes: Kann wpsync ausgeführt werden?

wpsync läuft auf Bun. Auf einem Mac, der noch kein Bun hat, schlägt jeder wpsync-Befehl (einschließlich status, init und doctor) mit "wpsync needs Bun" fehl (Exit-Code 127). Überprüfe dies zuerst, vor jedem wpsync-Befehl:

1. Führe ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version aus. Wenn eine Version ausgegeben wird, fahre mit "Wo sind wir?" fort.
2. Wenn die Meldung "wpsync needs Bun" erscheint, suche Homebrew: command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew.
   • Homebrew gefunden → brew install oven-sh/bun/bun (mit dem vollständigen Pfad zu brew, falls es nicht im PATH ist), dann führe wpsync --version erneut aus.
   • Kein Homebrew → Der Entwickler wird benötigt (es wird nach seinem Mac-Passwort gefragt). Erkläre, dass wpsync und die anderen Tools mit Homebrew installiert werden, öffne einen Terminal-Tab mit dem Installationsbefehl von https://brew.sh (siehe guiding.md) und warte mit dem Dialog "Fertig, überprüfen". Mache Homebrew dann nutzbar (siehe "Homebrew direkt nach der Installation" in Schritt 2) und installiere Bun wie oben.

Wenn wpsync läuft, sage nichts darüber und fahre fort. Nur wenn du Bun installieren musstest, teile dem Entwickler in einem Satz mit, dass dies die erste Voraussetzung war, und dass wpsync doctor --local den Rest in Schritt 2 überprüft.

Wo sind wir?

Führe wpsync status --json im aktuellen Ordner aus und orientiere dich an der phase:

phase	Aktion
no-project	Phase 1 ab Schritt 1 (das Start-Gate)
start-gate (Ordner aus einer früheren Sitzung)	Phase 1 ab Schritt 2
connect, pull	Phase 1 ab Schritt 2 (überspringt, was bereits erledigt ist)
work	Phase 2: Der wp-work-Skill für Änderungen, wp-pull zum Aktualisieren, wp-publish zum Live-Schalten
publish-pending	Die letzte Veröffentlichung wartet auf Abschluss oder Rollback: siehe wp-publish

Unabhängig von der Phase: Wenn status ein wordfence-Feld enthält, muss Wordfence dieser Site während der Arbeit von wpsync ausgeschaltet und danach wieder eingeschaltet werden. Folge ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md.

Starte in Phase 1 die Setup-Checkliste aus guiding.md (oder zeige sie beim Fortsetzen erneut an), mit abgehakten erledigten Schritten, und beginne ein Kapitel "Setup".

Phase 1: Lokale Kopie einrichten

1. Start-Gate: Der richtige Ordner, dann die Adresse

Der Ordner einer Sitzung wird beim Start festgelegt, daher startet der Entwickler die Sitzung in dem Ordner, in den die lokale Kopie soll. Alles Weitere passiert in dieser einen Sitzung.

Ist diese Sitzung in einem brauchbaren Ordner? Überprüfe den aktuellen Ordner (ls -A):

• Leer (oder enthält nur .DS_Store oder .claude): Es ist der neue Ordner für die Site. Fahre unten fort.

• Irgendetwas anderes (Desktop, Home-Ordner, ein anderes Projekt): Hier nicht einrichten. Sende diese Nachricht und halte an:

  Um eine Site einzurichten, starte eine neue Claude-Code-Sitzung in dem Ordner, in dem du ihre lokale Kopie haben möchtest: einen neuen, leeren Ordner, z. B. ~/wp-sites/example.com. Starte eine neue Sitzung, wähle (oder erstelle) diesen Ordner und setze den Berechtigungsmodus auf Berechtigungen umgehen, wenn du nicht jeden Schritt einzeln bestätigen möchtest. (Die Veröffentlichung auf der Live-Site wartet immer darauf, dass du ihre Domain in einem Dialog eingibst.) Sage dann dort "neues wp-dev-Projekt".

Frage im neuen Ordner nur eines: die Adresse der Live-Site, in einer kurzen Zeile:

Wie lautet die Adresse der Live-Site? Zum Beispiel https://example.com.

Wenn der Ordnername eine Domain enthält (z. B. example.com-local), biete stattdessen an: "Wie lautet die Adresse der Live-Site? Vom Ordnernamen her würde ich auf https://example.com tippen."

Erstelle dann das Projekt hier: wpsync init <site-url> --dir .. Es schreibt die CLAUDE.md des Ordners, .claude/settings.json (genehmigt ddev, git, brew und die schreibgeschützten wpsync-Befehle vorab; Veröffentlichungen fragen trotzdem nach) und .wpsync.json als ausstehend markiert. Es kontaktiert nichts. Fahre direkt mit Schritt 2 fort. Diese Einstellungen werden ab der nächsten Sitzung in diesem Ordner wirksam; wenn du nicht im Modus "Berechtigungen umgehen" bist, kann diese Sitzung zwischenzeitlich etwas öfter nachfragen. Du kannst den Berechtigungsmodus nicht erkennen und musst es auch nicht.

2. Diesen Mac überprüfen

wpsync doctor --local listet alles auf einmal auf. Zeige es als Ergebnistabelle aus guiding.md an. Installiere fehlende Komponenten in dieser Reihenfolge:

• Du kannst es erledigen: brew install ddev/ddev/ddev, brew install oven-sh/bun/bun und Docker. Wenn keine Docker-App installiert ist, frage "Welche Docker-App soll ich auf diesem Mac installieren?": OrbStack (Empfohlen: leichter und schneller auf einem Mac, kostenlos für den privaten Gebrauch) oder Docker Desktop (die Standard-App; kostenlos für den privaten Gebrauch und kleine Unternehmen). Dann brew install --cask orbstack oder brew install --cask docker. Docker installiert, aber "nicht ausgeführt": Starte es selbst (open -a OrbStack oder open -a Docker) und warte bis zu einer Minute, bis docker info erfolgreich ist. Nur ein erster Start (Bedingungen, Passwort) benötigt den Entwickler; wenn docker info nach einer Minute immer noch fehlschlägt, wartet ein Dialog des ersten Starts auf ihn.
• Benötigt den Entwickler (ein Passwort oder ein Klick, den du niemals für ihn erledigst): die Xcode-Befehlszeilentools (xcode-select --install), Homebrew (von https://brew.sh), der erste Start von OrbStack oder Docker Desktop und mkcert -install. Öffne einen Terminal-Tab mit dem bereiten Befehl (siehe guiding.md) und warte mit dem Dialog "Fertig, überprüfen". Wenn mehrere fehlen, liste sie alle in einer Nachricht auf und warte einmal, nicht für jedes einzeln.

mkcert ist erforderlich (doctor meldet es als FIX, bis es eingerichtet ist). Die Adresse der lokalen Kopie ist https://…ddev.site. Ohne mkcert -install verweigert Chrome diese Adresse, und über einfaches http wird die Seite ohne ihre Styles oder Bilder geladen (WordPress verlinkt sie über https). Das sieht in Schritt 7 wie eine defekte Kopie aus. Erledige es also hier, vor dem ersten Pull: Sage, dass es nach dem Mac-Passwort fragt, führe mkcert -install in einem Terminal-Tab aus und warte. Wenn es erst installiert wird, nachdem DDEV bereits gestartet ist (Fortsetzen einer älteren Einrichtung), verwendet DDEV immer noch sein nicht vertrauenswürdiges Zertifikat: Führe ddev poweroff && ddev start im Site-Ordner aus und bitte dann, die Seite neu zu laden.

Führe wpsync doctor --local erneut aus, bis nichts mehr FIX sagt. Hinweise können warten, aber sage, was sie bedeuten.

Homebrew direkt nach der Installation: Auf Apple-Silicon-Macs landet Homebrew in /opt/homebrew, was erst im PATH ist, wenn die Zeilen "Next steps" des Installers ausgeführt wurden. doctor meldet dies als "installiert unter /opt/homebrew/bin/brew, aber noch nicht im PATH" zusammen mit der Zeile, die zu ~/.zprofile hinzugefügt werden muss; sende sie niemals zurück zur Neuinstallation. Deine eigene Shell übernimmt ~/.zprofile nicht, daher verwende in dieser Sitzung eval "$(/opt/homebrew/bin/brew shellenv)" && als Präfix für Befehle.

3. Die Site überprüfen

wpsync doctor <site-url> (schreibgeschützt). Vor dem Verbinden prüft es, ob die Site WordPress mit ihrer REST-API ist und ob Anwendungspasswörter aktiviert sind. (Ob der Host den Authorization-Header durchreicht, kann nur mit einem echten Schlüssel getestet werden, daher wird dies geprüft, sobald wpsync verbindet.) Zeige die Ergebnistabelle an. Korrigiere oder erkläre jedes FIX, bevor du fortfährst; die meisten sind Hosting- oder Sicherheits-Plugin-Einstellungen, die der Entwickler mit jemandem klären muss: Verwende den Dialog "Wenn eine Prüfung eine andere Person benötigt" in guiding.md.

Wordfence: Wenn es meldet, dass Anwendungspasswörter "ausgeschaltet sind, höchstwahrscheinlich von Wordfence", folge ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("Vorher"): Der Entwickler schaltet eine Einstellung in wp-admin aus, und du wartest mit dem Dialog "Fertig, überprüfen", bis doctor es bestätigt. Du wirst daran erinnern, es in Schritt 8 wieder einzuschalten.

4. Verbinden

Der wp-connect-Skill. Führe danach wpsync doctor <site-url> erneut aus: Es prüft jetzt auch den Authorization-Header, Multisite, Dateiberechtigungen, Versionen und Speicherplatz auf diesem Mac und dem Server.

(wpsync new <site-url> führt die Schritte 2 bis 7 in einem Durchlauf aus und stoppt beim ersten, das den Entwickler benötigt; das ist praktisch zum Fortsetzen. Schritt für Schritt, wie hier, erklärt mehr zwischendurch.)

5. Pull

Der wp-pull-Skill (erster Pull: wpsync pull <site-url> --dir .). Er erstellt das DDEV-Projekt unter https://<project>.ddev.site, was keine Änderung der Hosts-Datei erfordert. Große Sites brauchen etwas Zeit: Führe es als langlaufenden Job aus (guiding.md).

6. Die Kopie ausführungssicher machen

Die Kopie enthält die Live-Datenbank: echte Kunden-E-Mails, vielleicht Live-Zahlungs- oder API-Schlüssel, geplante Aufgaben. DDEV fängt alle ausgehenden E-Mails ab (einsehbar mit ddev mailpit) und wpsync setzt WP_ENVIRONMENT_TYPE=local. Sieh dir die aktiven Plugins in CLAUDE.md an. Wenn eines ein Zahlungs-, Versand-, CRM-, Newsletter- oder Webhook-Plugin ist, liste sie auf und frage "Diese Plugins in der lokalen Kopie von könnten immer noch mit echten Diensten kommunizieren. Was sollen wir tun?": Testmodus durchgehen (Empfohlen: Du führst sie zu den Test- oder Sandbox-Einstellungen jedes Plugins im lokalen wp-admin), oder So lassen wie sie sind (sie akzeptieren, dass die lokale Kopie diese Dienste erreichen kann).

Wenn keines der aktiven Plugins so ist, frage nicht: Sage es in einem Satz (nenne dabei diejenigen, die nur E-Mails senden, was DDEV abfängt) und fahre fort.

7. Verifizieren

wpsync verify prüft Seiten, wp-admin, Permalinks, verbleibende Live-Adressen, Bilder und ob Plugins und Theme mit Live übereinstimmen. Zeige die Ergebnistabelle an.

Bevor du einen fehlgeschlagenen Seitentest untersuchst, frage die Seite selbst einmal ab: curl -s -o /dev/null -w '%{http_code}' <localUrl>/. Wenn sie 200 antwortet, wurde der Test wahrscheinlich ausgeführt, während DDEV noch startete (es antwortet kurz nach ddev start mit 502): Führe wpsync verify noch einmal aus, bevor du in Logs eintauchst.

Sieh dann selbst nach: Öffne Live und die lokale Kopie nebeneinander in Chrome (Claude in Chrome), Startseite und ein paar Innenseiten, und vergleiche sie. Beurteile die Kopie nicht im integrierten Browserbereich der App: Er blockiert Styles, Skripte und Bilder einer *.ddev.site-Seite (ERR_BLOCKED_BY_CLIENT), sodass selbst eine perfekte Kopie dort defekt aussieht. Wenn Chrome nicht verfügbar ist, überprüfe die Seite mit curl und bitte den Entwickler, einen Blick darauf zu werfen. Wenn etwas anders ist, das du nicht erklären kannst, beschreibe es und frage: Jetzt reparieren (Empfohlen), oder Ist in Ordnung, weitermachen.

Lokales Login: Die Kopie hat die Benutzer der Live-Site, daher meldet sich der Entwickler im lokalen wp-admin mit seinem Live-Passwort an.

8. Übergabe

Lies jetzt die CLAUDE.md der Site, damit ihre Regeln ab hier gelten.

Zuerst, wenn diese Site Wordfence verwendet (wpsync status --json zeigt "wordfence": "switched-off"): Das Setup benötigt die Live-Site nicht mehr, daher folge ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("Wenn wpsync fertig ist") und lasse den Entwickler den Schutz von Wordfence wieder einschalten, warte und bestätige mit wpsync status. Führe dies vor der Übergabezeile aus, damit der letzte Schritt des Entwicklers das Starten der Arbeit ist und nicht eine weitere lästige Aufgabe.

Öffne dann die lokale Site in Chrome und schließe die Checkliste ab. Beende das Setup genau mit diesem, in Fettschrift, in einer eigenen Zeile, als letztes in deiner Nachricht (nichts danach; alle anderen Hinweise, wie das Anmelden, kommen davor):

Die lokale Kopie der Site ist bereit unter https://{lokale-Site-Domain}. Überprüfe sie und sage mir dann, welche Änderungen du vornehmen möchtest.

wobei https://{lokale-Site-Domain} durch die localUrl aus .wpsync.json ersetzt wird. Unmittelbar davor steht eine Zeile zum Anmelden: Das lokale wp-admin akzeptiert den Live-Benutzernamen und das Live-Passwort.