# Mining smyčky: jak se ze změn stává institucionální paměť

Canonical source: https://maguyva.ai/cs/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 commity se mění na strukturované záznamy changelogu a architektonická rozhodnutí, a ty se pak vrací zpátky do AI agentů jako dotazovatelná institucionální paměť.

> *Čísla v tomto příspěvku odrážejí stav systému v době zveřejnění (únor 2026). Aktuální čísla najdete na naší [stránce týmu](/cs/team).*

Každý inženýrský tým čelí stejné výzvě: změny se dějí neustále, ale důvody těchto změn se ztrácejí. O půl roku později se někdo zeptá „proč jsme pro pipeline stages přešli na DuckDB?“ a odpověď žije jen v hlavě toho, kdo to rozhodnutí udělal — pokud je ještě poblíž.

Postavili jsme mining workflow, který tuhle smyčku uzavírá. Změny proudí přes git commity, zpracuje je naše mining pipeline, promění se na strukturované záznamy changelogu a architektonická rozhodnutí a pak se vrátí zpátky do našich AI agentů přes CLI dotazy. Výsledek: institucionální paměť, ke které mají přístup lidé i AI.

## Problém: rozhodnutí se vypařují

Zvažte typický scénář. Vývojář commitne:

```
feat(canonical): add DuckDB runtime for pipeline stages
```

Tenhle commit představuje významnou architektonickou volbu. Tým vyhodnotil možnosti, zvážil kompromisy a rozhodl se pro DuckDB z konkrétních důvodů. Ale celý ten kontext žije v:

- Vlákně na Slacku (pravděpodobně smazaném)
- Něčí paměti (rozhodně blednoucí)
- Komentáři v kódu (možná, pokud máte štěstí)

O tři měsíce později se nový člen týmu zeptá: „Mám pro tenhle nový stage použít DuckDB, nebo SQLite?“ Bez institucionální paměti buď znovu vynalézají kolo, nebo dělají nekonzistentní rozhodnutí.

## Smyčka: od commitů ke kontextu

Náš mining workflow proměňuje historii gitu na dotazovatelné znalosti:

```
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)     │
      └───────────────┘
```

Klíčový postřeh: changelogy i architektonická rozhodnutí plynou ze stejné historie gitu, zpracované jednotnou pipeline. Díky tomu nic nezapadne.

## Jak mining funguje

### Krok 1: Synchronizace indexu

```bash
uv run orkestra mine sync
```

Tenhle příkaz proskenuje historii gitu a postaví index všech commitů. Z každého commitu extrahuje strukturované signály:

- Typ konvenčního commitu (`feat`, `fix`, `chore`, `docs`)
- Scope (který balíček nebo oblast)
- Značky breaking change
- Dotčené soubory a metriky složitosti

### Krok 2: Kontrola stavu pokrytí

```bash
uv run orkestra mine status
```

Takhle vypadá náš aktuální stav:

```
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 zpracovaných commitů. 476 se stalo architektonickými rozhodnutími. 6 799 se stalo záznamy changelogu. Každý commit je klasifikovaný.

### Krok 3: Získání kandidátů k review

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

Tím se zobrazí commity, které ještě nebyly zpracované, s plným kontextem pro klasifikaci:

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

Signály pomáhají vést klasifikaci: `is_releasable_type: true` naznačuje, že by se to mělo objevit v changelogu. Velké množství přidaných řádků a soubory infrastruktury naznačují, že by to mohlo být i architektonické rozhodnutí.

### Krok 4: Klasifikace commitů

Tady se cesty rozdvojují: záznamy changelogu a architektonická rozhodnutí.

**Pro záznamy changelogu:**

```bash
uv run orkestra mine classify abc123 --changelog added
```

Tím se zaznamená, že by se commit `abc123` měl objevit v changelogu pod kategorií „Added“.

**Pro architektonická rozhodnutí:**

Nejdřív získejte skutečné ID rozhodnutí:

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

Pak klasifikujte s tímto ID rozhodnutí:

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

Tím se commit propojí se záznamem rozhodnutí, který se vytvoří nebo aktualizuje.

**Pro dávkové zpracování (co ve skutečnosti děláme):**

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

Formát JSONL podporuje obě domény v jednom průchodu:

```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"}
```

### Krok 5: Vykreslení výstupů

```bash
uv run orkestra registry changelog render --package <pkg>
```

Tím se z ledgeru vygenerují soubory `CHANGELOG.md` pro jednotlivé balíčky. Changelogy jsou odvozené artefakty — smažte je a dokonale se znovu vygenerují ze zdrojového ledgeru.

## Struktura záznamu rozhodnutí

Extrahovaná rozhodnutí se stávají YAML soubory s bohatými metadaty:

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

Každé rozhodnutí odkazuje zpátky na své zdrojové commity. Každé rozhodnutí specifikuje, které soubory ovlivňuje. Vztahy mezi rozhodnutími jsou explicitní.

## Integrace s CLI: dotazování institucionální paměti

Tady se smyčka uzavírá. Agenti mohou rozhodnutí dotazovat přes CLI:

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

Vrátí rozhodnutí o retry logice, zpracování chyb a vzorcích zotavení.

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

Vrátí kompletní záznam rozhodnutí s kontextem, zdůvodněním a dopadem.

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

Ukáže, jaká architektonická rozhodnutí byla nedávno učiněna.

### Jak to agenti používají

Základní instrukce našeho orchestrátoru zahrnují:

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

Když je agent požádán, aby implementoval něco souvisejícího s DuckDB, může nejdřív zkontrolovat:

```bash
uv run orkestra registry decisions search --query "DuckDB"
```

A objevit DEC-PL-142, kde se dozví:
- Proč jsme zvolili DuckDB (kontext)
- Jak ho správně používat (agent_guidance)
- Do kterých souborů se podívat (files)
- Jaká související rozhodnutí existují (related)

Agent nevynalézá znovu kolo. Staví na zavedených vzorcích.

## Test tří otázek

Ne každý commit si zaslouží záznam rozhodnutí. K filtrování používáme test tří otázek:

1. **Bylo těžké toto rozhodnutí přijmout?** Vyžadovalo to významnou analýzu, vyhodnocení kompromisů nebo debatu?
2. **Je nákladné to změnit?** Vyžadovalo by zvrácení tohoto rozhodnutí významnou práci navíc?
3. **Má to celosystémový dopad?** Ovlivňuje to více balíčků, nebo zakládá vzorce, kterými se budou řídit další?

Pokud commit na aspoň jednu z těchto otázek odpoví „ano“, je kandidátem na extrakci rozhodnutí. Náš typický poměr: 1–4 rozhodnutí na 100 commitů (zhruba 1–4 %).

U záznamů changelogu je laťka nižší: zaznamená se každá změna viditelná pro uživatele (funkce, opravy, vylepšení). Interní úklid, aktualizace dokumentace a refaktoring se obvykle přeskočí. Náš typický poměr: 30–50 záznamů changelogu na 100 commitů.

## Ukládání dat: append-only ledgery

Mining systém používá append-only JSONL ledgery pro bezkonfliktní operace více agentů najednou:

```
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
    └── ...
```

Formát JSONL s `merge=union` v `.gitattributes` znamená, že více agentů může klasifikovat commity současně bez merge konfliktů. Každý řádek je nezávislý.

## Validační brány

Před každou mining session spouštíme validaci:

```bash
uv run orkestra mine validate --quick
```

Ta kontroluje:
- Platnost formátu SHA
- Shodu s formátem ID rozhodnutí
- Žádné duplicitní záznamy pro stejné SHA
- Že odkazovaná rozhodnutí skutečně existují

Po klasifikaci validujeme znovu, ještě než změny commitneme.

## Proč na tom záleží

Zpětnovazební smyčka, kterou jsme postavili, řeší několik problémů:

**Pro nové členy týmu:** Místo aby se ptali „proč jsme udělali X?“, mohou prohledat registr rozhodnutí. Kontext je zachovaný.

**Pro AI agenty:** Neoperují ve vakuu. Mohou se dotázat na institucionální znalosti dřív, než dají doporučení. Když jsou požádáni o přidání nového stage do pipeline, mohou objevit vzorec DuckDB a řídit se jím.

**Pro architektonickou konzistenci:** Rozhodnutí jsou explicitní a prohledatelná. Když někdo navrhne přístup, který odporuje existujícímu rozhodnutí, systém dokáže konflikt vynést na povrch.

**Pro generování changelogu:** Poznámky k vydání nejsou honička na poslední chvíli. Jsou vedlejším produktem průběžné klasifikace během vývoje.

**Pro onboarding:** Noví agenti dědí plný kontext kódové základny. Nevidí jen kód — vidí i rozhodnutí, která ho utvářela.

## Aktuální stav

K dnešnímu dni:
- **15 637 commitů** zpracováno přes pipeline
- **476 architektonických rozhodnutí** extrahováno a zdokumentováno
- **6 799 záznamů changelogu** zaznamenáno
- **100% pokrytí** napříč oběma doménami

Každý commit od chvíle, kdy jsme začali, je klasifikovaný. Institucionální paměť je kompletní a dotazovatelná.

## Jak začít

Pokud chcete implementovat něco podobného:

1. **Začněte s konvenčními commity.** Mining pipeline funguje nejlépe, když mají commity strukturované prefixy (`feat:`, `fix:`, `chore:`).

2. **Definujte své domény.** My používáme domény jako `pipeline`, `agent-design`, `observability`, `data-modeling`. Ty organizují rozhodnutí podle oblasti.

3. **Vybudujte si návyk klasifikace.** Mining funguje, když týmy pravidelně commity klasifikují. Dávkové zpracování s asistencí LLM pomáhá škálovat.

4. **Udělejte rozhodnutí dotazovatelná.** Hodnota roste s tím, jak agenti mohou rozhodnutí prohledávat přes CLI. Strukturujte svůj výstup pro strojové zpracování.

5. **Uzavřete smyčku.** Rozhodnutí by měla ovlivňovat budoucí práci. Zahrňte odkazy na rozhodnutí do instrukcí pro agenty a checklistů pro code review.

Cílem není dokonalá dokumentace. Je to zpřístupnění důvodů těchto změn lidem i AI, dnes i za šest měsíců. Když se změny stanou institucionální pamětí, týmy stavějí na zavedených vzorcích místo toho, aby je znovu vynalézaly.

---

*Mining workflow je součástí našeho orchestračního enginu, konkrétně modulu kontextového enginu v našem orchestračním balíčku.*