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

Canonical source: https://maguyva.ai/ar/blog/ground-truths-anchoring-ai-to-reality

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-13 · Author: Maguyva Team

> يهلوس وكلاء الذكاء الاصطناعي بثقة. الحقائق الأساسية (Ground Truths) هي وقائع خاضعة لإدارة الإصدارات ومحدَّدة النطاق تُرسِّخ سلوك الوكيل في الواقع. إليك كيف بنيناها وكيف نفرضها.

> *تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع [صفحة فريقنا](/ar/team) للأرقام الحالية.*

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

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

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

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

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

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

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

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

```yaml
- 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`. يمكن أن تمتلك كل حزمة أو مجال سجله الخاص. البنية هي:

```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:

```python
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 قابل للقراءة:

```bash
uv run orkestra sync
```

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

```markdown
## 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) البحث عن الحقائق الأساسية برمجيًا:

```bash
uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current
```

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

```python
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، يمكن لسياقهم أن يشير إلى سجلات الحقائق الأساسية:

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

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

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

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

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

> «يعمل Maguyva في وضع القراءة فقط بالنسبة إلى مستودعات المستخدمين؛ والأصل الوحيد الذي لا يمكن إعادة بنائه هو ذاكرة التخزين المؤقت المدفوعة للتضمينات.» (GT-MAG-001)

### حدود البنية المعمارية
أين تعيش المسؤوليات ولماذا:

> «الحدود بين خط المعالجة وMaguyva مقصودة: خط المعالجة قابل لإعادة الاستخدام، ويحتضن Maguyva المنطق الخاص بالكود، ويفصل نمط CQRS عمليات الكتابة في المراحل عن عمليات القراءة في الخادم.» (GT-MAG-006)

### قواعد مكافحة الهلوسة
توجيهات إلزامية صريحة تُبقي عقود الأدوات حتمية بدلًا من مُستنتَجة:

> «المطابقة التقريبية للرموز اختيارية وتُفعَّل عبر `find_similar=true`. يُعيد السلوك الافتراضي نتائج فارغة للرموز غير الموجودة؛ ويفرض `exact_match=true` المطابقة الصارمة ويُعطِّل كل بدائل المطابقة التقريبية.» (GT-MAG-015)

### بوابات الجودة
معايير يجب الحفاظ عليها:

> «التغييرات على البنية التحتية المشتركة (post_filters.py، ومستخلِصات العلاقات، والمعالِجات المشتركة) **يجب** التحقق منها مقابل **جميع** اللغات المدعومة عبر توليد البيان (manifest) الكامل قبل الإيداع. التحقق بلغة واحدة لا يكفي للكود المشترك.» (GT-MAG-036)

### أنماط الكود
متطلبات التنفيذ:

> «استخدم `asyncio.to_thread()` للعمل المرتبط بالمعالج (CPU-bound) في السياقات غير المتزامنة؛ ولا ينبغي استخدام نمط `loop.run_in_executor()` المُتقادِم في الكود الجديد.» (GT-MAG-018)

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

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

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

```yaml
- 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)
حقيقة مُتحقَّق منها يجب أن يحترمها الوكلاء. جرى التحقق من الدليل:

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

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

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

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

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

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

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

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

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

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

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

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

```yaml
- 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**: من أين نشأت الحقيقة (فحص سطر الأوامر، مراجعة معمارية، تعلُّم بعد حادثة)

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

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

### حدود الأمان
```yaml
- 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.
```

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

### دقة وقت الاستخلاص
```yaml
- 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، أو الاستعلامات، أو المعالِجات.

### التصفية متعددة الطبقات
```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. أدرِج السجل ضمن تركيب سياق الوكيل

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

## الخاتمة

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

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

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

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

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