abdulmubdibindar/opencode-learn

ICM Architect

Baue Arbeitsbereiche, in denen die Ordnerstruktur die Orchestrierung übernimmt. Ein Agent, der die richtigen Dateien im richtigen Moment liest, ersetzt ein Multi-Agenten-Framework: nummerierte Ordner kodieren die Reihenfolge, Hierarchie kodiert die Kontexteingrenzung, einfache Markdown-Dateien kodieren den Zustand. Ein Mensch kann jeden Ordner öffnen und genau sehen, in welchem Zustand sich das System befindet, weil Zustand nur Dateien sind.

Stellen Sie sich den Arbeitsbereich als eine Bibliothek vor. Die Routing-Dateien sind der Katalog: klein, stabil, sie verweisen auf alles und speichern fast nichts. Der Inhalt lebt in den Regalen (Stufenordner, Knotendateien, Referenzmaterial). Ein Bibliothekar – ein Modell – geht durch das Gebäude, und die Frage entscheidet, zu welchem Regal gegangen wird. Niemand fotokopiert die Bibliothek in einen Rucksack; das ist das sogenannte Context-Stuffing. Der Katalog ist absichtlich klein.

Methode: Interpretable Context Methodology (Van Clief & McDermott, arXiv:2603.16021, MIT-lizenziert).

Die Invarianten

Jeder ICM, egal in welcher Form, gehorcht diesen. Beim Bauen oder Umstrukturieren alle zehn durchsetzen:

1. Ein Ordner, eine Aufgabe. Jeder Ordner erledigt einen einzelnen Schritt oder enthält eine einzelne Art von Ding und gibt seinen eigenen Zweck in einer Datei in sich selbst an. Die Struktur ist die Dokumentation.
2. Eine kleine, stabile Einstiegsdatei. CLAUDE.md (oder AGENTS.md) im Stammverzeichnis beantwortet „Wo bin ich, wo lebt alles, wo gehe ich für Aufgabe X hin“ – und sonst nichts. Ziel: unter ~60 Zeilen. Sie routet; sie enthält niemals Inhalt.
3. Nummerierung kodiert die Reihenfolge. 01_, 02_, … wenn die Reihenfolge wichtig ist. Das Umbenennen von Ordnern ordnet die Pipeline neu – das ist der Sinn.
4. Jeder ordnerbezogene Vertrag ist explizit. Ein CONTEXT.md pro Arbeitsordner: was er liest (Eingaben), was er tut (Prozess), was er schreibt (Ausgaben), was ein Mensch überprüft. Siehe assets/templates/stage-CONTEXT.md.
5. Fabrik vs. Produkt. Referenzmaterial (Regeln, Stimme, Schemata, Vorlagen – stabil über Läufe hinweg) lebt strukturell getrennt von Arbeitsartefakten (Ausgaben, Entwürfe – bei jedem Lauf neu). Konfigurieren Sie die Fabrik einmal; das Produkt ist das, was jeder Lauf ausgibt.
6. Jede Ausgabe ist eine Bearbeitungsoberfläche. Zwischenausgaben sind einfache Dateien, die ein Mensch öffnen, bearbeiten und speichern kann, bevor der nächste Schritt sie liest. Nichts geht weiter, bis eine Person die letzte Ausgabe gelesen hat.
7. Lade nur das, was der Schritt benötigt. Ein Agent, der einen Schritt ausführt, liest seinen Vertrag, seine Referenzen und seine Eingaben – nicht den gesamten Arbeitsbereich. 2.000–8.000 Tokens pro Schritt ist der gesunde Bereich.
8. Klartext, verlinkbar, abfragbar. Markdown + YAML-Frontmatter. Links ([[Wikilinks]] oder relative Pfade) machen es zu einem Graphen; Frontmatter-Label machen es abfragbar. Ein Zuhause pro Fakt – ein Link ist besser als eine Kopie.
9. Das Dateisystem ist die Zustandsmaschine. „Status“ ist ableitbar, indem man scannt, was in Ausgabeordnern existiert. Generierte Indizes (Dateizuordnungen, Protokolle) werden per Skript neu erstellt, niemals von Hand bearbeitet.
10. Instanziiere durch Kopieren. Neue Arbeitseinheit = kopiere einen Vorlagenordner, keine leere Seite. Halte Vorlagen in einem _templates/- oder _system/-Ordner.

Wähle einen Modus

• Aufbauend aus einem beschriebenen Prozess, einer Idee oder einem Problem → Aufbaumodus.
• Ein bestehender Ordner, ein Repository oder ein Tresor, der eine ICM-Struktur benötigt → Umstrukturierungsmodus.

Aufbaumodus

1. Extrahiere die Struktur aus dem Dialog. Die Struktur ist bereits darin, wie die Person die Arbeit beschreibt – erzwinge keine Form, sondern bringe ihre ans Licht. Frage (ein paar auf einmal, nicht alle auf einmal):

• Was ist die sich wiederholende Arbeitseinheit? (eine Episode, ein Kunde, ein Bericht, eine Person, ein Team?)
• Führe mich durch einen Durchlauf, von Anfang bis Ende. Wo hältst du an und überprüfst etwas, bevor du fortfährst?
• Was bleibt bei jedem Durchlauf gleich (Stimme, Regeln, Marke, Schema) im Gegensatz zu dem, was bei jedem Durchlauf neu ist?
• Wie sieht „erledigt“ aus – welches Artefakt verlässt den Arbeitsbereich?
• Wer berührt das noch, und was müssen sie finden, ohne dich zu fragen?

Ihre Pausen werden zu Stufengrenzen. Ihre „Ich überprüfe immer X, bevor ich Y tue“ werden zu menschlichen Toren. Ihr „es muss immer klingen wie / folgen Z“ wird zu Fabrikreferenzmaterial.

2. Wähle die Form. Lese references/forms.md und wähle:

Form	Greife danach, wenn
Pipeline	Dieselbe Sequenz läuft wiederholt ab und produziert jedes Mal ein Lieferobjekt
Schirm	Mehrere unterschiedliche Pipelines teilen sich eine Marken-/Stimmen-/Referenzschicht
Datensatzbibliothek	Die Einheit ist ein Datensatz (Person, Kunde, Sitzung), der sich ansammelt, kein Durchlauf
Wissenspaket	Das Produkt ist navigierbares Wissen selbst (ein Gehirn, ein Wiki, ein Modell von etwas)
Kontextkarte	Das Subjekt ist eine Organisation – Teams, Prozesse, Daten und die Verbindungen zwischen ihnen

Reale Arbeitsbereiche mischen Formen (eine Datensatzbibliothek, deren Datensätze Mini-Wissenspakete sind; eine Pipeline, die in eine Datensatzbibliothek ausgibt). Kombiniere frei – die Invarianten gelten auf jeder Ebene, rekursiv.

3. Gerüst für die kleinste Struktur, die die Arbeit trägt. Kopiere Starter aus assets/templates/ und fülle sie aus. Erstelle keine Ordner für Stufen, die noch nicht existieren, leere „Sonstiges“-Eimer oder spekulative Tiefe. Drei reale Stufen schlagen sieben erdachte. Wenn die gesamte Aufgabe in einen einzigen gespeicherten Prompt passt, sage das und baue überhaupt keinen Arbeitsbereich.

4. Schreibe die Verträge. Stamm CLAUDE.md (Identität + Routingtabelle), Stamm CONTEXT.md (die Pipeline- oder Schemadefinition), ein CONTEXT.md pro Stufen-/Hub-Ordner, setup/questionnaire.md, wenn die Fabrik pro Benutzer konfiguriert werden muss. Schreibe Eingaben als explizite Dateipfade, aufgeteilt in Arbeit (dieser Durchlauf) und Referenz (jeder Durchlauf).

5. Validiere mit dem Gehtest (unten).

Umstrukturierungsmodus

1. Bestandsaufnahme vor dem Berühren. Liste den Baum auf. Notiere für jeden Bereich: was es ist, wann zuletzt berührt, was darauf verweist. Lösche oder verschiebe in diesem Durchlauf niemals.

2. Finde die verborgene Form. Frage den Eigentümer (oder schließe daraus und bestätige): Was ist die sich wiederholende Einheit hier? Wo tritt Arbeit ein und aus? Das Chaos enthält normalerweise eine echte Pipeline, Bibliothek oder Karte, die ohne Skelett gewachsen ist – extrahiere sie, ersetze sie nicht. Interview den Ordner, wie du die Person interviewen würdest.

3. Klassifiziere jede Datei in eine von fünf Rollen:

• Katalog – Identität/Routing (wird zu CLAUDE.md / Indexdateien oder speist diese)
• Vertrag – beschreibt, wie ein Schritt funktioniert (wird zu einem CONTEXT.md)
• Fabrik – stabile Referenz (→ _shared/, _system/ oder references/)
• Produkt – laufspezifische Artefakte (→ Stufen-output/ oder Datensatzordner)
• Tot – veraltet, dupliziert oder ersetzt (→ _archive/ vorschlagen, niemals stillschweigend löschen)

4. Vorschlagen vor dem Verschieben. Präsentiere den Zielbaum und eine Migrationskarte (alter Pfad → neuer Pfad → Rolle). Hole Zustimmung ein. Dies ist ein menschliches Tor in einer auf menschlichen Toren aufgebauten Methode – respektiere es.

5. Migrieren. Verschiebe Dateien, schreibe die Einstiegsdatei und Verträge, dedupliziere in Richtung „ein Zuhause pro Fakt“ (hinterlasse einen Link dort, wo die Kopie gelebt hat, falls etwas darauf verweisen könnte). Trenne Methode von Instanz: Wenn die Struktur woanders wiederverwendet wird, lebt die leere Vorlage getrennt von dieser ausgefüllten Bereitstellung.

6. Validiere mit dem Gehtest.

Der Gehtest

Validiere jeden ICM – neu oder umstrukturiert – indem du ihn kalt durchgehst, als Agent ohne Erinnerung:

• Öffne das Stammverzeichnis. Kannst du „Wo bin ich“ und „Wo gehe ich für die aktuelle Aufgabe hin“ innerhalb der Einstiegsdatei plus höchstens zwei weiteren Lesevorgängen beantworten?
• Wähle eine beliebige Stufe / einen beliebigen Knoten aus. Benennt sein Vertrag explizite Eingabepfade, die Aufgabe, die Ausgabe und die menschliche Überprüfung?
• Kannst du den Pipelinestatus allein durch Scannen, was in output/-Ordnern (oder Knoten-Frontmatter) existiert, angeben?
• Trägt irgendeine Routing-Datei Inhaltsdaten? Verschiebe die Daten in ein Regal; hinterlasse einen Zeiger.
• Wird eine Tatsache an zwei Stellen gespeichert? Wähle ein Zuhause; verlinke von der anderen.
• Token-Check: Einstiegsdatei + ein Vertrag + seine Eingaben sollten in etwa 2k–8k Tokens liegen.

Wenn ein Schritt fehlschlägt, behebe die Struktur – nicht indem du mehr erklärst, sondern indem du Dateien verschiebst oder aufteilst, bis der Gehtest funktioniert.

Leitplanken

• Überstrukturiere nicht. Die Leiter läuft: Chat → gespeicherter Prompt/Skill → Ordner + ein Agent. Steige nur auf die nächste Sprosse, wenn die darunter wirklich automatisiert ist und sich wiederholt. Ein Arbeitsbereich für eine zweimal erledigte Sache ist ein Gerüst, keine Architektur.
• Wisse, wo ICM verliert. Echtzeit-Multi-Agenten-Kollaboration, stark frequentierter Mehrbenutzer-Betrieb und automatisierte Verzweigungen in der Mitte der Pipeline benötigen tatsächlich Framework-Code. ICM ist für sequenzielle, von Menschen überprüfte, wiederholbare Arbeit – das ist der Großteil der Wissensarbeit, aber nicht alles.
• In der Wildnis beobachtete Anti-Patterns: duplizierte Einstiegsdateien, die auseinanderdriften (generiere eine aus der anderen oder mache eine zu einem Zeiger); Schemadokumente, die Namen vorschreiben, die die tatsächlichen Dateien nicht mehr verwenden (aktualisiere das Schema oder die Dateien – wähle eins); manuelle Bearbeitungen von generierten Indizes; Workshop-Sitzungen, die Folien anstelle von strukturierten Daten produzieren (jede Arbeitssitzung sollte in einem Artefakt enden, das die Struktur halten kann); von oben herab deklarierte Muster (ein Team, das sich beschwert, ist eine Beschwerde – dieselbe Form, die dreimal unabhängig erscheint, ist eine Struktur).

Referenzen

• references/core.md – die fünf Designprinzipien, die fünfstufige Kontexthierarchie, Namenskonventionen, Token-Disziplin. Lies es beim Schreiben von Verträgen oder wenn eine strukturelle Entscheidung umstritten ist.
• references/forms.md – die fünf Formen im Detail: Skelettbäume, definierende Schritte, Fehlermodi. Lies es bei Schritt 2 des Aufbaumodus oder Schritt 2 des Umstrukturierungsmodus.
• assets/templates/ – kopierbare Starter: CLAUDE.md, Arbeitsbereich CONTEXT.md, stage-CONTEXT.md, node.md, schema.md, questionnaire.md.