تعدين الحلقة: كيف تتحول التغييرات إلى ذاكرة مؤسسية

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (فبراير 2026). راجع صفحة فريقنا للأرقام الحالية.

يواجه كل فريق هندسي التحدي نفسه: تحدث التغييرات باستمرار، لكن السبب وراء تلك التغييرات يختفي. بعد ستة أشهر، يسأل أحدهم “لماذا اعتمدنا DuckDB لمراحل خط الأنابيب (pipeline)؟” والجواب يعيش فقط في رأس من اتخذ ذلك القرار — إن كان لا يزال موجودًا.

بنينا سير عمل تعدين (mining) يُغلِق هذه الحلقة. تتدفق التغييرات عبر التزامات (commits) Git، وتُعالَج بخط أنابيب التعدين لدينا، وتصبح مدخلات سجل تغييرات منظَّمة وسجلات قرارات معمارية، ثم تُغذّي وكلاء الذكاء الاصطناعي لدينا مرة أخرى عبر استعلامات سطر الأوامر (CLI). النتيجة: ذاكرة مؤسسية يستطيع كل من البشر والذكاء الاصطناعي الوصول إليها.

المشكلة: القرارات تتبخَّر

تأمَّل سيناريو نموذجيًا. يُنشئ مطوِّر التزامًا (commit):

feat(canonical): add DuckDB runtime for pipeline stages

يمثِّل هذا الالتزام خيارًا معماريًا مهمًا. قيَّم الفريق الخيارات، ونظر في المقايضات، واستقر على DuckDB لأسباب محدَّدة. لكن كل ذلك السياق يعيش في:

• خيط Slack (على الأرجح مُحذوف)
• ذاكرة أحدهم (تتلاشى بالتأكيد)
• تعليق في الكود (ربما، إن كنت محظوظًا)

بعد ثلاثة أشهر، يسأل عضو فريق جديد: “هل ينبغي أن أستخدم DuckDB أم SQLite لهذه المرحلة الجديدة؟” بدون ذاكرة مؤسسية، إما أن يعيد اختراع العجلة أو يتخذ خيارات غير متسقة.

الحلقة: من الالتزامات إلى السياق

يُحوِّل سير عمل التعدين لدينا تاريخ git إلى معرفة قابلة للاستعلام:

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

البصيرة الأساسية: يتدفق كل من سجلات التغييرات والقرارات المعمارية من تاريخ git نفسه، وتُعالَج عبر خط أنابيب موحَّد. هذا يضمن ألا يفلت شيء من العناية.

كيف يعمل التعدين

الخطوة 1: مزامنة الفهرس

uv run orkestra mine sync

يفحص هذا الأمر تاريخ git ويبني فهرسًا لكل الالتزامات. يستخلص إشارات منظَّمة من كل التزام:

• نوع الالتزام التقليدي (feat، fix، chore، docs)
• النطاق (أي حزمة أو منطقة)
• علامات التغيير الجذري (breaking change)
• الملفات المُمَسَّة ومقاييس التعقيد

الخطوة 2: فحص حالة التغطية

uv run orkestra mine 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 التزامًا (commits) مُعالَجًا. أصبح 476 منها قرارات معمارية. أصبح 6,799 منها مدخلات سجل تغييرات. كل التزام مُصنَّف.

الخطوة 3: الحصول على مرشَّحين للمراجعة

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

هذا يُظهِر الالتزامات التي لم تُعالَج بعد، مع سياق كامل للتصنيف:

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

تساعد الإشارات في توجيه التصنيف: يقترح is_releasable_type: true أن هذا ينبغي أن يظهر في سجل التغييرات. عدد الإدراجات الكبير وملفات البنية التحتية تشير إلى أنه قد يكون قرارًا معماريًا أيضًا.

الخطوة 4: تصنيف الالتزامات

يتفرَّع مساران هنا: مدخلات سجل التغييرات والقرارات المعمارية.

لمدخلات سجل التغييرات:

uv run orkestra mine classify abc123 --changelog added

هذا يُسجِّل أن الالتزام abc123 ينبغي أن يظهر في سجل التغييرات تحت فئة “مُضاف” (Added).

للقرارات المعمارية:

أولًا، احصل على معرِّف قرار حقيقي:

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

ثم صنِّف باستخدام معرِّف القرار:

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

هذا يربط الالتزام بسجل قرار سيُنشَأ أو يُحدَّث.

للمعالجة بالدفعات (وهو ما نفعله فعليًا):

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

يدعم تنسيق JSONL كلا المجالين في تمريرة واحدة:

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

الخطوة 5: توليد المخرجات

uv run orkestra changelog render --package <pkg>

هذا يُولِّد ملفات CHANGELOG.md لكل حزمة من السجل (ledger). سجلات التغييرات نواتج مُشتقَّة — احذفها وستتولَّد من جديد بشكل مثالي من السجل المصدر.

بنية سجل القرار

تصبح القرارات المُستخلَصة ملفات 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

يرتبط كل قرار مرة أخرى بالتزاماته المصدر. يحدِّد كل قرار الملفات التي يؤثر فيها. العلاقات بين القرارات صريحة.

تكامل سطر الأوامر: الاستعلام عن الذاكرة المؤسسية

هنا تُغلَق الحلقة. يستطيع الوكلاء الاستعلام عن القرارات عبر سطر الأوامر:

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

يُعيد قرارات حول منطق إعادة المحاولة، ومعالجة الأخطاء، وأنماط الاستعادة.

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

يُعيد سجل القرار الكامل بسياقه، ومبرِّراته، وأثره.

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

يُظهِر الخيارات المعمارية التي اتُّخذت مؤخرًا.

كيف يستخدم الوكلاء هذا

تتضمن التعليمات الأساسية لمنسِّقنا:

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

عندما يُطلَب من وكيل تنفيذ شيء متعلق بـDuckDB، يمكنه أولًا التحقق من:

uv run orkestra decisions search --query "DuckDB"

واكتشاف DEC-PL-142، والتعلُّم:

• لماذا اخترنا DuckDB (context)
• كيفية استخدامه بشكل صحيح (agent_guidance)
• أي الملفات يجب النظر إليها (files)
• أي القرارات ذات الصلة موجودة (related)

لا يعيد الوكيل اختراع العجلة. إنه يبني على أنماط راسخة.

اختبار الأسئلة الثلاثة

لا يستحق كل التزام سجل قرار. نستخدم اختبار الأسئلة الثلاثة للفرز:

1. هل كان اتخاذه صعبًا؟ هل تطلَّب تحليلًا كبيرًا، أو تقييم مقايضات، أو نقاشًا؟
2. هل تغييره مكلف؟ هل سيتطلب عكس هذا القرار إعادة عمل كبيرة؟
3. هل له أثر على مستوى النظام كله؟ هل يؤثر في حزم متعددة أو يُرسي أنماطًا سيتبعها آخرون؟

إذا أجاب التزام بـ“نعم” على واحد على الأقل من هذه الأسئلة، فهو مرشَّح لاستخلاص قرار. معدلنا المعتاد: 1-4 قرارات لكل 100 التزام (نحو 1-4%).

بالنسبة إلى مدخلات سجل التغييرات، العتبة أقل: يُسجَّل أي تغيير يواجه المستخدم (ميزات، إصلاحات، تحسينات). عادةً ما تُتخطَّى المهام الداخلية، وتحديثات التوثيق، وإعادة الهيكلة. معدلنا المعتاد: 30-50 مدخلة سجل تغييرات لكل 100 التزام.

تخزين البيانات: سجلات إلحاق فقط (Append-Only)

يستخدم نظام التعدين سجلات JSONL بإلحاق فقط لتشغيل خالٍ من التعارض بين وكلاء متعددين:

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

تنسيق JSONL مع merge=union في .gitattributes يعني أن وكلاء متعددين يستطيعون تصنيف الالتزامات في آنٍ واحد دون تعارضات دمج. كل سطر مستقل.

بوابات التحقق

قبل أي جلسة تعدين، نُشغِّل التحقق:

uv run orkestra mine validate --quick

يفحص هذا:

• صحة تنسيق SHA
• امتثال تنسيق معرِّف القرار
• عدم وجود مدخلات مكرَّرة لنفس SHA
• وجود القرارات المُشار إليها فعليًا

بعد التصنيف، نتحقق مجددًا قبل الالتزام بالتغييرات.

لماذا يهم هذا

تحلّ حلقة التغذية الراجعة التي بنيناها عدة مشكلات:

لأعضاء الفريق الجدد: بدلًا من سؤال “لماذا فعلنا X؟”، يستطيعون البحث في سجل القرارات. السياق محفوظ.

لوكلاء الذكاء الاصطناعي: لا يعملون في فراغ. يستطيعون الاستعلام عن المعرفة المؤسسية قبل تقديم التوصيات. عندما يُطلَب منهم إضافة مرحلة خط أنابيب جديدة، يستطيعون اكتشاف نمط DuckDB واتّباعه.

للاتساق المعماري: القرارات صريحة وقابلة للبحث. عندما يقترح أحدهم نهجًا يناقض قرارًا قائمًا، يستطيع النظام إظهار التعارض.

لتوليد سجل التغييرات: ملاحظات الإصدار ليست هرولة في اللحظة الأخيرة. إنها نتاج ثانوي لتصنيف مستمر أثناء التطوير.

للتهيئة: يرث الوكلاء الجدد السياق الكامل لقاعدة الكود. لا يرون الكود فقط — بل يرون القرارات التي شكَّلته.

الحالة الراهنة

اعتبارًا من اليوم:

• 15,637 التزامًا عولِجت عبر خط الأنابيب
• 476 قرارًا معماريًا استُخلِصت ووُثِّقت
• 6,799 مدخلة سجل تغييرات سُجِّلت
• تغطية 100% عبر كلا المجالين

كل التزام منذ أن بدأنا صُنِّف. الذاكرة المؤسسية كاملة وقابلة للاستعلام.

البدء

إذا أردت تنفيذ شيء مماثل:

1. ابدأ بالتزامات تقليدية (conventional commits). يعمل خط أنابيب التعدين بشكل أفضل عندما تحمل الالتزامات بادئات منظَّمة (feat:، fix:، chore:).

2. حدِّد مجالاتك. نستخدم مجالات مثل pipeline، agent-design، observability، data-modeling. تنظِّم هذه المجالات القرارات حسب المنطقة.

3. ابنِ عادة التصنيف. يعمل التعدين عندما تصنِّف الفرق الالتزامات بانتظام. تساعد المعالجة بالدفعات بمساعدة LLM على التوسّع.

4. اجعل القرارات قابلة للاستعلام. تتضاعف القيمة عندما يستطيع الوكلاء البحث في القرارات عبر سطر الأوامر. صمِّم مخرجك ليكون قابلًا للاستهلاك آليًا.

5. أغلِق الحلقة. ينبغي أن تؤثر القرارات في العمل المستقبلي. أدرِج مراجع القرارات في تعليمات الوكيل وقوائم مراجعة الكود.

الهدف ليس توثيقًا مثاليًا. إنه جعل السبب وراء التغييرات متاحًا لكل من البشر والذكاء الاصطناعي، اليوم وبعد ستة أشهر من الآن. عندما تصبح التغييرات ذاكرة مؤسسية، تبني الفرق على أنماط راسخة بدلًا من إعادة اختراعها.

---

سير عمل التعدين جزء من محرك التنسيق لدينا، وتحديدًا وحدة محرك السياق في حزمة التنسيق لدينا.