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

لمستخدمي 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 أبدًا” المحدَّدة النطاق لمجلد معيَّن.
  • أعراف التسمية وتفضيلات إعادة الهيكلة.
  • إشارات إلى سجلّات القرارات المرجعية وملاحظات المعمارية.

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

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

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

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

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

// workflow 01

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

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.

// 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

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

ذو صلة

اقرأ أيضاً

جميع عمليات التكامل