Failed to generate image: PlantUML preprocessing failed: [From <input> (line 18) ]

@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Entwicklung der Sessions — Von der Session 1 bis 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Aktive Sitzungen" as S

@S
0 is ".md roh"
1 is "Migration
^^^^^
 Syntax Error? (Assumed diagram type: timing)

@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Entwicklung der Sessions — Von der Session 1 bis 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Aktive Sitzungen" as S

@S
0 is ".md roh"
1 is "Migration
AsciiDoc"
10 is "Eager/Lazy
formalisiert"
62 is "Sicherheitsregel
(site.yml)"
87 is "Knacken\nKontext"
109 is "Optimierung
-60% Tokens"
133 is "133 Sitzungen\n240 Tests bestanden"

S@0 -> S@1 : Session 1\n(cheroliv.com)
S@1 -> S@10
S@10 -> S@62 : Session 62\n(plantuml-plugin)
S@62 -> S@87 : Session 87\n(Cry 4 help)
S@87 -> S@109 : Session 109\n(API Key Pool)
S@109 -> S@133 : Session 133\n(Aujourd'hui)

@enduml

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 7) ]

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Projekt-Root (Eager - automatisch geladen)" {
    component "<b>AGENT.adoc</b>\nAbsolute Regeln\nStruktur & Konventionen" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>
^^^^^
 Syntax Error? (Assumed diagram type: component)

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Projekt-Root (Eager - automatisch geladen)" {
    component "<b>AGENT.adoc</b>\nAbsolute Regeln\nStruktur & Konventionen" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>
Mission der Sitzung N
Zusammenfassung N-1" as PROMPT
    component "<b>INDEX.adoc</b>
Einstiegspunkt
Regeln + Sitzungen" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nGeschäftskontext\nkritisch" as ESS
}

package ".agents/ (Lazy - bei Bedarf geladen)" {
    component "<b>sessions/N-*.adoc</b>\nDetaillierte Archive\nEntscheidungen & Ausgabe" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nZusammenfassungstabelle\nDatum/Typ/Punktzahl" as HIST
    component "<b>PROCEDURES.adoc</b>
Vorlagen für das Ende der Sitzung
6 Schritte" as PROC
    component "<b>*_REFERENCE.adoc</b>\nVollständige Architektur\nTechnische Referenzen" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nErledigte Aufgaben\nPro Monat" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nStrategiedokumentation\nMethodik" as MOD
    component "<b>*_REFERENCE.adoc</b>
Boot tests, A/B partition
Spezifische Kontexte" as SPEC
}

AGENT --> PROMPT : "Referenzen"
AGENT --> INDEX : "Referenzen"
INDEX --> SESS : "indexiert"
INDEX --> HIST : "indexiert"
INDEX --> PROC : "Referenz"
INDEX --> ARCH : "Referenz"
INDEX --> REF : "Referenz"
PROMPT --> SESS : "Archiv N-1"
PROMPT --> ESS : "Fachkontext"

@enduml

----
----
| magic-stick    | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 |
| bakery-gradle  | Session 11 | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| cheroliv.com   | Session 9  | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS   | 2026-04-23 |
| jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 |
----

**`*_ESSENTIALS.adoc`** -- Ein kürzlich hinzugefügter Beitrag (Session 109, plantuml-plugin) zur weiteren Optimierung des Eager-Kontextes. Anstatt 200 Zeilen des Geschäfts-Kontexts im API-Schlüssel-Pool zu laden, lade ich 50 Zeilen des Wesentlichen und die übrigen 150 Zeilen bleiben im LAZY-Modus in`*_REFERENCE.adoc`.

Gemessenes Ergebnis: Übergang von**~25k tokens EAGER zu ~10k tokens**(Gewinn von 60%). Der Agent braucht keine energieintensiven Erinnerungen mehr.

==== Das fehlende Glied:`opencode.json

Ich muss Ihnen gestehen, dass ich fast vergessen hätte, es zu dokumentieren. Über allen diesen Dateien `.adoc` befindet sich eine winzige JSON-Datei, ohne die nichts funktioniert. Es heißt`opencode.json`und er ist sechs Zeilen lang. Wörtlich sechs Zeilen.

[source,json]
----
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENT.adoc"
  ]
}
----

Diese Datei sagt Opencode: « Beim Start laden`AGENT.adoc` automatisch. » Ohne ihn ist der Agent ein leeres Blatt genau wie ich es zu Beginn des Artikels beschrieben habe. Mit ihm hat der Agent bereits die absoluten Regeln, die Projektarchitektur und die essentiellen Befehle in der Hand — bevor ich überhaupt Guten Tag gesagt habe.

Ich habe die Bedeutung dieser Datei zufällig entdeckt. Auf`bakery-plugin`, es existierte nicht. Ich fragte mich, warum der Agent auf diesem Projekt systematisch mehr « verloren » war als bei den anderen. Die absoluten Regeln waren gut in`AGENT.adoc`— aber`AGENT.adoc`war nie geladen. Der Agent las nur das, was ich ihm sagte zu lesen, manuell, bei jeder Sitzung. Es war die Sitzung 11 von`bakery-plugin`Als ich die Abwesenheit des bemerkte`opencode.json`. Ich habe es erstellt — und die Sitzung 12 begann wie die anderen.

Diese Datei ist für mich jetzt so offensichtlich, dass ich überhaupt nicht mehr daran denke. Ein klassischer Fehler eines Entwicklers, der sein Werkzeug zu gut kennt. Heute erstelle ich es systematisch *avant`AGENT.adoc`. Das ist der erste Stein.

==== Die Dualität von `INDEX.adoc

Eine weitere Subtilität, die es wert ist, ausdrücklich benannt zu werden:`INDEX.adoc`lebt in`.agents/`— Dieses Dokument habe ich als LAZY angegeben. Trotzdem führe ich es in all meinen Tabellen als EAGER auf. Hier besteht eine erkennbare Spannung.

Die Realität vor Ort: die Dateien`.agents/INDEX.adoc`werden automatisch zu Beginn der Sitzung gut geladen, ebenso wie`AGENT.adoc` et `PROMPT_REPRISE.adoc`. Sie sind in`.agents/`aus organisatorischen Gründen — nicht das Root-Verzeichnis bevölkern — aber ihr Verhalten ist EAGER

Auf`plantuml-plugin`, `INDEX.adoc`Es hat 200 Zeilen und enthält die absoluten Regeln *vollständig* mit ihrer Historie (die Lehren aus den vergangenen Sitzungen), die EPICs mit Punktzahlen, und das Projektportfolio. Das ist das Dokument, das der Agent konsultiert, um zu wissen « wo wir stehen ». Auf`bakery-plugin`, er hat 150 Zeilen mit der Roadmap und den neuesten Sitzungen

Die freiwillige Redundanz zwischen`AGENT.adoc` et `INDEX.adoc`kann überraschend sein. Absolute Regeln sind in beiden vorhanden. Warum? Weil sie zwei verschiedene Rollen erfüllen: in`AGENT.adoc`, sie sind *explicatives* (das Storytelling der Regel, die gelernte Lektion); in`INDEX.adoc`, sie sind *ausführend* (die nackte Regel, ohne Begründung, für eine schnelle Konsultation). Der Agent liest`AGENT.adoc`einmal zum Verstehen ; er liest es noch einmal`INDEX.adoc`zu jeder Sitzung für *anwenden*. Zwei Verwendungen, zwei Formate.

[plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"]
----
@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center

title Dualität AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc
(Wurzel — EAGER)" as AGENT #E3F2FD {
  rectangle "�📖 **Narratives Format**
Das Storytelling der Regel
die gelernte Lektion, der Kontext" as NARR
  rectangle "🏗️ **Vollständige Architektur**
Projektstruktur, Komponenten
Detaillierter Backlog US" as ARCHI
  rectangle "📋 **Erklärende Regeln**
Warum existiert die Regel?
Verlauf des Vorfalls" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **Ausführendes Format**
Die nackte Regel, ohne Begründung
Schnelle Konsultation" as EXEC
  rectangle "�📊 **Roadmap & EPICs**\nZusammenfassungstabelle\nFortschritt, Score, Priorität" as ROAD
  rectangle "�🌐 **Projektportfolio**
Queransicht
5 synchronisierte Projekte" as PORT
}

AGENT --> INDEX : "Agent liest AGENT.adoc\n1 Mal zum **verstehen**"
INDEX --> AGENT : "Agent liest INDEX.adoc erneut
für jede Sitzung zum **anwenden**"

note bottom of AGENT
  Taille max : 200 lignes
end note

note bottom of INDEX
  Taille max : 200 lignes
  Source de vérité en cas de divergence
end note

@enduml
----

Diese akzeptierte Redundanz ist eine Designentscheidung. Sie verbraucht etwa 50 zusätzliche Zeilen von EAGER‑Tokens — aber sie gewährleistet, dass der Agent stets die Regeln vor Augen hat, einschließlich im knappen Format, das sofortige Gehorsam erleichtert.

=== Die LAZY-Dateien: Das Handbuch des Eigentümers

Diese Dateien leben in`.agents/`und werden nur gelesen, wenn der Agent sie benötigt. Sie bilden den wahren Reichtum der Methode, denn sie sammeln das Projektwissen, ohne den aktuellen Kontext zu verunreinigen.

[plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"]
----
@startuml
skinparam folderBackgroundColor #E3F2FD
skinparam folderBorderColor #1565C0
skinparam fileBackgroundColor #FFF3E0
skinparam fileBorderColor #EF6C00

folder ".agents/" as ROOT {
  file "INDEX.adoc
(EAGER -- 200 Zeilen)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc
(Vorlagensitzung)" as ASM
  file "SESSION_CHECKLIST.adoc\n(Wann ändern)" as CHK
  file "PROCEDURES.adoc
(6 Schritte + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc
(Alle Sitzungen)" as HIS

  folder "Sitzungen/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-Formalisierung-lazy.adoc" as S109 #FFECB3
    file "133-epic11-artikel.adoc" as S133
    file "... +130 andere" as SMORE
  }

  folder "Archive/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "sessions_zusammenfassungen/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "prompts_archive/" as PARCH {
      file "PROMPT_REPRISE_S65.adoc" as PR65
      file "PROMPT_REPRISE_S75.adoc" as PR75
      file "..." as PMORE
    }
  }
}

IDX --> SESS : "indiziert"
IDX --> HIS : "indiziert"
IDX --> ARCH : "Referenz"

note right of S109
  Session 109 =
  Formalisation stratégie
  LAZY/EAGER
  Token : ~25k → ~10k
end note

@enduml
----

Die obige Baumstruktur zeigt die tatsächliche Ordnerstruktur`.agents/`auf`plantuml-plugin`, das reifste Projekt. Beachte die Tiefe in drei Schichten: Stammdateien (Metadaten), Ordner`sessions/`(chronologische Archive), und Akte`archives/`(Aggregationen und Zusammenfassungen). Diese Tiefe verwandelt die Governance einer einfachen TODO-Datei in eine**vollständiges organisatorisches Gedächtnis**.

**.agents/sitzungen/{N}-{titel}.adoc**Die detaillierten Aufzeichnungen jeder Sitzung. Derzeit:

* `plantuml-plugin` : **133 archivierte Sitzungen**(von der Sitzung 1 bis 133)
* `bakery-plugin`:**11 Sitzungen**
* `magic-stick` : **23 Sitzungen**
* `cheroliv.com`:**9 formelle Sitzungen**+ 7 Sitzungen vor dem System wurden rückwirkend rekonstruiert

Jedes Archiv enthält den vollständigen Kontext der Sitzung, die getroffenen Entscheidungen, die aufgetretenen Probleme und deren Lösung, die ausgeführten Befehle und ihre Ausgabe.

**.agents/SESSIONS_HISTORY.adoc**-- Eine Zusammenfassungstabelle aller Sitzungen mit einem Score. Beispiel auf`cheroliv.com` :

----

| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 |  1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 |  7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 |  8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10

**.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc**Abgeschlossene Aufgaben werden monatlich archiviert, um den aktiven Backlog nicht zu überladen. Wenn eine User Story abgeschlossen ist, wird sie hierhin verschoben. Der Backlog bleibt übersichtlich: maximal 10 aktive Elemente.

**.agents/PROCEDURES.adoc**-- Detaillierte Vorlagen des Sitzungsende-Verfahrens. Lang, aber nur einmal vom Agenten gelesen, wenn er die Methode lernt. Dann wird das Verfahren mechanisch.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- Die vollständige strategische Dokumentation. Auf`plantuml-plugin`, Diese Datei macht**900+ Zeilen**und er/sie heißt tatsächlich`AGENT_METHODOLOGIES.adoc`— Ich habe den Namen zwischen dem Schreiben dieses Artikels und der praktischen Implementierung geändert. Diese Art von Namensabweichung ist in einem sich entwickelnden handwerklichen System unvermeidlich. Wichtig ist die Namenskonvention: Wenn die Datei die *Methode* dokumentiert, beginnt sie mit`AGENT_`oder ein explizites Präfix. Es dokumentiert die Eager/Lazy-Methodik, die zu befolgenden Muster, die zu vermeidenden Anti-Muster. Es ist LAZY, weil ein Agent nicht die gesamte Strategie in jeder Sitzung nachlesen muss, nur wenn es Unklarheit gibt.

**`*_REFERENCE.adoc`** -- Die projektspezifischen technischen Referenzen. Auf`magic-stick`, zwei dichte LAZY Dateien:

* `AB_PARTITION_REFERENCE.adoc`(147 Zeilen) -- Architektur Partition A/B GPT, Skripte`update-system.sh`, geschätzte Größen, Rollback-Mechanismus
* `BOOT_TEST_REFERENCE.adoc`(144 Zeilen) -- Verfahren QEMU + VNC zum Testen des Boots der ISO ohne physische Hardware, Checkliste BIOS/UEFI, Einschränkungen CI/CD

Auf`plantuml-plugin`:

* `ARCHITECTURE.adoc`(134 Zeilen) -- Struktur der 11 Data-Klassen, Aufmerksamkeitspunkte (zu vermeidende Fallstricke), optimierte Testbefehle
* `API_KEY_POOL_REFERENCE.adoc`-- Vollständige Details des Schlüsselpools (LAZY während`ESSENTIALS`ist EAGER)

== Die Spezialagenten: Ein virtuelles Team

Die Governance beschränkt sich nicht auf passive Dateien. Ich habe formalisierte**Rollen spezialisierter Agenten**in dedizierten LAZY-Dateien, die den erwarteten Workflow je nach Aufgabentyp definieren.

|===
|Agent |Datei |Rolle |Projekt |**kodieren** |`CODER.adoc` |Implementierung FTL/CSS/JS, semantische Tags, Zugänglichkeitskriterien |cheroliv.com |**Scrum-Master** |`SCRUM_MASTER.adoc` |US-Planung, Aufteilung in Unteraufgaben, Erkennung der Abhängigkeiten |cheroliv.com |**PlantUML-Designer** |`PLANTUML_DESIGNER.adoc` |Erstellung von Diagrammen, PUML-Syntax, JBake-Integration |cheroliv.com
|===

Die Datei`CODER.adoc`auf`cheroliv.com`enthält konkrete Regeln: _einzige`<h1>`pro Seite_, _Pfade mit Präfix versehen`${content.rootpath}`_, _Die Sprache deklarieren`<html lang="${content.lang!"fr"}">`_. Diese Konventionen, einmal geschrieben, werden vom Agenten seit Sitzung 1 automatisch eingehalten.

Die Datei`SCRUM_MASTER.adoc`Vorgibt eine Lieferstruktur :**Ziel**, **Aufgaben**(Koordinaten mit Zuweisung)**Akzeptanzkriterien**, **Risiken**. Wenn ich einen Aktionsplan anfordere, erstellt der Agent diese Struktur, ohne dass ich sie verlangt habe. Die Governance**Programm**der Agent.

==== Wenn die Spezialagenten unverzichtbar werden

Die Erstellung der spezialisierten Agenten folgt einer natürlichen Kurve. Zu Beginn eines Projekts brauchen Sie sie nicht —`AGENT.adoc`reicht völlig aus. Aber wenn das Projekt wächst (sagen wir, über 20 Sitzungen), sollten zwei Signale Sie alarmieren:

1. Der Agent mischt die Konventionen zweier unterschiedlicher Bereiche (z.B. PlantUML-Syntax und CSS-Regeln)
2. Du verbringst mehr Zeit damit, den Agenten wegen Konventionen zu korrigieren, die du ihm bereits fünfmal erklärt hast.

Auf`cheroliv.com`, es ist in der Sitzung passiert... 1. Ja, von Anfang an. Weil dieses Projekt eine Website mit drei Sprachen (FTL, CSS, JS) ist, AsciiDoc-Inhalt und PlantUML-Diagramme enthält — drei Bereiche, die nichts gemeinsam haben. Der Agent CODER muss die Schriftgrößen und Media Queries kennen; der Agent PLANTUML_DESIGNER muss die Syntax kennen.`@startuml`. Ohne Trennung bot mir der CODER-Agent Diagramme an, und umgekehrt. Das Chaos.

auf`jhipster-gradle-plugins`, ich habe zwei spezialisierte Agenten für die Entwicklung von Gradle-Plugins erstellt:`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. Der erste kodiert alle Kotlin/Gradle-Konventionen (keine`!!`, Datenklassen für die Modelle,`@TaskAction`pour die Aufgaben). Der Zweite weiß, dass`persistence`muss stabil sein bevor`assistant`startet seine Entwicklung nicht — eine kritische Abhängigkeit in einem Monorepo.

Der Fehler, den man nicht machen sollte: zu viele Agenten zu früh erstellen.`plantuml-plugin`hat die Session 108 abgewartet, bevor ein spezialisierter Agent für den Pool von API-Schlüsseln formalisiert wurde. Bis dahin lag der fachliche Kontext in`AGENT.adoc`. Die Faustregel: Ein spezialisierter Agent ist gerechtfertigt, wenn sein Fachgebiet mehr als 100 Dokumentationszeilen umfasst.

==== Die Namenskonvention der Sitzungen

Ein Detail, das trivial erscheint, aber kritisch wird, wenn man 100 Sitzungen erreicht hat. Wie sollen die Archivdateien benannt werden?

Ich habe auf die harte Tour gelernt, dass eine Konvention notwendig ist — vier Projekte, vier unterschiedliche Formate zu Beginn, und ich habe den Überblick verloren. Heute ist die Konvention, die ich festgelegt habe, :

Konkrete Beispiele:

* `1-chore-migration-gouvernance-agent.adoc`— Sitzung 1, Typ Aufgabe
* `10-solidification-tests.adoc`— Sitzung 10, ohne expliziten Typ (das Subjekt reicht aus)
* `036-debug-graphify-symlink-epic9.adoc`— Sitzung 36 mit dreistelliger Nummer für die Sortierung

Die Sitzungsnummer ist das Hauptkriterium für die Sortierung. Projekte, die Nummern mit drei Stellen (001, 036, 133) verwenden, vermeiden Probleme bei der lexikografischen Sortierung, wenn man über 99 hinausgeht. Das ist, was ich jetzt auf`magic-stick`(Note: The user provided no text to translate after the colon, so the output is empty.)`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

Der Typ ist optional und wird aus den Session-Schlüsselwörtern abgeleitet (debug, feature, refactor, docs, chore, test). Der Betreff im kebab-case ist der wichtigste Teil: Er muss es ermöglichen, eine Sitzung ohne Öffnen der Datei wiederzufinden. Wenn du dich fragst, welche Sitzung das war, in der wir den Timeout der Integrations-Tests behoben haben, lautet die Antwort`124-fix-timeout-integration-test.adoc`.

Für die historisch rekonstruierten Sitzungen (Projekte, die vor der Governance entstanden sind), verwende ich negative Zahlen. Auf`cheroliv.com`, die Sitzungen -6 bis 0 decken die gesamte Vor-Governance-Geschichte des Projekts ab. Und für die Sitzungen « nicht dokumentiert » oder verloren, erstelle ich einen Eintrag in`SESSIONS_HISTORY.adoc`Ohne entsprechendes Archiv, mit einer Punktzahl`?`. Es ist ehrlicher als vorzutäuschen.

[plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]

==== TEST_COVERAGE_ANALYSIS.adoc` — Der Schritt 5 im Detail

Schritt 5 des Verfahrens zur Sitzungsbeendigung ist das Geheimnisvollste. Sie sagt « Aktualisieren`TEST_COVERAGE_ANALYSIS.adoc`Wenn Tests hinzugefügt oder geändert wurden. » Wie sieht diese Datei aus?

auf`plantuml-plugin`, er hat sich von einigen Zeilen zu einer vollständigen Struktur entwickelt. Hier ist seine stabile Form :

[source]