# Mining im Kreislauf: Wie Änderungen zu institutionellem Gedächtnis werden

Canonical source: https://maguyva.ai/de/blog/mining-workflow-closing-the-loop

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-02-03 · Author: Maguyva Team

> Git-Commits werden zu strukturierten Changelog-Einträgen und Architectural Decision Records und fließen dann als abfragbares institutionelles Gedächtnis zurück in KI-Agents.

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

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 der Person, die 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-Agents. 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

```bash
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

```bash
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

```bash
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:

```json
{
  "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:**

```bash
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:

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

Dann mit der Decision-ID klassifizieren:

```bash
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):**

```bash
# 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:

```jsonl
{"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

```bash
uv run orkestra registry 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:

```yaml
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. Agents können Decisions über die CLI abfragen:

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

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

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

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

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

Zeigt, welche Architekturentscheidungen kürzlich getroffen wurden.

### Wie Agents das nutzen

Die Baseline-Instruktionen unseres Orchestrators enthalten:

```markdown
**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions
```

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

```bash
uv run orkestra registry 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 Agents 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:

```bash
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-Agents:** 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 Agents 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 Agents 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.*