# ‏AGENTS.md يخبر Codex كيف يعمل. لا بما يحتويه المستودع.

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

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

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

> ‏AGENTS.md هو الاتفاق. MCP هو القناة. Maguyva هو الخريطة.

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

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

### AGENTS.md

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

### MCP

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

### Maguyva

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

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

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

## ‏AGENTS.md اتفاق عمل. استخدمه.

التعليمات الدائمة مكانها [`AGENTS.md`](https://developers.openai.com/codex/guides/agents-md). إنه المكان الصحيح لـ:

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

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

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

## أين يصبح AGENTS.md وحده جامدًا عند التوسّع

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

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

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

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

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

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

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

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

حشو AGENTS.md إلى أن “يعرف Codex ما يكفي” يستهلك رموزًا (tokens) كان ينبغي أن تُنفَق على الاستدلال. بعد بضع كيلوبايتات، تستبدل جودة الإجابة بحجم سياق جامد.

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

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

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

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

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

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

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

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

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

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

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

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

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

```text
codex> كيف تتعامل 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
codex> ما الذي يستدعي QueueDispatcher.publish؟

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

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

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

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

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

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

### 02. أضف Maguyva كخادم MCP في إعداد Codex الخاص بك

`~/.codex/config.toml`

```text
export MAGUYVA_API_KEY=mgv_xxxx
codex mcp add maguyva --url https://maguyva.tools/mcp --bearer-token-env-var MAGUYVA_API_KEY
```

```toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"
```

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

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

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

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