Mining the Loop: Wie Änderungen zu institutionellem Gedächtnis werden

Die Zahlen in diesem Beitrag spiegeln den Stand des Systems zum Veröffentlichungszeitpunkt (Februar 2026) wider. Aktuelle Zahlen findest du auf unserer Team-Seite.

Jedes Engineering-Team steht vor derselben Herausforderung: Änderungen passieren ständig, aber das Warum dahinter verschwindet. Sechs Monate später fragt jemand „warum haben wir DuckDB für Pipeline-Stages eingeführt?“, und die Antwort lebt nur im Kopf von wem auch immer diese Entscheidung getroffen hat — falls diese Person noch da ist.

Wir haben einen Mining-Workflow gebaut, der diese Lücke schließt. Änderungen fließen durch Git-Commits, werden von unserer Mining-Pipeline verarbeitet, werden zu strukturierten Changelog-Einträgen und Architectural Decision Records, und fließen dann über CLI-Abfragen zurück in unsere KI-Agenten. Das Ergebnis: institutionelles Gedächtnis, auf das sowohl Menschen als auch KI zugreifen können.

Das Problem: Entscheidungen verdunsten

Stell dir ein typisches Szenario vor. Ein Entwickler committet:

feat(canonical): add DuckDB runtime for pipeline stages

Dieser Commit stellt eine bedeutende Architekturentscheidung dar. Das Team hat Optionen bewertet, Trade-offs abgewogen und ist bei DuckDB aus bestimmten Gründen gelandet. Aber der ganze Kontext lebt in:

• Einem Slack-Thread (wahrscheinlich gelöscht)
• Der Erinnerung von jemandem (definitiv verblassend)
• Einem Kommentar im Code (vielleicht, wenn du Glück hast)

Drei Monate später fragt ein neues Teammitglied: „Sollte ich DuckDB oder SQLite für diese neue Stage verwenden?“ Ohne institutionelles Gedächtnis erfinden sie entweder das Rad neu oder treffen inkonsistente Entscheidungen.

Die Loop: Von Commits zu Kontext

Unser Mining-Workflow verwandelt Git-History in abfragbares Wissen:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Die zentrale Erkenntnis: Sowohl Changelogs als auch Architekturentscheidungen fließen aus derselben Git-History, verarbeitet durch eine einheitliche Pipeline. Das stellt sicher, dass nichts durch die Maschen fällt.

Wie Mining funktioniert

Schritt 1: Den Index synchronisieren

uv run orkestra mine sync

Dieser Befehl scannt die Git-History und baut einen Index aller Commits. Er extrahiert strukturierte Signale aus jedem Commit:

• Conventional-Commit-Typ (feat, fix, chore, docs)
• Scope (welches Paket oder welcher Bereich)
• Breaking-Change-Markierungen
• Angefasste Dateien und Komplexitätsmetriken

Schritt 2: Coverage-Status prüfen

uv run orkestra mine status

So sieht unser aktueller Status aus:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 Commits verarbeitet. 476 wurden zu Architekturentscheidungen. 6.799 wurden zu Changelog-Einträgen. Jeder Commit klassifiziert.

Schritt 3: Kandidaten für die Review holen

uv run orkestra mine candidates --limit 50 --full

Das bringt Commits an die Oberfläche, die noch nicht verarbeitet wurden, mit vollständigem Kontext für die Klassifizierung:

on
{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Die Signale helfen bei der Klassifizierung: is_releasable_type: true legt nahe, dass das im Changelog erscheinen sollte. Die große Anzahl an Insertions und die Infrastruktur-Dateien legen nahe, dass es auch eine Architectural Decision sein könnte.

Schritt 4: Commits klassifizieren

Hier trennen sich zwei Pfade: Changelog-Einträge und Architekturentscheidungen.

Für Changelog-Einträge:

uv run orkestra mine classify abc123 --changelog added

Das protokolliert, dass Commit abc123 im Changelog unter der Kategorie „Added“ erscheinen sollte.

Für Architekturentscheidungen:

Zuerst eine echte Decision-ID holen:

uv run orkestra decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Dann mit der Decision-ID klassifizieren:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Das verknüpft den Commit mit einem Decision-Record, der erstellt oder aktualisiert wird.

Für Batch-Verarbeitung (was wir tatsächlich tun):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Das JSONL-Format unterstützt beide Domänen in einem Durchgang:

on
l
{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Schritt 5: Outputs rendern

uv run orkestra changelog render --package <pkg>

Das generiert pro-Paket-CHANGELOG.md-Dateien aus dem Ledger. Die Changelogs sind abgeleitete Artefakte — lösche sie, und sie regenerieren sich perfekt aus dem Quell-Ledger.

Die Struktur des Decision-Records

Extrahierte Decisions werden zu YAML-Dateien mit reichhaltigen Metadaten:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Jede Decision verlinkt zurück zu ihren Quell-Commits. Jede Decision spezifiziert, welche Dateien sie betrifft. Beziehungen zwischen Decisions sind explizit.

CLI-Integration: Institutionelles Gedächtnis abfragen

Hier schließt sich die Loop. Agenten können Decisions über die CLI abfragen:

# Search by topic
uv run orkestra decisions search --query "retry"

Liefert Decisions über Retry-Logik, Fehlerbehandlung, Recovery-Muster.

# Get full details on a specific decision
uv run orkestra decisions info DEC-PL-142

Liefert den vollständigen Decision-Record mit Kontext, Begründung und Auswirkung.

# List recent decisions for context
uv run orkestra decisions list --limit 15

Zeigt, welche Architekturentscheidungen kürzlich getroffen wurden.

Wie Agenten das nutzen

Die Baseline-Instruktionen unseres Orchestrators enthalten:

**Essential CLI commands:**
- `orkestra decisions search "X"` — Architekturentscheidungen finden

Wenn ein Agent gebeten wird, etwas im Zusammenhang mit DuckDB zu implementieren, kann er zuerst prüfen:

uv run orkestra decisions search --query "DuckDB"

Und DEC-PL-142 entdecken und lernen:

• Warum wir DuckDB gewählt haben (context)
• Wie man es richtig verwendet (agent_guidance)
• Welche Dateien man sich ansehen sollte (files)
• Welche verwandten Decisions existieren (related)

Der Agent erfindet das Rad nicht neu. Er baut auf etablierten Mustern auf.

Der Drei-Fragen-Test

Nicht jeder Commit verdient einen Decision-Record. Wir verwenden den Drei-Fragen-Test zum Filtern:

1. War das schwer zu entscheiden? Erforderte es signifikante Analyse, Trade-off-Bewertung oder Debatte?
2. Ist es teuer zu ändern? Würde eine Umkehrung dieser Entscheidung signifikante Nacharbeit erfordern?
3. Hat es systemweite Auswirkungen? Betrifft es mehrere Pakete oder etabliert es Muster, denen andere folgen werden?

Wenn ein Commit mindestens eine dieser Fragen mit „ja“ beantwortet, ist er ein Kandidat für die Decision-Extraktion. Unsere typische Rate: 1–4 Decisions pro 100 Commits (etwa 1–4 %).

Für Changelog-Einträge liegt die Hürde niedriger: Jede nutzersichtbare Änderung (Features, Fixes, Verbesserungen) wird erfasst. Interne Chores, Dokumentations-Updates und Refactorings werden typischerweise übersprungen. Unsere typische Rate: 30–50 Changelog-Einträge pro 100 Commits.

Datenspeicherung: Append-Only-Ledger

Das Mining-System verwendet Append-Only-JSONL-Ledger für konfliktfreien Multi-Agent-Betrieb:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Das JSONL-Format mit merge=union in .gitattributes bedeutet, dass mehrere Agenten Commits gleichzeitig klassifizieren können, ohne Merge-Konflikte. Jede Zeile ist unabhängig.

Validierungs-Gates

Vor jeder Mining-Session führen wir eine Validierung durch:

uv run orkestra mine validate --quick

Das prüft:

• Gültigkeit des SHA-Formats
• Einhaltung des Decision-ID-Formats
• Keine doppelten Einträge für denselben SHA
• Referenzierte Decisions existieren tatsächlich

Nach der Klassifizierung validieren wir erneut, bevor Änderungen committet werden.

Warum das wichtig ist

Die Feedback-Loop, die wir gebaut haben, löst mehrere Probleme:

Für neue Teammitglieder: Statt zu fragen „warum haben wir X gemacht?“, können sie die Decisions-Registry durchsuchen. Der Kontext bleibt erhalten.

Für KI-Agenten: Sie operieren nicht im luftleeren Raum. Sie können institutionelles Wissen abfragen, bevor sie Empfehlungen aussprechen. Wenn sie gebeten werden, eine neue Pipeline-Stage hinzuzufügen, können sie das DuckDB-Muster entdecken und ihm folgen.

Für Architekturkonsistenz: Decisions sind explizit und durchsuchbar. Wenn jemand einen Ansatz vorschlägt, der einer bestehenden Decision widerspricht, kann das System den Konflikt sichtbar machen.

Für die Changelog-Generierung: Release Notes sind kein Last-Minute-Gehetze. Sie sind ein Nebenprodukt kontinuierlicher Klassifizierung während der Entwicklung.

Für Onboarding: Neue Agenten erben den vollen Kontext der Codebase. Sie sehen nicht nur den Code — sie sehen die Entscheidungen, die ihn geformt haben.

Aktueller Stand

Stand heute:

• 15.637 Commits durch die Pipeline verarbeitet
• 476 Architekturentscheidungen extrahiert und dokumentiert
• 6.799 Changelog-Einträge erfasst
• 100 % Coverage über beide Domänen hinweg

Jeder Commit seit unserem Start wurde klassifiziert. Das institutionelle Gedächtnis ist vollständig und abfragbar.

Erste Schritte

Wenn du etwas Ähnliches umsetzen willst:

1. Beginne mit Conventional Commits. Die Mining-Pipeline funktioniert am besten, wenn Commits strukturierte Präfixe haben (feat:, fix:, chore:).

2. Definiere deine Domänen. Wir verwenden Domänen wie pipeline, agent-design, observability, data-modeling. Diese organisieren Decisions nach Bereich.

3. Baue die Klassifizierungs-Gewohnheit auf. Mining funktioniert, wenn Teams regelmäßig Commits klassifizieren. Batch-Verarbeitung mit LLM-Unterstützung hilft bei der Skalierung.

4. Mache Decisions abfragbar. Der Wert verstärkt sich, wenn Agenten Decisions über die CLI durchsuchen können. Strukturiere deine Ausgabe für maschinellen Konsum.

5. Schließe die Loop. Decisions sollten zukünftige Arbeit beeinflussen. Nimm Decision-Referenzen in Agent-Instruktionen und Code-Review-Checklisten auf.

Das Ziel ist nicht perfekte Dokumentation. Es ist, das Warum hinter Änderungen sowohl für Menschen als auch für KI zugänglich zu machen, heute und in sechs Monaten. Wenn Änderungen zu institutionellem Gedächtnis werden, bauen Teams auf etablierten Mustern auf, statt sie neu zu erfinden.

---

Der Mining-Workflow ist Teil unserer Orchestrierungs-Engine, genauer gesagt des Context-Engine-Moduls in unserem Orchestration-Paket.