Von JBake nach Hugo: eine Website-Migration, geplant mit Werkbaum

Diese Website lief seit Jahren auf einem selbst gepatchten Fork von JBake. Der Fork war bequem, solange ich ihn im Kopf hatte, aber jede Änderung am Layout hieß: Freemarker-Templates, ein altes CSS-Framework mit jQuery und veraltetem Java-Code. Jetzt läuft die Seite auf Hugo mit dem gepflegten Theme Blowfish, zwei Sprachen unter /de/ und /en/, und alle alten URLs leiten weiter.

Dieser Artikel dokumentiert, wie ich bei der Migration vorgegangen bin. Die Schwerpunkte liegen auf Werkbaum, meinem Werkzeug für Projektplanung mit Projektstrukturplänen, und darauf, warum sich diese Art der Planung nach meiner Erfahrung besonders für die Arbeit mit Agentic AI gut eignet. Die Umsetzung selbst hat nämlich ein AI-Agent erledigt, in meinem Fall vor allem Claude Code mit Fable 5.1, sowie kleinere Nachkorrekturen in meinen statischen Seiten mit OpenCode und Muse Spark 1.3.

Für diese Migration habe ich einen vereinfachten Ansatz gewählt. Wie ich generell mit Agentic AI in der Softwareentwicklung arbeite, ist Thema eines eigenen, späteren Artikels.

Ausgangslage

#

Die Bestandsaufnahme am Anfang ergab mehr Altlasten, als ich erwartet hatte:

• 73 Artikel, davon 57 als HTML aus einem noch älteren WordPress-Import und 16 in AsciiDoc, dazu 7 Seiten; 44 Artikel auf Deutsch, 29 auf Englisch, ohne Übersetzungspaare.
• 17 Admonitions, 6 include::-Anweisungen mit Tag-Regionen aus Quelldateien, 4 Callouts, zwei Artikel mit MP3-Aufnahmen.
• 23 interne Links auf Dateien aus der WordPress-Zeit, die nie im Repository lagen, nur auf dem Webspace.
• Eine .htaccess mit 121 Umleitungen alter WordPress-Pfade, die weiterhin funktionieren sollten, und Tag-URLs mit Leerzeichen, Umlauten und Großschreibung.

Die Ziele waren dementsprechend: Ein gepflegtes Theme, nur optisch aufgebessert mit eigenem CSS, statt eigenen Templates, echte Mehrsprachigkeit statt gemischter Listen, keine externen Requests, jede alte URL mit einer 301-Umleitung, und Build plus Deployment über Werkator, einen eigenen CI/CD-Server, der auch ohne Docker-Support in einem Hostsharing Managed Webspace läuft.

Der Plan als Werkbaum

#

In einem Chat mit Claude Code wurden die Anforderungen evaluiert, welcher statische Website-Generator überhaupt verwendet werden soll, und welche Templates dafür infrage kommen.

Der erste Commit der Migration war somit kein Code, sondern der Plan: doc/Hugo-Migration.werkbaum, eine Textdatei in der Werkbaum-Notation. Gekürzt sah sie zu Beginn so aus:

[ ] #relaunch: Website-Relaunch michael.hoennig.de mit Hugo (XL)
  - [ ] #inventar: Bestandsaufnahme (S)
    - [ ] #content-inv: Content-Inventar: Artikel, Sprache, Sonderkonstrukte (XS)
    - [ ] #urls: Alte URL-Struktur dokumentieren (XS)
  - [ ] #spike: Hugo-Spike (S) :#inventar
    - [!] #math-check: Formel-Rendering prüfen (XS) :#content-inv
    - [ ] #admon-check: Admonition-Darstellung ausprobieren (XS)
  - [ ] #migration: Content-Migration (L) :#spike
    - [ ] #conv-script: Konvertierungsskript (XS)
    - [ ] #conv-review: Sichtprüfung je Artikel (S) :#conv-script
  - [ ] #theme: Layout und Theme (L) :#spike
  - [ ] #ci: Build und Deployment mit Werkator (M)
  - [ ] #cutover: Go-Live (M) :#migration,#theme,#ci
    - [ ] #qa: Abnahme: Vergleich alt gegen neu, Redirects (S)
    - [ ] #switch: Webroot umschalten (XS) :#qa

---
#math-check
  High Risk, weil unklar ist, ob alte Artikel Formeln enthalten.

Die Notation ist bewusst schlicht gehalten, damit sie leicht im Plaintext bearbeitbar und als Diff lesbar bleibt:

• Einrückung bildet die Zerlegung ab. - bedeutet ein Pflicht-Teilpaket (alle davon), | eine Alternative (eine davon), + einen optionalen Zusatz.
• Die Statusbox sagt, wo ein Knoten steht: [?] Idee, [ ] geplant, [~] in Arbeit, [/] Durchstich, [x] fertig, [^] in Produktion, [-] verworfen, [!] High Risk.
• (S) ist eine T-Shirt-Größe, #math-check eine ID, :#content-inv eine Abhängigkeit, %% ein Kommentar.
• Unter dem Trennstrich --- stehen Anmerkungen je ID: Befunde, Entscheidungen, Verworfenes.

Der Editor rendert daraus live ein Diagramm mit Statusfarben. Für die Steuerung der Arbeit ist aber die Textdatei entscheidend, nicht das Bild. Allerdings kann man über das gerenderte Diagramm den Fortschritt des KI-Agenten gut beobachten.

Wie der Plan die Arbeit gesteuert hat

#

Der Agent hat den Werkbaum nicht nur gelesen, sondern auch laufend gepflegt. Die Regeln waren einfach:

1. Nimm den nächsten Knoten, dessen Abhängigkeiten [x] sind. Setze ihn auf [~].
2. Jede Änderung ist ein Commit, die ID steht vorne in der Commit-Nachricht. Vor jedem Commit muss der Hugo-Build fehlerfrei sein.
3. Befunde und Entscheidungen kommen in die Anmerkung des Knotens, inklusive der verworfenen Alternativen und der Gründe.
4. Entscheidungen, die mir als Product Owner zustehen, werden mir als zwei bis vier Optionen mit Aufwand, Risiko, Auswirkung und Umkehrbarkeit vorgelegt. Die Empfehlung steht vorne.

Das Git-Log liest sich dadurch wie der Plan:

105a531 #inventar: Bestandsaufnahme abgeschlossen
d852bac #conv-script: Konvertierungsskript und Content-Import
1fd047b #conv-review: Sichtprüfung aller Artikel und Seiten
b94fb47 #theme-spike: PaperMod, Congo und Blowfish als Kandidaten
6a96673 #theme-base: Blowfish als Standard-Umgebung
5324e13 #redirect-map: Generierte .htaccess mit 325 Umleitungen
0b7e95b #werkator-build: Werkator-Konfiguration, Link-Check, Deploy-Skript
f6e9fdc #qa: Abnahme auf der Preview-Domain bestanden

Drei Stellen zeigen, was der Plan dabei geleistet hat.

Risiken zuerst, und manchmal löst sich ein Risiko in Luft auf

#

Zwei Knoten waren von Anfang an [!]: Formel-Rendering und Formel-Umstellung. Die Bestandsaufnahme ergab: kein einziger Artikel enthält Formeln. Beide Knoten konnten also mit [-] gestrichen werden.

Lean Pathfinding im Kleinen

#

Die zu erreichenden Features strukturieren und bewerten, dann ermitteln, welcher Pfad am schnellsten das nächste Zwischenziel erreichen lässt. Wenn ein Zwischen erreicht ist, das nächst erreichbare Zwischenziel ermitteln.

Alternativen als Spike, Entscheidung beim Menschen

#

Für das Theme gab es einen Spike statt einer Diskussion: PaperMod, Congo und Blowfish mit dem kompletten Content. Die Wahl fiel auf Blowfish, Grund und verworfene Kandidaten stehen in der Anmerkung.

Der Plan darf sich ändern, aber sichtbar

#

Der Werkbaum am Ende ist nicht der Werkbaum vom Anfang. Die Redirect-Map wurde ein eigenes Arbeitspaket, der Dark Mode wanderte auf „nach dem Cutover“. Jede Änderung ist ein Diff an einer Textdatei und damit Teil der Git-Historie.

Warum sich das für Agentic AI eignet

#

Ich benutze Werkbaum auch ohne AI, z.B. als Diskussiongrundlage bei der Projektplanung mit Kollegen. Aber in der Arbeit mit einem KI-Agenten hat sich der Werkbaum als sehr effektives Werkzeug erwiesen. Die Gründe dafür sind:

Der Plan ist Text im Repository. Der Agent liest und schreibt ihn mit denselben Mitteln wie den Code. Es braucht keine API zu einem Ticket-System, keine Integration, keine Berechtigungen. Und ich sehe jede Änderung am Plan im selben Diff wie die Änderung am Code.

Zerlegung, Abhängigkeiten und Status sind explizit. Ein Agent muss nicht raten, was als Nächstes dran ist. Er sieht, welche Knoten frei sind, welche blockiert, welche [!] tragen und deshalb zuerst geklärt werden müssen. Die T-Shirt-Größen helfen beim Zuschnitt: Ein XS-Knoten ist eine Arbeitseinheit, die ein Agent in einem Anlauf sauber abschließen kann.

Verworfenes bleibt stehen. Das ist für Agenten wichtiger als für Menschen. Ein Agent ohne Gedächtnis schlägt gern wieder vor, was vor zwei Stunden verworfen wurde. Alles steht mit [-] und Begründung im Plan.

Der Plan ist meine Review-Oberfläche. Ich musste nicht jeden Commit lesen. Die Anmerkungen mit Befund und Entscheidung sind genau die Dokumentation, die sonst niemand schreibt.

Entscheidungspunkte für den Menschen sind Knoten. #theme-choice, #switch: Wo der Agent nicht entscheiden soll, steht das im Plan. So bleibt die Autonomie des Agenten groß, ohne dass mir etwas entgleitet.

Das Ergebnis, an der Git-Historie abgelesen: Vom ersten Commit mit dem Plan bis zur abgenommenen Preview auf der Testdomain lag ein Arbeitstag. Der größte Teil meiner eigenen Zeit ging in Entscheidungen und Sichtprüfungen, nicht in die Umsetzung.

Was nicht in den Plan gehört

#

Nach der Abnahme kamen inhaltliche Korrekturen: Profil, Startseitentext, ein Sprachumschalter als Durchklick-Button statt Dropdown, die Audio-Player, die beim Theme-Wechsel verloren gegangen waren. Diese Commits tragen keine Werbaum-ID. Das ist beabsichtigt, denn der Werkbaum plant die Struktur und wesentlichen Features, nicht jedes Detail.

Eine Grenze habe ich auch gesehen: Die Anmerkungen wuchsen im Lauf des Tages auf fast 500 Zeilen. Der Baum selbst blieb übersichtlich, aber wer die Historie einer Entscheidung sucht, muss lesen. Das gerenderte Diagramm zeigt aber die Erläuterungen zu jedem Knoten direkt an.

Stand und Ausblick

#

Die Migration ist fertig, und wenn dieser Artikel online ist, wurde auch das Go-Live durch meine Freigabe auf der Test-Stage abgeschlossen.

Werkbaum selbst kann unter werkbaum.javagil.de ausprobiert werden, der Quellcode steht auf GitEA unter der MIT Lizenz zur Verfügung.

Ein Artikel über meine allgemeine Arbeitsweise bei der Software-Entwicklung mit Agentic AI in etwas größeren Projekten folgt in Kürze.

Dieser Artikel ist mit Unterstützung von KI entstanden.