# Wiedza z historii zmian zamyka pętlę: jak zmiany stają się pamięcią instytucjonalną

Canonical source: https://maguyva.ai/pl/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

> Commity git stają się ustrukturyzowanymi wpisami changeloga i rekordami decyzji architektonicznych, a następnie wracają do agentów AI jako przeszukiwalna pamięć instytucjonalna.

> *Liczby w tym wpisie odzwierciedlają system w momencie publikacji (luty 2026). Aktualne dane znajdziesz na naszej [stronie zespołu](/pl/team).*

Każdy zespół inżynieryjny mierzy się z tym samym wyzwaniem: zmiany zachodzą nieustannie, ale *powód* tych zmian znika. Sześć miesięcy później ktoś pyta „dlaczego przyjęliśmy DuckDB dla etapów pipeline'u?”, a odpowiedź żyje tylko w głowie osoby, która podjęła tę decyzję — jeśli w ogóle jeszcze tu jest.

Zbudowaliśmy przepływ pracy wydobywczy (mining), który zamyka tę pętlę. Zmiany przepływają przez commity git, są przetwarzane przez nasz pipeline wydobywczy, stają się ustrukturyzowanymi wpisami changeloga i rekordami decyzji architektonicznych, a następnie wracają do naszych agentów AI przez zapytania CLI. Wynik: pamięć instytucjonalna, do której mają dostęp zarówno ludzie, jak i AI.

## Problem: decyzje wyparowują

Rozważ typowy scenariusz. Deweloper commituje:

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

Ten commit reprezentuje istotny wybór architektoniczny. Zespół ocenił opcje, rozważył kompromisy i wybrał DuckDB z konkretnych powodów. Ale cały ten kontekst żyje w:

- Wątku na Slacku (prawdopodobnie usuniętym)
- Pamięci kogoś (zdecydowanie blaknącej)
- Komentarzu w kodzie (może, jeśli masz szczęście)

Trzy miesiące później nowy członek zespołu pyta: „Powinienem użyć DuckDB czy SQLite dla tego nowego etapu?”. Bez pamięci instytucjonalnej albo wymyśla koło na nowo, albo dokonuje niespójnych wyborów.

## Pętla: od commitów do kontekstu

Nasz przepływ pracy wydobywczy zamienia historię git w przeszukiwalną wiedzę:

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

Kluczowa obserwacja: zarówno changelogi, jak i decyzje architektoniczne wypływają z tej samej historii git, przetwarzanej przez ujednolicony pipeline. To zapewnia, że nic nie umknie.

## Jak działa wydobywanie

### Krok 1: Synchronizacja indeksu

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

To polecenie skanuje historię git i buduje indeks wszystkich commitów. Wyodrębnia ustrukturyzowane sygnały z każdego commita:

- Typ zgodny ze standardem Conventional Commits (`feat`, `fix`, `chore`, `docs`)
- Zakres (który pakiet lub obszar)
- Znaczniki zmian łamiących kompatybilność
- Dotknięte pliki i metryki złożoności

### Krok 2: Sprawdzenie statusu pokrycia

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

Oto jak wygląda nasz obecny status:

```
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 przetworzonych commitów. 476 stało się decyzjami architektonicznymi. 6799 stało się wpisami changeloga. Każdy commit sklasyfikowany.

### Krok 3: Uzyskanie kandydatów do przeglądu

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

To wydobywa commity, które nie zostały jeszcze przetworzone, wraz z pełnym kontekstem do klasyfikacji:

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

Sygnały pomagają w klasyfikacji: `is_releasable_type: true` sugeruje, że powinno się to znaleźć w changelogu. Duża liczba wstawień i pliki infrastrukturalne sugerują, że może to być też decyzja architektoniczna.

### Krok 4: Klasyfikacja commitów

W tym miejscu rozchodzą się dwie ścieżki: wpisy changeloga i decyzje architektoniczne.

**Dla wpisów changeloga:**

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

To zapisuje, że commit `abc123` powinien pojawić się w changelogu w kategorii „Dodano”.

**Dla decyzji architektonicznych:**

Najpierw uzyskaj prawdziwy identyfikator decyzji:

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

Następnie klasyfikuj z identyfikatorem decyzji:

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

To łączy commit z rekordem decyzji, który zostanie utworzony lub zaktualizowany.

**Do przetwarzania wsadowego (co faktycznie robimy):**

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

Format JSONL obsługuje obie domeny w jednym przebiegu:

```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: Renderowanie wyników

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

To generuje pliki `CHANGELOG.md` dla poszczególnych pakietów na podstawie ledgera. Changelogi są artefaktami pochodnymi — usuń je, a wygenerują się na nowo idealnie z ledgera źródłowego.

## Struktura rekordu decyzji

Wyodrębnione decyzje stają się plikami YAML z bogatymi metadanymi:

```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żda decyzja odsyła z powrotem do swoich commitów źródłowych. Każda decyzja określa, których plików dotyczy. Relacje między decyzjami są jednoznaczne.

## Integracja CLI: odpytywanie pamięci instytucjonalnej

Tu właśnie zamyka się pętla. Agenci mogą odpytywać decyzje przez CLI:

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

Zwraca decyzje dotyczące logiki ponawiania, obsługi błędów, wzorców odzyskiwania.

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

Zwraca kompletny rekord decyzji z kontekstem, uzasadnieniem i wpływem.

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

Pokazuje, jakie wybory architektoniczne zostały podjęte ostatnio.

### Jak agenci tego używają

Bazowe instrukcje naszego orkiestratora zawierają:

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

Gdy agent zostaje poproszony o zaimplementowanie czegoś związanego z DuckDB, może najpierw sprawdzić:

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

I odkryć DEC-PL-142, dowiadując się:
- Dlaczego wybraliśmy DuckDB (kontekst)
- Jak używać go poprawnie (agent_guidance)
- Na które pliki spojrzeć (files)
- Jakie powiązane decyzje istnieją (related)

Agent nie wymyśla koła na nowo. Opiera się na ustalonych wzorcach.

## Test trzech pytań

Nie każdy commit zasługuje na rekord decyzji. Używamy testu trzech pytań, aby filtrować:

1. **Czy to było trudne do podjęcia?** Czy wymagało znaczącej analizy, oceny kompromisów lub debaty?
2. **Czy kosztowna jest zmiana tego?** Czy cofnięcie tej decyzji wymagałoby znacznego nakładu pracy?
3. **Czy ma wpływ na cały system?** Czy wpływa na wiele pakietów lub ustanawia wzorce, które inni będą naśladować?

Jeśli commit odpowiada „tak” na przynajmniej jedno z tych pytań, jest kandydatem do ekstrakcji decyzji. Nasz typowy wskaźnik: 1-4 decyzje na 100 commitów (około 1-4%).

Dla wpisów changeloga próg jest niższy: każda zmiana widoczna dla użytkownika (funkcje, poprawki, usprawnienia) zostaje zapisana. Wewnętrzne porządki, aktualizacje dokumentacji i refaktoryzacje zazwyczaj są pomijane. Nasz typowy wskaźnik: 30-50 wpisów changeloga na 100 commitów.

## Przechowywanie danych: ledgery tylko do dopisywania

System wydobywczy używa ledgerów JSONL tylko do dopisywania (append-only) dla bezkonfliktowej pracy wieloagentowej:

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

Format JSONL z `merge=union` w `.gitattributes` oznacza, że wielu agentów może klasyfikować commity jednocześnie bez konfliktów scalania. Każda linia jest niezależna.

## Kontrole walidacyjne

Przed każdą sesją wydobywczą uruchamiamy walidację:

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

Sprawdza to:
- Poprawność formatu SHA
- Zgodność formatu identyfikatora decyzji
- Brak zduplikowanych wpisów dla tego samego SHA
- Czy przywoływane decyzje faktycznie istnieją

Po klasyfikacji walidujemy ponownie przed zatwierdzeniem zmian.

## Dlaczego to ma znaczenie

Pętla sprzężenia zwrotnego, którą zbudowaliśmy, rozwiązuje kilka problemów:

**Dla nowych członków zespołu:** Zamiast pytać „dlaczego zrobiliśmy X?”, mogą przeszukać rejestr decyzji. Kontekst jest zachowany.

**Dla agentów AI:** Nie działają w próżni. Mogą odpytywać wiedzę instytucjonalną, zanim wydadzą rekomendację. Poproszeni o dodanie nowego etapu pipeline'u, mogą odkryć wzorzec DuckDB i się go trzymać.

**Dla spójności architektonicznej:** Decyzje są jednoznaczne i przeszukiwalne. Gdy ktoś proponuje podejście sprzeczne z istniejącą decyzją, system może uwidocznić ten konflikt.

**Dla generowania changeloga:** Notatki wydania nie są gorączkowym pośpiechem w ostatniej chwili. Są produktem ubocznym ciągłej klasyfikacji podczas rozwoju.

**Dla onboardingu:** Nowi agenci dziedziczą pełny kontekst bazy kodu. Widzą nie tylko kod — widzą decyzje, które go ukształtowały.

## Stan obecny

Na dziś:
- **15 637 commitów** przetworzonych przez pipeline
- **476 decyzji architektonicznych** wyodrębnionych i udokumentowanych
- **6799 wpisów changeloga** zapisanych
- **100% pokrycia** w obu domenach

Każdy commit od momentu, gdy zaczęliśmy, został sklasyfikowany. Pamięć instytucjonalna jest kompletna i przeszukiwalna.

## Jak zacząć

Jeśli chcesz wdrożyć coś podobnego:

1. **Zacznij od standardu Conventional Commits.** Pipeline wydobywczy działa najlepiej, gdy commity mają ustrukturyzowane prefiksy (`feat:`, `fix:`, `chore:`).

2. **Zdefiniuj swoje domeny.** Używamy domen takich jak `pipeline`, `agent-design`, `observability`, `data-modeling`. Organizują one decyzje według obszaru.

3. **Zbuduj nawyk klasyfikacji.** Wydobywanie działa, gdy zespoły regularnie klasyfikują commity. Przetwarzanie wsadowe ze wsparciem LLM pomaga skalować.

4. **Uczyń decyzje przeszukiwalnymi.** Wartość kumuluje się, gdy agenci mogą przeszukiwać decyzje przez CLI. Nadaj wynikom strukturę odpowiednią do przetwarzania maszynowego.

5. **Zamknij pętlę.** Decyzje powinny wpływać na przyszłą pracę. Uwzględnij odniesienia do decyzji w instrukcjach agentów i listach kontrolnych przeglądu kodu.

Celem nie jest idealna dokumentacja. Chodzi o to, by *powód* stojący za zmianami był dostępny zarówno dla ludzi, jak i AI, dziś i za sześć miesięcy. Gdy zmiany stają się pamięcią instytucjonalną, zespoły opierają się na ustalonych wzorcach zamiast wymyślać je na nowo.

---

*Przepływ pracy wydobywczy jest częścią naszego silnika orkiestracji, konkretnie modułu silnika kontekstu w naszym pakiecie orkiestracji.*