Mining Gelung: Bagaimana Perubahan Menjadi Memori Institusi

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Februari 2026). Lihat halaman pasukan kami untuk angka terkini.

Setiap pasukan kejuruteraan menghadapi cabaran yang sama: perubahan berlaku secara berterusan, tetapi sebab di sebalik perubahan itu hilang begitu sahaja. Enam bulan kemudian, seseorang bertanya “mengapa kita mengadaptasi DuckDB untuk stage pipeline?” dan jawapannya hanya wujud dalam kepala sesiapa yang membuat keputusan itu — jika mereka masih ada.

Kami membina aliran kerja mining yang menutup gelung ini. Perubahan mengalir melalui commit git, diproses oleh pipeline mining kami, menjadi entri changelog berstruktur dan rekod keputusan seni bina, kemudian disalurkan semula kepada ejen AI kami menerusi pertanyaan CLI. Hasilnya: memori institusi yang boleh dicapai oleh manusia dan AI.

Masalahnya: Keputusan Menguap Hilang

Pertimbangkan satu senario biasa. Seorang developer melakukan commit:

feat(canonical): add DuckDB runtime for pipeline stages

Commit ini mewakili satu pilihan seni bina yang signifikan. Pasukan itu menilai pilihan, mempertimbangkan trade-off, dan akhirnya memilih DuckDB atas sebab-sebab tertentu. Tetapi kesemua konteks itu hanya wujud dalam:

• Satu thread Slack (kemungkinan besar telah dipadam)
• Ingatan seseorang (pasti semakin pudar)
• Satu komen dalam kod (mungkin, jika anda bertuah)

Tiga bulan kemudian, ahli pasukan baharu bertanya: “Patutkah saya guna DuckDB atau SQLite untuk stage baharu ini?” Tanpa memori institusi, mereka sama ada mencipta semula roda atau membuat pilihan yang tidak konsisten.

Gelung Itu: Daripada Commit Kepada Konteks

Aliran kerja mining kami mengubah sejarah git menjadi pengetahuan yang boleh dipertanyakan:

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

Pandangan utamanya: kedua-dua changelog dan keputusan seni bina mengalir daripada sejarah git yang sama, diproses menerusi satu pipeline bersatu. Ini memastikan tiada apa-apa yang terlepas pandang.

Bagaimana Mining Berfungsi

Langkah 1: Segerakkan Indeks

uv run orkestra mine sync

Arahan ini mengimbas sejarah git dan membina satu indeks bagi semua commit. Ia mengekstrak isyarat berstruktur daripada setiap commit:

• Jenis commit konvensional (feat, fix, chore, docs)
• Scope (package atau kawasan yang mana)
• Penanda breaking change
• Fail yang disentuh dan metrik kerumitan

Langkah 2: Semak Status Liputan

uv run orkestra mine status

Berikut rupa status semasa kami:

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 commit diproses. 476 menjadi keputusan seni bina. 6,799 menjadi entri changelog. Setiap commit diklasifikasikan.

Langkah 3: Dapatkan Calon Untuk Semakan

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

Ini memaparkan commit yang belum diproses lagi, dengan konteks penuh untuk pengklasifikasian:

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

Isyarat itu membantu membimbing pengklasifikasian: is_releasable_type: true mencadangkan ini patut muncul dalam changelog. Kiraan insertion yang besar dan fail infrastruktur mencadangkan ia mungkin juga satu keputusan seni bina.

Langkah 4: Klasifikasikan Commit

Dua laluan bercabang di sini: entri changelog dan keputusan seni bina.

Untuk entri changelog:

uv run orkestra mine classify abc123 --changelog added

Ini merekodkan bahawa commit abc123 patut muncul dalam changelog di bawah kategori “Added.”

Untuk keputusan seni bina:

Pertama, dapatkan ID keputusan yang sebenar:

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

Kemudian klasifikasikan dengan ID keputusan itu:

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

Ini memautkan commit itu kepada satu rekod keputusan yang akan dicipta atau dikemas kini.

Untuk pemprosesan kelompok (apa yang sebenarnya kami lakukan):

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

Format JSONL menyokong kedua-dua domain dalam satu pusingan:

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

Langkah 5: Render Output

uv run orkestra changelog render --package <pkg>

Ini menjana fail CHANGELOG.md setiap package daripada ledger. Changelog adalah artifak terbitan — padamkannya dan ia akan dijana semula dengan sempurna daripada ledger sumber.

Struktur Rekod Keputusan

Keputusan yang diekstrak menjadi fail YAML dengan metadata yang kaya:

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

Setiap keputusan memaut kembali kepada commit sumbernya. Setiap keputusan menentukan fail mana yang terlibat. Hubungan antara keputusan adalah eksplisit.

Integrasi CLI: Mempertanyakan Memori Institusi

Di sinilah gelung itu ditutup. Ejen boleh mempertanyakan keputusan menerusi CLI:

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

Memulangkan keputusan tentang logik cuba semula, pengendalian ralat, corak pemulihan.

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

Memulangkan rekod keputusan yang lengkap dengan konteks, rasional, dan kesan.

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

Menunjukkan pilihan seni bina apa yang telah dibuat baru-baru ini.

Bagaimana Ejen Menggunakan Ini

Arahan garis dasar orchestrator kami merangkumi:

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

Apabila seorang ejen diminta untuk melaksanakan sesuatu yang berkaitan dengan DuckDB, ia boleh menyemak dahulu:

uv run orkestra decisions search --query "DuckDB"

Dan menemui DEC-PL-142, mempelajari:

• Mengapa kami memilih DuckDB (context)
• Bagaimana menggunakannya dengan betul (agent_guidance)
• Fail apa yang perlu dilihat (files)
• Keputusan berkaitan apa yang wujud (related)

Ejen itu tidak mencipta semula roda. Ia membina di atas corak yang telah ditetapkan.

Ujian Tiga Soalan

Bukan setiap commit layak mendapat rekod keputusan. Kami menggunakan Ujian Tiga Soalan untuk menapis:

1. Adakah ini sukar untuk dibuat? Adakah ia memerlukan analisis, penilaian trade-off, atau perdebatan yang signifikan?
2. Adakah ia mahal untuk diubah? Adakah membatalkan keputusan ini memerlukan kerja semula yang signifikan?
3. Adakah ia mempunyai kesan seluruh sistem? Adakah ia menjejaskan pelbagai package atau mewujudkan corak yang akan diikuti oleh yang lain?

Jika sesuatu commit menjawab “ya” kepada sekurang-kurangnya satu soalan ini, ia adalah calon untuk pengekstrakan keputusan. Kadar biasa kami: 1-4 keputusan bagi setiap 100 commit (kira-kira 1-4%).

Untuk entri changelog, kayu ukurnya lebih rendah: sebarang perubahan yang dilihat pengguna (ciri, pembaikan, penambahbaikan) direkodkan. Chore dalaman, kemas kini dokumentasi, dan refaktor lazimnya dilangkau. Kadar biasa kami: 30-50 entri changelog bagi setiap 100 commit.

Penyimpanan Data: Ledger Append-Only

Sistem mining menggunakan ledger JSONL append-only untuk operasi pelbagai-ejen yang bebas konflik:

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 dengan merge=union dalam .gitattributes bermakna pelbagai ejen boleh mengklasifikasikan commit secara serentak tanpa konflik merge. Setiap baris adalah bebas.

Gate Pengesahan

Sebelum sebarang sesi mining, kami menjalankan pengesahan:

uv run orkestra mine validate --quick

Ini menyemak:

• Kesahihan format SHA
• Pematuhan format ID keputusan
• Tiada entri pendua untuk SHA yang sama
• Keputusan yang dirujuk benar-benar wujud

Selepas pengklasifikasian, kami mengesahkan semula sebelum melakukan commit perubahan.

Mengapa Ini Penting

Gelung maklum balas yang kami bina menyelesaikan beberapa masalah:

Untuk ahli pasukan baharu: Selain bertanya “mengapa kita buat X?”, mereka boleh mencari registri keputusan. Konteks itu terpelihara.

Untuk ejen AI: Mereka tidak beroperasi dalam ruang hampa. Mereka boleh mempertanyakan pengetahuan institusi sebelum membuat cadangan. Apabila diminta menambah satu stage pipeline baharu, mereka boleh menemui corak DuckDB dan mengikutinya.

Untuk konsistensi seni bina: Keputusan bersifat eksplisit dan boleh dicari. Apabila seseorang mencadangkan pendekatan yang bercanggah dengan keputusan sedia ada, sistem boleh memaparkan konflik itu.

Untuk penjanaan changelog: Nota pelepasan bukan lagi tergesa-gesa saat akhir. Ia adalah hasil sampingan daripada pengklasifikasian berterusan semasa pembangunan.

Untuk onboarding: Ejen baharu mewarisi konteks penuh pangkalan kod. Mereka bukan sahaja melihat kod — mereka melihat keputusan yang membentuknya.

Keadaan Semasa

Setakat hari ini:

• 15,637 commit diproses melalui pipeline
• 476 keputusan seni bina diekstrak dan didokumenkan
• 6,799 entri changelog direkodkan
• Liputan 100% merentasi kedua-dua domain

Setiap commit sejak kami bermula telah diklasifikasikan. Memori institusi itu lengkap dan boleh dipertanyakan.

Bermula

Jika anda ingin melaksanakan sesuatu yang serupa:

1. Mulakan dengan commit konvensional. Pipeline mining berfungsi terbaik apabila commit mempunyai prefix berstruktur (feat:, fix:, chore:).

2. Takrifkan domain anda. Kami menggunakan domain seperti pipeline, agent-design, observability, data-modeling. Ini menyusun keputusan mengikut kawasan.

3. Bina tabiat pengklasifikasian. Mining berfungsi apabila pasukan kerap mengklasifikasikan commit. Pemprosesan kelompok dengan bantuan LLM membantu penskalaan.

4. Jadikan keputusan boleh dipertanyakan. Nilainya berganda apabila ejen boleh mencari keputusan menerusi CLI. Strukturkan output anda untuk penggunaan mesin.

5. Tutup gelung itu. Keputusan patut mempengaruhi kerja masa depan. Sertakan rujukan keputusan dalam arahan ejen dan senarai semak semakan kod.

Matlamatnya bukan dokumentasi yang sempurna. Ia adalah menjadikan sebab di sebalik perubahan boleh dicapai oleh manusia dan AI, hari ini dan enam bulan dari sekarang. Apabila perubahan menjadi memori institusi, pasukan membina di atas corak yang telah ditetapkan dan bukannya mencipta semula.

---

Aliran kerja mining adalah sebahagian daripada enjin orkestrasi kami, khususnya modul enjin konteks dalam package orkestrasi kami.