Εξόρυξη του Βρόχου: Πώς οι Αλλαγές Γίνονται Θεσμική Μνήμη

Οι αριθμοί σε αυτή την ανάρτηση αντικατοπτρίζουν το σύστημα κατά τη δημοσίευση (Φεβρουάριος 2026). Δείτε τη σελίδα ομάδας μας για τα τρέχοντα στοιχεία.

Κάθε ομάδα μηχανικών αντιμετωπίζει την ίδια πρόκληση: οι αλλαγές συμβαίνουν συνεχώς, όμως το γιατί πίσω από αυτές τις αλλαγές εξαφανίζεται. Έξι μήνες αργότερα, κάποιος ρωτά «γιατί υιοθετήσαμε το DuckDB για τα στάδια του αγωγού;» και η απάντηση ζει μόνο στο μυαλό όποιου πήρε εκείνη την απόφαση — αν εξακολουθεί να είναι εκεί.

Χτίσαμε μια ροή εργασίας εξόρυξης που κλείνει αυτόν τον βρόχο. Οι αλλαγές ρέουν μέσα από υποβολές git, επεξεργάζονται από τον αγωγό εξόρυξής μας, γίνονται δομημένες καταχωρίσεις ιστορικού αλλαγών και αρχεία αρχιτεκτονικών αποφάσεων, και έπειτα τροφοδοτούν πίσω τους πράκτορές μας AI μέσω ερωτημάτων CLI. Το αποτέλεσμα: θεσμική μνήμη στην οποία μπορούν να έχουν πρόσβαση τόσο άνθρωποι όσο και AI.

Το Πρόβλημα: Οι Αποφάσεις Εξατμίζονται

Σκεφτείτε ένα τυπικό σενάριο. Ένας προγραμματιστής κάνει μια υποβολή (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)
• Εμβέλεια (ποιο πακέτο ή περιοχή)
• Δείκτες ασύμβατων αλλαγών
• Αρχεία που επηρεάστηκαν και μετρικές πολυπλοκότητας

Βήμα 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 υποβολές επεξεργάστηκαν. 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».

Για αρχιτεκτονικές αποφάσεις:

Πρώτα, πάρτε ένα πραγματικό ID απόφασης:

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

Έπειτα ταξινομήστε με το ID απόφασης:

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 ανά πακέτο από το καθολικό. Τα ιστορικά αλλαγών είναι παράγωγα τεχνουργήματα — διαγράψτε τα και αναδημιουργούνται τέλεια από το πηγαίο καθολικό.

Η Δομή του Αρχείου Απόφασης

Οι εξαγόμενες αποφάσεις γίνονται αρχεία 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

Κάθε απόφαση συνδέεται πίσω με τις πηγαίες της υποβολές. Κάθε απόφαση προσδιορίζει ποια αρχεία επηρεάζει. Οι σχέσεις ανάμεσα σε αποφάσεις είναι ρητές.

Ενσωμάτωση CLI: Ερωτήματα στη Θεσμική Μνήμη

Εδώ είναι όπου κλείνει ο βρόχος. Οι πράκτορες μπορούν να θέτουν ερωτήματα σε αποφάσεις μέσω του CLI:

# 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 (πλαίσιο)
• Πώς να το χρησιμοποιήσει σωστά (agent_guidance)
• Ποια αρχεία να κοιτάξει (files)
• Ποιες σχετικές αποφάσεις υπάρχουν (related)

Ο πράκτορας δεν ανακαλύπτει ξανά τον τροχό. Χτίζει πάνω σε καθιερωμένα μοτίβα.

Το Τεστ των Τριών Ερωτημάτων

Δεν αξίζει κάθε υποβολή ένα αρχείο απόφασης. Χρησιμοποιούμε το Τεστ των Τριών Ερωτημάτων για να φιλτράρουμε:

1. Ήταν δύσκολο να ληφθεί; Απαίτησε σημαντική ανάλυση, αξιολόγηση ανταλλαγμάτων ή συζήτηση;
2. Είναι δαπανηρό να αλλάξει; Θα απαιτούσε η αντιστροφή αυτής της απόφασης σημαντική επανεργασία;
3. Έχει επίδραση σε όλο το σύστημα; Επηρεάζει πολλαπλά πακέτα ή θεσπίζει μοτίβα που θα ακολουθήσουν άλλοι;

Αν μια υποβολή απαντά «ναι» σε τουλάχιστον ένα από αυτά τα ερωτήματα, είναι υποψήφια για εξαγωγή απόφασης. Ο τυπικός μας ρυθμός: 1-4 αποφάσεις ανά 100 υποβολές (περίπου 1-4%).

Για καταχωρίσεις ιστορικού αλλαγών, ο πήχης είναι χαμηλότερος: κάθε αλλαγή ορατή στον χρήστη (χαρακτηριστικά, διορθώσεις, βελτιώσεις) καταγράφεται. Εσωτερικές δουλειές συντήρησης, ενημερώσεις τεκμηρίωσης και αναδιαμορφώσεις συνήθως παραλείπονται. Ο τυπικός μας ρυθμός: 30-50 καταχωρίσεις ιστορικού αλλαγών ανά 100 υποβολές.

Αποθήκευση Δεδομένων: Καθολικά Μόνο-για-Προσθήκη

Το σύστημα εξόρυξης χρησιμοποιεί καθολικά 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
• Συμμόρφωση μορφής ID απόφασης
• Καμία διπλή καταχώριση για το ίδιο SHA
• Ότι οι αναφερόμενες αποφάσεις όντως υπάρχουν

Μετά την ταξινόμηση, επικυρώνουμε ξανά πριν υποβάλουμε τις αλλαγές.

Γιατί Έχει Σημασία

Ο βρόχος ανάδρασης που χτίσαμε λύνει αρκετά προβλήματα:

Για νέα μέλη της ομάδας: Αντί να ρωτούν «γιατί κάναμε το X;», μπορούν να αναζητήσουν στο μητρώο αποφάσεων. Το πλαίσιο διατηρείται.

Για πράκτορες AI: Δεν λειτουργούν σε κενό. Μπορούν να θέτουν ερωτήματα στη θεσμική γνώση πριν κάνουν συστάσεις. Όταν τους ζητηθεί να προσθέσουν ένα νέο στάδιο αγωγού, μπορούν να ανακαλύψουν το μοτίβο DuckDB και να το ακολουθήσουν.

Για αρχιτεκτονική συνέπεια: Οι αποφάσεις είναι ρητές και αναζητήσιμες. Όταν κάποιος προτείνει μια προσέγγιση που έρχεται σε αντίθεση με μια υπάρχουσα απόφαση, το σύστημα μπορεί να αναδείξει τη σύγκρουση.

Για δημιουργία ιστορικού αλλαγών: Οι σημειώσεις έκδοσης δεν είναι μια πανικόβλητη εργασία της τελευταίας στιγμής. Είναι παραπροϊόν συνεχούς ταξινόμησης κατά την ανάπτυξη.

Για ένταξη νέων μελών: Οι νέοι πράκτορες κληρονομούν το πλήρες πλαίσιο της βάσης κώδικα. Δεν βλέπουν απλώς τον κώδικα — βλέπουν τις αποφάσεις που τον διαμόρφωσαν.

Τρέχουσα Κατάσταση

Έως σήμερα:

• 15.637 υποβολές επεξεργάστηκαν μέσω του αγωγού
• 476 αρχιτεκτονικές αποφάσεις εξήχθησαν και τεκμηριώθηκαν
• 6.799 καταχωρίσεις ιστορικού αλλαγών καταγράφηκαν
• 100% κάλυψη και στους δύο τομείς

Κάθε υποβολή από τότε που ξεκινήσαμε έχει ταξινομηθεί. Η θεσμική μνήμη είναι πλήρης και αναζητήσιμη.

Ξεκινώντας

Αν θέλετε να υλοποιήσετε κάτι παρόμοιο:

1. Ξεκινήστε με συμβατικές υποβολές. Ο αγωγός εξόρυξης λειτουργεί καλύτερα όταν οι υποβολές έχουν δομημένα προθέματα (feat:, fix:, chore:).

2. Ορίστε τους τομείς σας. Χρησιμοποιούμε τομείς όπως pipeline, agent-design, observability, data-modeling. Αυτοί οργανώνουν τις αποφάσεις κατά περιοχή.

3. Χτίστε τη συνήθεια ταξινόμησης. Η εξόρυξη λειτουργεί όταν οι ομάδες ταξινομούν τακτικά υποβολές. Η μαζική επεξεργασία με βοήθεια LLM βοηθά στην κλιμάκωση.

4. Κάντε τις αποφάσεις αναζητήσιμες. Η αξία πολλαπλασιάζεται όταν οι πράκτορες μπορούν να αναζητήσουν αποφάσεις μέσω CLI. Δομήστε την έξοδό σας για κατανάλωση από μηχανή.

5. Κλείστε τον βρόχο. Οι αποφάσεις πρέπει να επηρεάζουν τη μελλοντική εργασία. Συμπεριλάβετε αναφορές αποφάσεων σε οδηγίες πρακτόρων και λίστες ελέγχου επισκόπησης κώδικα.

Ο στόχος δεν είναι τέλεια τεκμηρίωση. Είναι να κάνει το γιατί πίσω από τις αλλαγές προσβάσιμο τόσο σε ανθρώπους όσο και σε AI, σήμερα και έξι μήνες από τώρα. Όταν οι αλλαγές γίνονται θεσμική μνήμη, οι ομάδες χτίζουν πάνω σε καθιερωμένα μοτίβα αντί να τα ανακαλύπτουν ξανά.

---

Η ροή εργασίας εξόρυξης είναι μέρος της μηχανής ενορχήστρωσής μας, συγκεκριμένα του αρθρώματος μηχανής πλαισίου στο πακέτο ενορχήστρωσής μας.