Döngüyü Madenlemek: Değişiklikler Kurumsal Hafızaya Nasıl Dönüşür

Bu yazıdaki sayılar, yayınlandığı tarihteki (Şubat 2026) sistemi yansıtır. Güncel rakamlar için ekip sayfamıza bakın.

Her mühendislik ekibi aynı zorlukla karşılaşır: değişiklikler sürekli olur, ama bu değişikliklerin arkasındaki neden kaybolur gider. Altı ay sonra biri “pipeline aşamaları için neden DuckDB’yi benimsedik?” diye sorar ve yanıt yalnızca o kararı verenin kafasında yaşar — hâlâ ortalardaysa.

Bu döngüyü kapatan bir madencilik iş akışı kurduk. Değişiklikler git commit’leri üzerinden akar, madencilik hattımız tarafından işlenir, yapılandırılmış değişiklik günlüğü girdilerine ve mimari karar kayıtlarına dönüşür, ardından CLI sorguları üzerinden yapay zeka ajanlarımıza geri beslenir. Sonuç: hem insanların hem de yapay zekanın erişebileceği kurumsal hafıza.

Sorun: Kararlar Buharlaşır

Tipik bir senaryo düşünün. Bir geliştirici şunu commit eder:

feat(canonical): add DuckDB runtime for pipeline stages

Bu commit önemli bir mimari seçimi temsil eder. Ekip seçenekleri değerlendirdi, ödünleşimleri (trade-off) göz önünde bulundurdu ve belirli nedenlerle DuckDB’de karar kıldı. Ama tüm o bağlam şurada yaşar:

• Bir Slack konuşması (muhtemelen silinmiş)
• Birinin hafızası (kesinlikle soluklaşan)
• Koddaki bir yorum (belki, şanslıysanız)

Üç ay sonra, yeni bir ekip üyesi sorar: “Bu yeni aşama için DuckDB mi yoksa SQLite mi kullanmalıyım?” Kurumsal hafıza olmadan, ya tekerleği yeniden icat ederler ya da tutarsız seçimler yaparlar.

Döngü: Commit’lerden Bağlama

Madencilik iş akışımız git geçmişini sorgulanabilir bilgiye dönüştürür:

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

Kilit içgörü: hem değişiklik günlükleri hem de mimari kararlar aynı git geçmişinden, birleşik bir hat üzerinden işlenerek akar. Bu, hiçbir şeyin gözden kaçmamasını sağlar.

Madencilik Nasıl Çalışır

Adım 1: İndeksi Senkronize Et

uv run orkestra mine sync

Bu komut git geçmişini tarar ve tüm commit’lerin bir indeksini oluşturur. Her commit’ten yapılandırılmış sinyaller çıkarır:

• Geleneksel commit türü (feat, fix, chore, docs)
• Kapsam (hangi paket veya alan)
• Kırıcı değişiklik işaretleri
• Dokunulan dosyalar ve karmaşıklık metrikleri

Adım 2: Kapsam Durumunu Kontrol Et

uv run orkestra mine status

Mevcut durumumuz şöyle görünüyor:

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 işlendi. 476’sı mimari karara dönüştü. 6.799’u değişiklik günlüğü girdisine dönüştü. Her commit sınıflandırıldı.

Adım 3: İnceleme İçin Adayları Al

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

Bu, sınıflandırma için tam bağlamla birlikte henüz işlenmemiş commit’leri ortaya çıkarır:

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

Sinyaller sınıflandırmaya rehberlik etmeye yardımcı olur: is_releasable_type: true bunun değişiklik günlüğünde görünmesi gerektiğini önerir. Büyük ekleme sayısı ve altyapı dosyaları, bunun bir mimari karar da olabileceğini önerir.

Adım 4: Commit’leri Sınıflandır

Burada iki yol ayrılır: değişiklik günlüğü girdileri ve mimari kararlar.

Değişiklik günlüğü girdileri için:

uv run orkestra mine classify abc123 --changelog added

Bu, abc123 commit’inin değişiklik günlüğünde “Added” kategorisi altında görünmesi gerektiğini kaydeder.

Mimari kararlar için:

Önce gerçek bir karar kimliği alın:

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

Ardından karar kimliğiyle sınıflandırın:

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

Bu, commit’i oluşturulacak veya güncellenecek bir karar kaydına bağlar.

Toplu işleme için (gerçekte yaptığımız şey):

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

JSONL biçimi tek bir geçişte her iki alanı da destekler:

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

Adım 5: Çıktıları Render Et

uv run orkestra changelog render --package <pkg>

Bu, deftere dayanan pakete özgü CHANGELOG.md dosyaları üretir. Değişiklik günlükleri türetilmiş eserlerdir — onları silin ve kaynak defterden kusursuz bir şekilde yeniden oluşurlar.

Karar Kaydı Yapısı

Çıkarılan kararlar, zengin meta veriye sahip YAML dosyalarına dönüşür:

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

Her karar, kaynak commit’lerine geri bağlanır. Her karar hangi dosyaları etkilediğini belirtir. Kararlar arasındaki ilişkiler açıktır.

CLI Entegrasyonu: Kurumsal Hafızayı Sorgulamak

Döngünün kapandığı yer burasıdır. Ajanlar CLI üzerinden kararları sorgulayabilir:

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

Yeniden deneme mantığı, hata işleme, kurtarma desenleri hakkındaki kararları döndürür.

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

Bağlam, gerekçe ve etkiyle birlikte tam karar kaydını döndürür.

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

Son zamanlarda hangi mimari seçimlerin yapıldığını gösterir.

Ajanlar Bunu Nasıl Kullanıyor

Orkestratörümüzün temel talimatları şunları içerir:

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

Bir ajandan DuckDB ile ilgili bir şey uygulaması istendiğinde, önce şunu kontrol edebilir:

uv run orkestra decisions search --query "DuckDB"

Ve DEC-PL-142’yi keşfedip şunları öğrenebilir:

• Neden DuckDB’yi seçtiğimiz (context)
• Nasıl doğru kullanılacağı (agent_guidance)
• Hangi dosyalara bakılacağı (files)
• Hangi ilgili kararların var olduğu (related)

Ajan tekerleği yeniden icat etmez. Yerleşik desenler üzerine inşa eder.

Üç Soru Testi

Her commit bir karar kaydını hak etmez. Filtrelemek için Üç Soru Testini kullanırız:

1. Bunu yapmak zor muydu? Önemli analiz, ödünleşim değerlendirmesi veya tartışma gerektirdi mi?
2. Değiştirmesi maliyetli mi? Bu kararı tersine çevirmek önemli bir yeniden çalışma gerektirir mi?
3. Sistem geneli bir etkisi var mı? Birden fazla paketi etkiliyor mu veya başkalarının izleyeceği desenler oluşturuyor mu?

Bir commit bu sorulardan en az birine “evet” yanıtı veriyorsa, karar çıkarımı için bir adaydır. Tipik oranımız: her 100 commit’te 1-4 karar (yaklaşık %1-4).

Değişiklik günlüğü girdileri için çıta daha düşüktür: kullanıcıya yönelik herhangi bir değişiklik (özellikler, düzeltmeler, iyileştirmeler) kaydedilir. İç işler, dokümantasyon güncellemeleri ve yeniden yapılandırmalar genellikle atlanır. Tipik oranımız: her 100 commit’te 30-50 değişiklik günlüğü girdisi.

Veri Depolama: Yalnızca Ekleme Defterleri

Madencilik sistemi, çakışmasız çok ajanlı işlem için yalnızca ekleme yapılan (append-only) JSONL defterleri kullanır:

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

.gitattributes içindeki merge=union’a sahip JSONL biçimi, birden fazla ajanın birleştirme çakışması olmadan aynı anda commit’leri sınıflandırabileceği anlamına gelir. Her satır bağımsızdır.

Doğrulama Kapıları

Herhangi bir madencilik oturumundan önce doğrulama çalıştırırız:

uv run orkestra mine validate --quick

Bu şunları kontrol eder:

• SHA biçimi geçerliliği
• Karar kimliği biçimi uyumluluğu
• Aynı SHA için yinelenen girdi olmaması
• Referans verilen kararların gerçekten var olması

Sınıflandırmadan sonra, değişiklikleri commit etmeden önce tekrar doğrularız.

Bunun Neden Önemli Olduğu

Kurduğumuz geri bildirim döngüsü birkaç sorunu çözer:

Yeni ekip üyeleri için: “Neden X’i yaptık?” diye sormak yerine, karar kayıt defterini arayabilirler. Bağlam korunur.

Yapay zeka ajanları için: Boşlukta çalışmazlar. Öneride bulunmadan önce kurumsal bilgiyi sorgulayabilirler. Yeni bir pipeline aşaması eklemesi istendiğinde, DuckDB desenini keşfedip onu izleyebilirler.

Mimari tutarlılık için: Kararlar açık ve aranabilirdir. Biri mevcut bir kararla çelişen bir yaklaşım önerdiğinde, sistem çatışmayı gün yüzüne çıkarabilir.

Değişiklik günlüğü üretimi için: Yayın notları son dakika telaşı değildir. Geliştirme sırasındaki sürekli sınıflandırmanın bir yan ürünüdür.

Katılım için: Yeni ajanlar kod tabanının tam bağlamını devralır. Yalnızca kodu görmezler — onu şekillendiren kararları da görürler.

Mevcut Durum

Bugün itibarıyla:

• Hat üzerinden 15.637 commit işlendi
• 476 mimari karar çıkarıldı ve belgelendi
• 6.799 değişiklik günlüğü girdisi kaydedildi
• Her iki alanda da %100 kapsam

Başladığımızdan beri her commit sınıflandırıldı. Kurumsal hafıza eksiksiz ve sorgulanabilir.

Başlarken

Benzer bir şey uygulamak isterseniz:

1. Geleneksel commit’lerle başlayın. Madencilik hattı, commit’ler yapılandırılmış öneklere (feat:, fix:, chore:) sahip olduğunda en iyi şekilde çalışır.

2. Alanlarınızı tanımlayın. pipeline, agent-design, observability, data-modeling gibi alanlar kullanıyoruz. Bunlar kararları alana göre düzenler.

3. Sınıflandırma alışkanlığını oluşturun. Madencilik, ekipler commit’leri düzenli olarak sınıflandırdığında çalışır. LLM yardımıyla toplu işleme ölçeklenmeye yardımcı olur.

4. Kararları sorgulanabilir hale getirin. Değer, ajanlar kararları CLI üzerinden arayabildiğinde katlanarak artar. Çıktınızı makine tüketimi için yapılandırın.

5. Döngüyü kapatın. Kararlar gelecekteki işi etkilemelidir. Ajan talimatlarına ve kod inceleme kontrol listelerine karar referansları ekleyin.

Amaç kusursuz dokümantasyon değildir. Değişikliklerin arkasındaki nedeni, bugün ve altı ay sonra, hem insanlar hem de yapay zeka için erişilebilir kılmaktır. Değişiklikler kurumsal hafızaya dönüştüğünde, ekipler onları yeniden icat etmek yerine yerleşik desenler üzerine inşa eder.

---

Madencilik iş akışı, orkestrasyon motorumuzun bir parçasıdır; özellikle orkestrasyon paketimizdeki bağlam motoru modülüdür.