From 889cd47be720dd8c29a1ee14d13a72995fcb081b Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Thu, 6 Aug 2026 12:00:00 +0000 Subject: [PATCH] verfahren: Textbausteine fuer Sessions (Workshop #17, Punkt 6) Die Konventionen stehen kanonisch in CLAUDE.md, aber eine Session liest sie nur, wenn sie dazu aufgefordert wird. Diese fuenf Bloecke sind die Aufforderung: Session-Start, Host-Session, Deploy-Uebergabe, Abschluss, Entscheidungsvorlage. Zwei Gestaltungsentscheidungen, beide aus Fehlern dieser Woche: Die Bausteine VERWEISEN auf die Regeln, statt sie zu wiederholen. Waeren sie ausgeschrieben, gaebe es eine zweite Fassung, die driftet - genau das ist am 2026-08-02 passiert, als gitops/CLAUDE.md 'keine Gitea-Ausnahme mehr' behauptete, waehrend management/CLAUDE.md zwei nannte. Und hoechstens acht Zeilen je Block, maschinell geprueft. Der Test ist banal: Wer zum Kopieren scrollen muss, benutzt es nicht. Der Host-Block musste dafuer zweimal umgeschrieben werden; die Deploy-/AAR-Zeile ist rausgeflogen und steht jetzt als Prosa daneben - Prosa muss niemand kopieren. Die Inhalte sind nicht ausgedacht, sondern die Fehler der Woche: erfundene Theme-Paletten statt gelesener Quelle, ein Sweep nach dem Pfad statt nach dem Namen, ein zur Haelfte gelesenes Issue samt uebersehenem Korrekturkommentar, die .netrc-gegen-PRIVATE-TOKEN-Falle und der Ping, der immer fehlschlaegt. Pflegeregel dabei: ergaenzt wird ein Baustein, wenn derselbe Fehler ZWEIMAL passiert ist - nicht vorsorglich. Sonst wachsen sie, bis sie niemand mehr kopiert. Verlinkt aus CLAUDE.md und verfahren/README.md. 59 relative Links geprueft, keiner tot. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01PKhFj1S3UdD6xL2fbWPeYj --- CLAUDE.md | 5 ++ verfahren/README.md | 3 ++ verfahren/textbloecke.md | 109 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 verfahren/textbloecke.md diff --git a/CLAUDE.md b/CLAUDE.md index 5bbc33b..dd182ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,11 @@ Widerspruch gilt für Arbeitsweise und Prozess **diese** Datei. > **Für Sessions ohne Lab-Zugang** (CFGMON, MATRIX, …): dieses Repo ist als > Push-Mirror unter `https://rohana.axion1337.de/sorb/management` von überall > **lesbar** — dort diese Datei und die ADRs nachschlagen. Nur pushen ist tabu. +> +> 📋 **Kopierbare Kurzfassungen zum Voranstellen:** +> [verfahren/textbloecke.md](verfahren/textbloecke.md) — Session-Start, Host-Session, +> Deploy-Übergabe, Abschluss, Entscheidungsvorlage. Diese Datei hier bleibt die +> Quelle; die Bausteine verweisen nur darauf. ## Projektrealitäten (Stand 2026-08-01) diff --git a/verfahren/README.md b/verfahren/README.md index 2a9a781..c1e33fa 100644 --- a/verfahren/README.md +++ b/verfahren/README.md @@ -9,6 +9,9 @@ nicht an einem einzelnen Projekt-Repo hängen. | [aar-vorlage.md](aar-vorlage.md) | Vorlage für den After Action Report nach einem Deploy | | [aar/](aar/) | Abgelegte AARs, benannt `JJJJ-MM-TT-.md` | +[`textbloecke.md`](textbloecke.md) hält kurze, kopierbare Blöcke, die man einer +Session voranstellt — sie verweisen auf die Konventionen, statt sie zu wiederholen. + Die zugehörige Issue-Vorlage liegt unter `.gitlab/issue_templates/Deploy-Übergabe.md` und erscheint beim Anlegen eines Issues in diesem Repo im Auswahlfeld *Description template* als diff --git a/verfahren/textbloecke.md b/verfahren/textbloecke.md new file mode 100644 index 0000000..37c4854 --- /dev/null +++ b/verfahren/textbloecke.md @@ -0,0 +1,109 @@ +# Textbausteine für Sessions + +Kurze, kopierbare Blöcke, die man einer Claude-/Agenten-Session voranstellt. + +Die Konventionen stehen kanonisch in [`CLAUDE.md`](../CLAUDE.md) — aber eine +Session liest sie nur, wenn sie dazu aufgefordert wird. Diese Bausteine sind die +Aufforderung. + +## Zwei Regeln für diese Datei + +**Die Bausteine verweisen auf die Regeln, sie wiederholen sie nicht.** Stünden die +Regeln hier ausgeschrieben, gäbe es eine zweite Fassung, die driftet — real +passiert am 2026-08-02, als `gitops/CLAUDE.md` „keine Gitea-Ausnahme mehr" behauptete, +während die `management/CLAUDE.md` zwei nannte. + +**Höchstens acht Zeilen je Baustein.** Der Test ist banal: Wer zum Kopieren scrollen +muss, benutzt es nicht. Was länger wäre, gehört in die CLAUDE.md — nicht hierher. + +--- + +## 1 · Session-Start (Mac, mit Lab-Zugang) + +``` +Lies zuerst CLAUDE.md im management-Repo auf git.lab und halte dich daran. +Kanonisch ist git.lab; nie direkt nach Gitea pushen. +Alles Offene wird zum Issue, nicht zur Chat-Notiz — auch Nebenbefunde. +Bevor du ein Issue schließt oder darüber urteilst: vollständig lesen, inklusive +Kommentare. +Bevor du aus einer Vorlage/Spezifikation ableitest: die Quelle öffnen, nicht raten. +Verifiziert und vermutet klar trennen; fremde Messungen als fremde kennzeichnen. +``` + +> Die letzten drei Zeilen stehen hier, weil genau das dreimal an einem Tag +> schiefging: erfundene Theme-Paletten statt gelesener Skill-Quelle; ein Sweep nach +> dem Pfad `sorb/Backlogs` statt nach dem Namen `Backlogs`; und ein Issue, von dem +> 750 von 1237 Zeichen gelesen wurden — samt übersehenem Korrekturkommentar, der +> seit 16 Stunden darunterstand. + +## 2 · Host-Session (CFGMON, MATRIX — ohne Lab-Zugang) + +``` +Du arbeitest auf einem Hetzner-Host ohne direkte Lab-Route. +Konventionen: CLAUDE.md im management-Repo — von hier lesbar über den Gitea-Mirror +rohana.axion1337.de/sorb/management. Dort NUR lesen, niemals hinpushen. +Für git.lab (Issues, Pushes) muss sorb erst den Site-to-Site-Tunnel einschalten. +git.lab-API: PRIVATE-TOKEN-Header — .netrc gilt nur für clone/push (sonst 401, +bei privaten Projekten irreführend 404, sieht aus wie "Projekt gibt es nicht"). +Ping auf 10.58.73.17 schlägt IMMER fehl (nur 443 + DNS offen), das ist kein +Tunnelproblem — prüfen mit: curl https://git.lab/users/sign_in +``` + +> Soll in dieser Session etwas ausgerollt werden, kommt **Baustein 3** dazu — der +> Deploy-Weg samt AAR-Pflicht steht dort, nicht hier, damit dieser Block kurz bleibt. + +## 3 · Deploy-Übergabe + +``` +Öffne auf git.lab ein Issue aus der Vorlage "Deploy-Übergabe" +(Feld "Description template") und fülle ALLE Felder — Verfahren und Begründung +je Feld: verfahren/deploy-uebergabe.md. +Pflicht: Stand (Repo/Branch/Commit) · Testtiefe (ehrlich, "ungetestet" ist gültig) +· Mengengerüst (geschätzt oder gemessen, dazuschreiben welches) · vollständiges +Deploy-Kommando inkl. Reload/Recreate · Verifikation DORT WO DER DIENST LIEST +· Außenwirkung und Not-Aus · Rollback · bewusst offen Gelassenes. +Wo nichts zutrifft: "-" eintragen, nicht das Feld löschen. +``` + +## 4 · Abschluss einer Session + +``` +Vor dem Ende prüfen und benennen: +- Alle Commits über git.lab gepusht, kein Rest im Arbeitsverzeichnis, Mirror grün. +- Jeder offene Punkt und Nebenbefund ist ein Issue — nichts bleibt nur im Chat. +- Zeitkritisches trägt ein Datum im due_date-Feld, nicht nur im Fließtext. +- Genau ein status:*-Label je angefasstem Issue; status:wartet nur mit Grund. +- Gedächtnis aktualisiert: nur was kein Repo festhält. +- Wiederaufsetzpunkt in einem Satz: Was ist als Nächstes dran, und wer ist dran? +``` + +## 5 · Entscheidungsvorlage + +``` +Leg mir das als Entscheidung vor, nicht als offene Frage: +2–4 Optionen, je eine Zeile Konsequenz, und deine Empfehlung zuerst mit Begründung. +Sag dazu, was du gemessen und was du angenommen hast. +Wenn die Entscheidung eine dauerhafte Ausnahme von einer Regel schafft, ist sie +ADR-pflichtig (decisions/, siehe CLAUDE.md) — dann leg die ADR gleich mit vor. +``` + +--- + +## Wann welcher + +| Situation | Baustein | +|---|---| +| Neue Session auf dem Mac | 1 | +| Session auf CFGMON/MATRIX/game | 2 | +| Etwas gebautes soll ausgerollt werden | 3 | +| Session neigt sich dem Ende | 4 | +| Eine Frage braucht sorbs Entscheidung | 5 | + +Bausteine 1 und 2 schließen sich aus; 3–5 kommen anlassbezogen dazu. + +## Pflege + +Ein Baustein wird ergänzt, wenn **derselbe Fehler zweimal** passiert ist — nicht +vorsorglich. Sonst wachsen sie, bis sie niemand mehr kopiert, und dann wirken sie +gar nicht mehr. Wächst einer über acht Zeilen, gehört der Inhalt in die CLAUDE.md +und hier bleibt der Verweis.