الحقائق الأساسية (Ground Truths): ترسيخ وكلاء الذكاء الاصطناعي في الواقع

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

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

التخفيف المعتاد هو “امنح الوكيل سياقًا أكثر”. لكن السياق يمكن أن يكون متناقضًا. يبتعد التوثيق عن التنفيذ. التعليقات تكذب. حتى الكود يمكن أن يُضلِّل عندما يُقرَأ دون فهم القصد.

احتجنا إلى شيء أكثر صراحة. شيء لا يمكن تجاهله أو إساءة تفسيره. شيء يُرسِّخ الوكلاء في واقع قابل للتحقّق.

نسمّيها الحقائق الأساسية (Ground Truths).

ما هي الحقيقة الأساسية؟

الحقيقة الأساسية هي عبارة واقعية صريحة ومُراقَبة الإصدار يجب أن يحترمها الوكلاء. إنها ليست توثيقًا. إنها ليست تعليقًا. إنها كيان من الدرجة الأولى في النظام يحتوي على:

• معرِّف فريد (مثل GT-MAG-015 أو GT-MAG-036)
• حالة دورة حياة (current، أو tentative، أو deprecated)
• نطاق (على مستوى المنصة، أو خاص بالحزمة، أو محصور بمجال)
• دليل (مسارات ملفات، أو روابط، أو مراجع تُثبِت العبارة)
• توجيه للوكيل (تعليمات صريحة بما يجب فعله وما يجب تجنّبه)

إليك مثال من منصة ذكاء الكود Maguyva لدينا:

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

هذا ليس نثرًا. إنه عقد. عندما يصادف الوكيل هذه الحقيقة الأساسية، فإنه يعرف:

1. السلوك الافتراضي حتمي (نتائج فارغة، لا تخمينات غامضة)
2. توجد معاملات محدَّدة (find_similar، exact_match) بسلوكيات مُعرَّفة
3. الدليل موجود في ملفات محدَّدة يمكن التحقق منها
4. جرى التحقق من العبارة في تاريخ محدَّد

تشريح سجل الحقائق الأساسية

تعيش الحقائق الأساسية في سجلات YAML تحت ai_assets/reference/ground_truths.yaml. يمكن أن تمتلك كل حزمة أو مجال سجله الخاص. البنية هي:

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

يتضمن السجل بيانات وصفية عن المجموعة نفسها، وإعداد العرض لتوليد التوثيق، والعبارات نفسها. تتبع كل عبارة مخططًا صارمًا يُتحقَّق منه بنماذج Pydantic:

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

كيف يصل الوكلاء إلى الحقائق الأساسية

تُعرَض الحقائق الأساسية عبر قنوات متعددة:

1. التوثيق المُصيَّر

يحوِّل أمر orkestra sync سجلات YAML إلى markdown قابل للقراءة:

uv run orkestra sync

هذا يُولِّد ملفات GROUND_TRUTHS.md تُدرَج ضمن سياق الوكيل. يُجمِّع المخرَج المُصيَّر العبارات حسب الحالة والفئة:

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. بحث سطر الأوامر (CLI)

يستطيع الوكلاء ذوو وصول إلى الصدفة (shell) البحث عن الحقائق الأساسية برمجيًا:

uv run orkestra context ground-truths search "embedding"
uv run orkestra context ground-truths search --tag security
uv run orkestra context ground-truths list --status current

تُقيِّم دالة البحث التطابقات عبر حقول متعددة بأهمية نسبية موزونة:

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. تركيب السياق

عندما تُصيَّر الوكلاء من تعريفات YAML، يمكن لسياقها أن يشير إلى سجلات الحقائق الأساسية:

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

هذا يضمن تحميل الحقائق الأساسية ذات الصلة قبل أن يبدأ الوكيل العمل.

فئات الحقائق الأساسية

عند النظر عبر سجلاتنا، تتجمَّع الحقائق الأساسية في عدة أنماط:

مبادئ المنتج

قيود على ما هو عليه المنتج وما ليس عليه:

“Maguyva is read-only with respect to user repositories; the only non-rebuildable asset is the paid embeddings cache.” (GT-MAG-001)

حدود البنية المعمارية

أين تعيش المسؤوليات ولماذا:

“Pipeline and Maguyva boundaries are intentional: pipeline is reusable, Maguyva holds code-specific logic, and CQRS separates stage writes from server reads.” (GT-MAG-006)

قواعد مكافحة الهلوسة

تفويضات صريحة تُبقي عقود الأدوات حتمية بدلًا من مُستنتَجة:

“Fuzzy symbol matching is opt-in via find_similar=true. Default behavior returns empty results for non-existent symbols; exact_match=true enforces strict matching and disables all fuzzy fallbacks.” (GT-MAG-015)

بوابات الجودة

معايير يجب الحفاظ عليها:

“Changes to shared infrastructure (post_filters.py, relationship extractors, shared handlers) MUST be validated against ALL supported languages via full manifest generation before commit. A single-language validation is insufficient for shared code.” (GT-MAG-036)

أنماط الكود

متطلبات التنفيذ:

“Use asyncio.to_thread() for CPU-bound work in async contexts; the deprecated loop.run_in_executor() pattern should not be used in new code.” (GT-MAG-018)

دورة حياة الحقيقة الأساسية

الحقائق الأساسية ليست ثابتة. تتطور عبر دورة حياة مُعرَّفة:

مبدئية (Tentative)

حقيقة مقترَحة قيد التقييم. تُسجَّل العبارة لكنها قد تتغيّر:

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

حالية (Current)

حقيقة مُتحقَّق منها يجب أن يحترمها الوكلاء. جرى التحقق من الدليل:

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

مُتقادِمة (Deprecated)

حقيقة لم تعد تنطبق. تُبقى للمرجعية التاريخية مع إشارة إلى ما حلّ محلها:

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

لماذا لا يكفي التوثيق فقط؟

يخدم التوثيق غرضًا مختلفًا. إنه يشرح. إنه يعلِّم. يمكن أن يكون غامضًا، ويمكن أن يستخدم مؤهِّلات مثل “عمومًا” أو “عادةً”.

لا يمكن أن تكون الحقائق الأساسية غامضة. إنها تأكيدات. إما أن تنطبق أو لا تنطبق.

تأمَّل الفرق:

التوثيق: “تُعيد الواجهة البرمجية (API) عمومًا نتائج فارغة عندما لا يُعثَر على رمز، رغم أن المطابقة الغامضة قد تكون مُفعَّلة في بعض الإعدادات.”

الحقيقة الأساسية: “السلوك الافتراضي يُعيد نتائج فارغة للرموز غير الموجودة؛ exact_match=true يفرض المطابقة الصارمة ويُعطِّل كل أساليب الرجوع الغامضة.”

الأول مفيد للبشر الذين يتعلمون النظام. الثاني قابل للتنفيذ للوكلاء الذين يتخذون القرارات.

توجيه الوكيل: افعل وتجنّب

تتضمن بعض الحقائق الأساسية توجيهًا صريحًا للوكيل:

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

هذا يُزيل الغموض. الوكيل الذي يقرأ هذا يعرف ليس فقط ما هو صحيح، بل الإجراءات التي تستلزمها تلك الحقيقة.

التحقق والصيانة

تتطلب الحقائق الأساسية صيانة. نتتبَّع:

• last_verified: متى أكَّد أحدهم أن العبارة لا تزال صحيحة
• evidence: الملفات التي تُثبِت العبارة (يمكن التحقق من وجودها)
• source: من أين نشأت الحقيقة (فحص سطر الأوامر، مراجعة معمارية، تعلُّم بعد حادثة)

حقيقة أساسية بتواريخ تحقق قديمة أو روابط دليل معطَّلة هي إشارة للتحقيق. إما أن الحقيقة لا تزال صالحة وتحتاج إعادة تحقق، أو أن الواقع تغيَّر وتحتاج الحقيقة إلى تحديث.

أمثلة حقيقية من الإنتاج

حدود الأمان

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

تمنع هذه الحقيقة الأساسية فئة من “تحسينات الأمان” المضلَّلة التي كانت ستُعطِّل المنتج.

دقة وقت الاستخلاص

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

جاء هذا من تجربة مؤلمة. كان الوكلاء يرقِّعون حزم اللغات الفاشلة بإضافة مرشِّحات خاصة بالمُتحقِّق فقط تجعل تسخيرة الاختبار تبدو أكثر خضرة، بينما لا يزال مُستخلِص Maguyva الحي يُصدر الحواف الخاطئة. تفرض القاعدة إعادة الإصلاحات إلى المسار الحقيقي: إعداد YAML، أو الاستعلامات، أو المعالِجات.

التصفية متعددة الطبقات

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

هذا يمنع الوكلاء من إضافة مرشِّحات في المكان الخطأ، وهو خطأ شائع تسبَّب في انحدارات دقة.

التكامل مع نظام التنسيق

الحقائق الأساسية طبقة واحدة من نظام سياق أوسع:

1. القرارات المعمارية (ADRs) - تُسجِّل لماذا اخترنا النهج A بدلًا من B
2. الحقائق الأساسية - تنص على ما هو صحيح قطعيًا الآن
3. أنماط المجال - تصف كيفية فعل الأشياء بشكل صحيح
4. الأنماط المضادة - تصف ما يجب تجنّبه ولماذا

الوكيل الذي يعمل في النظام لديه وصول إلى الأربعة جميعًا. توفِّر الحقائق الأساسية المرساة الواقعية، بينما تشرح القرارات التاريخ، وتوجِّه الأنماط التنفيذ، وتحذِّر الأنماط المضادة من المزالق.

قياس الأثر

منذ تقديم الحقائق الأساسية، لاحظنا:

• دورات أقل من “أصلِح الإصلاح المُهلوَس”
• اتخاذ قرارات أكثر ثقة من الوكلاء عندما تكون الوقائع واضحة
• مراجعات طلبات سحب (PR) أفضل لأن التوقعات صريحة
• وقت تهيئة أقصر للوكلاء الجدد (والبشر أيضًا)

يُؤتي الاستثمار في صيانة الحقائق الأساسية ثماره بتقليل التصحيح وتوضيح حدود النظام.

البدء

لإضافة حقيقة أساسية إلى نظامك:

1. أنشئ ground_truths.yaml في دليل ai_assets/reference/ الخاص بحزمتك
2. عرِّف البيانات الوصفية وإعداد العرض
3. أضِف العبارات وفق المخطط
4. شغِّل uv run orkestra sync لتوليد التوثيق
5. أدرِج السجل ضمن تركيب سياق الوكيل

ابدأ بالوقائع التي تسبِّب أكبر قدر من الالتباس، أو القيود التي تُنتهَك أكثر من غيرها. تلك هي حقائقك الأساسية الأعلى قيمة.

الخاتمة

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

الحقائق الأساسية ليست حلًا كاملًا. تتطلب صيانة. يمكن أن تصبح قديمة. تضيف عبئًا إضافيًا إلى عملية التطوير.

لكنها توفِّر شيئًا قيّمًا: مفردات مشتركة من الوقائع يمكن للبشر والوكلاء أن يثقوا بها. في عالم يشارك فيه الوكلاء بشكل متزايد في تطوير البرمجيات، يصبح ذلك الأساس المشترك ضروريًا.

البديل هو دورات لا نهاية لها من الوكلاء الذين يرتكبون أخطاء بثقة والبشر الذين يصحِّحونها. تكسر الحقائق الأساسية تلك الدورة بجعل التصحيحات صريحة ودائمة.

وكلاؤك يستحقون معرفة ما هو صحيح. أخبِرهم.