# ‏GEMINI.md يخبر Gemini بقواعدك. لا بما يحتويه كودك.

Canonical source: https://maguyva.ai/ar/for-gemini

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).

‏GEMINI.md يضبط سياق العمل. MCP يتيح لـGemini الوصول إلى الأدوات. Maguyva هو خادم MCP الذي يمنح Gemini خريطة قابلة للاستعلام عن مستودعك، لذا لا يكون التعديل الأول تخمينًا لبنية الملفات.

> ‏GEMINI.md هو السياق. MCP هو القناة. Maguyva هو الخريطة.

## البنية الطبقية

أربع أفكار. لكل واحدة مهمتها.

### GEMINI.md

كيف ينبغي أن يتصرَّف Gemini في هذا المستودع.

### MCP

كيف يصل Gemini إلى الأدوات والسياق الخارجيَّين.

### Maguyva

خادم MCP الذي يُرجع حقائق مؤسَّسة عن المستودع.

### مساحات عمل، لا مقاعد

الوكلاء لا يدفعون مقابل مقاعد. [اطّلع على الأسعار](https://maguyva.ai/ar/pricing)

## ‏GEMINI.md سياق عمل. استخدمه.

التعليمات الدائمة مكانها `GEMINI.md`. إنه المكان الصحيح لـ:

- أوامر البناء والاختبار والـlint التي ينبغي أن يشغِّلها Gemini.
- ضوابط “افعل X دائمًا / لا تفعل Y أبدًا” المحدَّدة النطاق لمجلد معيَّن.
- أعراف التسمية وتفضيلات إعادة الهيكلة.
- إشارات إلى سجلّات القرارات المرجعية وملاحظات المعمارية.

اجعله موجزًا. حدِّد نطاقه. أودعه في Git.

لكن `GEMINI.md` لم يُصمَّم قط ليكون فهرسًا قابلًا للاستعلام عن كل رمز وملف وموقع استدعاء في مستودعك.

## أين لا يعود GEMINI.md وحده كافيًا

أربعة أنماط فشل، واحد لكل بطاقة.

### ‏// السياق ليس فهرسًا

إخبار Gemini *كيف يعمل* لا يخبره *بما هو موجود*. التعديل الأول على حزمة غير مألوفة هو تخمين لمسارات الملفات وأسماء الدوال. لا يمكن لـGEMINI.md سرد كل رمز، ولن ترغب في ذلك أصلًا.

### ‏// الوثيقة تنحرف عن الكود

قسم في GEMINI.md يصف بنية قائمة الانتظار لديك يكون صحيحًا إلى أن يُدخِل أحدهم مستهلِكًا جديدًا. الكود الآن هو مصدر الحقيقة، والوثيقة قديمة بثقة زائفة. يقرأ Gemini الوثيقة الخاطئة.

### ‏// إعادة التسمية مشكلة رسم بياني

«ما الذي يشير إلى هذه الفئة؟» سؤال لا يمكن الإجابة عنه من ملف markdown. إما أن يبحث Gemini بـgrep ويدعو أن ينجح عبر المستودع الموحّد، أو يطلب منك لصق مواقع الاستدعاء في المحادثة.

### ‏// نوافذ السياق ليست مجانية

نافذة سياق كبيرة ليست كفهرس قابل للاستعلام. تحميل GEMINI.md إلى أن “يعرف Gemini ما يكفي” ما زال يستبدل ميزانية الاستدلال بحجم سياق جامد.

## كيف تتلاءم الطبقات الثلاث معًا

مستخدمو Gemini يفكِّرون بهذا الشكل بالفعل. ينبغي أن توضِّح الصفحة ذلك.

- **GEMINI.md**: السياق (كيف يتصرَّف Gemini)
- **MCP**: القناة (كيف يصل)
- **Maguyva**: حقائق قاعدة الكود (ما يراه)

- **GEMINI.md**: كيف يتصرَّف Gemini في هذا المستودع.
- **MCP**: كيف يصل Gemini إلى الأدوات والسياق. [(المواصفة)](https://modelcontextprotocol.io/docs/getting-started/intro)
- **Maguyva**: ما يراه Gemini عندما يطرح سؤالًا على قاعدة الكود. بحث دلالي وAST ورسم بياني ونصي، تُعاد نتائجه مع مسارات الملفات وأرقام الأسطر.

> ‏GEMINI.md يخبر Gemini *كيف يعمل*.
> Maguyva يمنح Gemini *ما يعمل انطلاقًا منه*.

## ثلاثة تدفقات عمل

خاص بـGemini. مؤسَّس على الرسم البياني الفعلي للاستدعاءات، لا على grep الخاصة بـGemini.

### 01. أعد تسمية فئة مشتركة، وابحث عن كل العناصر المعتمدة عليها أولًا

```text
gemini> أعد تسمية PaymentClient → BillingClient

graph::callers(PaymentClient)            12 مرجعًا عبر 7 حزم
graph::importers(src/payments/client.ts)  9 جهات استيراد
graph::extends(PaymentClient)             2 من الأصناف الفرعية (RetryClient, MockClient)

→ يقترح Gemini عملية ترحيل من 21 تعديلًا مع قائمة الملفات مضمَّنة.
[exit 0]
```

يطلب Gemini من Maguyva العناصر المعتمدة *قبل* أن يبدأ التحرير. تعود قائمة الترحيل مؤسَّسة على الرسم البياني الفعلي، لا على تذكُّر Gemini.

### 02. إيجاد التنفيذ الحقيقي، لا البديل الوهمي

```text
gemini> كيف تتعامل normalizePhoneNumber مع E.164؟

semantic::query("normalize phone E.164")
  src/util/phone.ts:88   normalizePhoneNumber()   ← التنفيذ الحقيقي
  test/util/phone.spec.ts:14  jest.mock(...)      ← بديل وهمي
[exit 0]
```

الأسماء تكذب. المحاكيات تحجب الكود الحقيقي. يُرتِّب Maguyva التنفيذ الحقيقي فوق محاكي الاختبار.

### 03. تحقّق من نطاق التأثير قبل إعادة الهيكلة

```text
gemini> ما الذي يستدعي QueueDispatcher.publish؟

graph::callers(QueueDispatcher.publish)
  3 في src/billing/*    1 في src/audit/*    1 في src/notifications/*
[exit 0]
```

تظهر مواقع الاستدعاء العابرة للحزم ضمن السياق. الفرق مؤسَّس على مستوردين حقيقيين، لا على grep الخاصة بـGemini.

## الإعداد في Gemini CLI

ثلاث خطوات. خطة Free: 3 مستودعات, حتى 50 ألف سطر مُفهرَس من المستودع، بلا بطاقة.

### 01. افهرس مستودعًا على maguyva.ai

اختر واحدًا تعرفه جيدًا، لتتمكَّن من التحقق من الإجابات.

### 02. أضف Maguyva كخادم MCP في إعدادات Gemini CLI

`~/.gemini/settings.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}
```

### 03. اطرح سؤالًا واحدًا تعرف إجابته مسبقًا

لا تبدأ بشركتك بأكملها. ابدأ بمستودع واحد وسؤال واحد يمكن التحقق منه.

## افهرس مستودعًا واحدًا تعرفه جيدًا.

اتصل بـGemini عبر MCP. اطرح سؤالًا واحدًا يمكنك التحقق من إجابته.