Mining smyčky: jak se ze změn stává 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.

Každý inženýrský tým čelí stejné výzvě: změny se dějí neustále, ale proč za nimi zmizí. 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 nepropadne skulinami.

Jak mining funguje

Krok 1: Synchronizace indexu

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í

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

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

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

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

Signály pomáhají vést klasifikaci: is_releasable_type: true naznačuje, že by se to mělo objevit v changelogu. Vysoký počet vložení 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:

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í:

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

Pak klasifikujte s tímto ID rozhodnutí:

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):

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

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

Krok 5: Vykreslení výstupů

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

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:

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

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

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

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

# List recent decisions for context
uv run orkestra 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í:

**Essential CLI commands:**
- `orkestra 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:

uv run orkestra 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 tohle těžké udělat? 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:

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í onoho proč za změnami 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.