تخطَّ إلى المحتوى

لمستخدمي Codex CLI

‏AGENTS.md يخبر Codex كيف يعمل.
لا بما هو موجود.

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

ابدأ مجانًااقرأ دليل إعداد Codex

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

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

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

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

‏// الاتفاق

AGENTS.md

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

‏// النقل

MCP

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

‏// قاعدة الكود

Maguyva

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

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

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

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

اجعله موجزًا. حدِّد نطاقه. التزم به.

لكن 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 إلى الأدوات والسياق. (المواصفة)
  • Maguyva ما يراه Codex عندما يطرح سؤالًا على قاعدة الكود. بحث دلالي وAST ورسم بياني ونصي، تُعاد نتائجه مع مسارات الملفات وأرقام الأسطر.

‏AGENTS.md يخبر Codex كيف يعمل.

Maguyva تمنح Codex ما يعمل انطلاقًا منه.

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

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

// workflow 01

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

codex> أعد تسمية PaymentClient إلى BillingClient

graph::callers(PaymentClient)            12 references across 7 packages
graph::importers(src/payments/client.ts)  9 importers
graph::extends(PaymentClient)             2 subclasses (RetryClient, MockClient)

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

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

// workflow 02

إيجاد التنفيذ الحقيقي، لا البديل الاختباري

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 التنفيذ الحقيقي فوق محاكي الاختبار.

// workflow 03

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

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 ألف سطر مُفهرَس من المستودع، بلا بطاقة.

  1. // step 01

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

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

  2. // step 02

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

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

# equivalent ~/.codex/config.toml
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

  3. // step 03

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

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

التسجيل الذاتي متاح الآن.

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

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

افهرس مستودعك الأولعرض وثائق التوافق

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