لم أبدأ استخدام Codex بجدية إلا منذ نحو شهر، ومعظم ذلك جاء بعد أن جعل GPT-5.4 التجربة أكثر عملية بالنسبة إلي. لذلك فهذه ليست مقالة من نوع "خمس سنوات من الخبرة التي اختبرها الميدان". الفكرة أبسط بكثير: بدأ Codex ينجح معي فعلًا حين توقفت عن التعامل معه بوصفه مجرد مربع أنيق لإدخال التعليمات، وبدأت أزوّده منذ البداية بقواعد ثابتة وواضحة.
توفّر OpenAI كلًا من واجهة سطر الأوامر في Codex وتطبيق ماك. وبالنسبة إلي، فكلاهما يقوم على الفكرة نفسها: تعليمات دائمة، وملف AGENTS.md، وقواعد خاصة بالمستودع، ووكيل يبدأ العمل وهو يعرف سلفًا كيف أحب أن تُنجز المهام البرمجية. أميل إلى تطبيق ماك ببساطة لأنه أريح وأمتع في الاستخدام اليومي من نافذة طرفية إضافية.
واجهة سطر الأوامر في Codex تؤدي هذا الدور جيدًا أصلًا. أما تطبيق ماك فيمنحني واجهة أجمل وأكثر راحة لسير العمل نفسه. وما زالت الأمور التي تهمني هي نفسها: تعريف صارم للأنواع، وتعديلات صغيرة ومحددة، وأخطاء صريحة، ومن دون سلوكيات احتياطية عشوائية، وسلاسل توثيق داخل الشفرة بدل الشروح المتناثرة. لا أريد أن أشرح لـ Codex هذه القواعد من الصفر في كل مهمة جديدة. أريد أن يكون هذا الأساس حاضرًا منذ البداية.
عمليًا، مكان ذلك هو Settings -> Personalization -> Custom instructions.
وخلف الكواليس، ترتبط تعليمات التطبيق هذه بملف AGENTS.md الشخصي. وهذا بالضبط ما أريده. أحصل على تجربة تطبيق ألطف، من دون أن أخسر الوضوح الذي يتيحه وجود ملف حقيقي على طريقة واجهة سطر الأوامر.
أين توجد تعليمات Codex المخصصة فعلًا
إذا كنت ستتذكر شاشة واحدة فقط من هذه المقالة، فلتكن هذه.
داخل التطبيق، توجد التعليمات العامة تحت Settings -> Personalization -> Custom instructions. هذه هي الشاشة التي سأبدأ بها.
تقول وثائق Codex من OpenAI إن Codex يستطيع قراءة ملف تعليمات عام من مجلد Codex المنزلي لديك، ويكون عادة ~/.codex/AGENTS.md. كما توضّح وثائق إعدادات Codex أن تعديل التعليمات المخصصة يحدّث تعليماتك الشخصية في AGENTS.md.
وهذا هو النموذج الذي أريده بالضبط. أستطيع أن أستخدم التطبيق بوصفه الواجهة الأساسية من دون أن أفقد وضوح الملف الكامن وراءه.
هكذا يبدو تصوري الذهني:
- ملف
~/.codex/AGENTS.mdالشخصي من أجل القواعد الافتراضية العابرة للمشاريع - ملف
AGENTS.mdالخاص بالمستودع من أجل إرشادات الفريق والمشروع - إعدادات تطبيق Codex وإرشادات المستودع التي تأتي فوق هذه القواعد
وهذه هي الشاشة:
القواعد التي أريد أن يحملها Codex معه أينما ذهب
هذا هو الأساس الذي أريد أن يدخل به Codex إلى أي مستودع قبل أن يرى أي تعليمات خاصة بالمشروع.
# Global Rules
## Code Style
- Comments in English only
- Prefer functional programming over OOP
- Use OOP classes only for connectors and interfaces to external systems
- Write pure functions - only modify return values, never input parameters or global state
- Follow DRY, KISS, and YAGNI principles
- Prefer simple, native, vendor-recommended solutions and avoid premature abstractions
- Use strict typing for returns, variables, collections, and complex data; validate external/API data at runtime; require needed fields, ignore unrelated extra fields, prefer structured models over loose dictionaries, and avoid weak generic types like `Any`, `unknown`, or `List[Dict[str, Any]]`
- Check if logic already exists before writing new code
- Never use default parameter values - make all parameters explicit
- Write simple single-purpose functions - no multi-mode behavior, no flag parameters that switch logic. If the user needs multiple modes, they will ask explicitly
## Error Handling
- Always raise errors explicitly, never silently ignore them
- Use specific error types that clearly indicate what went wrong
- Avoid catch-all exception handlers that hide the root cause
- No fallbacks, symptom-masking guards, or silent recovery unless I explicitly ask for them; fix root causes and make code either succeed or fail with a clear error
- External API or service calls: use retries with warnings, then raise the last error
- Error messages must be clear, actionable, and specific: explain what failed and why, include request params, response body, status codes, and avoid generic "something went wrong"
- Logging should use structured fields instead of interpolating dynamic values into message strings
## Libraries and Dependencies
- Use modern stable, project-compatible package management, libraries, and language standards; prefer vendor-recommended patterns such as ESM when supported
- Install dependencies in project environments, not globally
- Add or update dependencies in project config files, not as one-off manual installs
- If a dependency is installed locally, read its source code when needed instead of guessing, even if it is gitignored
## Testing
- Respect the repository test strategy and add only the minimum useful tests for the requested change
- Prefer smoke, integration, and end-to-end tests over narrow unit or regression tests; do not test static text, prompts, or config unless behavior depends on them
- Do not create fake/mock-based tests by default; use real integrations when practical, even if they cost a little money
- UI tests and automations must use stable IDs, test IDs, or accessibility IDs instead of visible text, and fail fast without fallback clicks
## Terminal Usage
- Prefer non-interactive commands with flags over interactive ones
- Always use non-interactive git diff: `git --no-pager diff` or `git diff | cat`
## Workflow
- Read the existing code and relevant project instructions before editing
- Keep changes minimal and tightly scoped to the current request: make the smallest useful diff, change only the lines needed to solve the problem, and avoid unrelated improvements unless the user asks for them
- Match the existing style of the repository even if it differs from my personal preference; new code must look like it was written by the same author
- Keep files small and cohesive; split by feature or responsibility when the project has no established structure
- Do not revert unrelated changes
- If you are unsure, inspect the codebase instead of inventing patterns
- When project instructions include test or lint commands, run them before finishing if the task changed code
## Documentation
- Code is the primary documentation - use clear naming, types, and docstrings
- Keep documentation in docstrings of the functions, classes, or modules they describe, not in separate files
- Separate docs files only when a concept cannot be expressed clearly in code, and only one file per topic
- Never duplicate documentation across files; reference other sources instead
- Store knowledge as current state, not as a changelog of modifications
## Commits
- Never create a git commit unless the user explicitly asks for one
- Prefer `git merge` over `git squash` whenever possible, unless the user explicitly asks for squash.
- Uncommitted changes are the user's review state - they read the diff before deciding what to commit
- Keep changes uncommitted until asked, so the diff stays clean and reviewable
هذا الملف ممل، وذلك بأفضل معنى ممكن.
وظيفته أن يزيل مصادر الاحتكاك المتكررة:
- أن يخترع Codex إعادة هيكلة واسعة بينما كنت أريد تعديلًا محدودًا
- أن يخفي Codex عدم يقينه خلف لغة ناعمة وملتبسة
- أن يضيف Codex سلوكًا احتياطيًا "من باب الأمان"
- أن يتجاوز Codex أعراف المستودع لأن صياغة المهمة كانت أضيق من اللازم
ومتى كانت هذه القواعد محمّلة سلفًا، تصبح الجلسة أهدأ بكثير.
لماذا أضع القواعد العامة فوق قواعد المستودع
يدعم Codex تدرّج ملفات AGENTS.md بشكل جيد. وتوثّق OpenAI وجود ملف عام في ~/.codex/AGENTS.md، ثم ملفات خاصة بالمستودع وملفات داخلية أكثر تحديدًا كلما صار مسار العمل أكثر خصوصية.
هذه الطبقات مفيدة، لكن الطبقة الأولى يجب أن تكون طبقتي أنا.
ينبغي لملفي الشخصي أن يجيب عن أسئلة مثل:
- إلى أي حد أريد أسلوب الشفرة صارمًا
- ما الذي أعتبره معالجة أخطاء مقبولة
- إلى أي درجة أريد من الوكيل أن يكون جريئًا في التغييرات
- ما الذي تعنيه كلمة "منجز" في العمل البرمجي المعتاد
أما ملف المستودع فيجب أن يجيب عن:
- كيف يُنظَّم هذا المشروع
- ما الأوامر التي ينبغي تشغيلها
- ما الأجزاء الهشة
- كيف يريد الفريق التعامل مع طلبات الدمج والالتزامات والوثائق
والخلاصة القصيرة:
AGENTS.mdالشخصي يشرح كيف أعمل أناAGENTS.mdالخاص بالمستودع يشرح كيف يعمل هذا المشروع
إذا خلطت بين الاثنين، فسأحصل على تكرار، وانحراف مع الوقت، وملف لا يرغب أحد في صيانته.
وهذا أحد الأسباب التي جعلت Codex يعمل معي أفضل مما توقعت. تدرّج التعليمات واضح. ويبدو الأمر أقل شبهًا بحيل الصياغات الخفية، وأكثر شبهًا بنظام حقيقي.
تطبيق ماك هو الواجهة الأساسية، وهذا مهم
تطبيق Codex على ماك هو الجزء الذي أستمتع به أكثر في الوقت الحالي.
وليس السبب أن واجهة سطر الأوامر ضعيفة. على العكس، هي جيدة جدًا أصلًا. لكن التطبيق ألطف بكثير في الاستخدام اليومي. Codex نفسه في الخلفية، لكن الواجهة أكثر راحة بكثير.
ولهذا لا أريد أن تتمحور هذه المقالة حول واجهة سطر الأوامر رغم أهميتها. التطبيق هو الطريقة الأريح لاستخدام النظام نفسه.
وما يجعل التطبيق متينًا لا مجرد طبقة تجميلية هو أن التعليمات ما زالت تستند إلى AGENTS.md. تقول وثائق التطبيق إن تعديل التعليمات المخصصة يحدّث التعليمات الشخصية في AGENTS.md، وهذه هي العلاقة التي أريدها بالضبط:
- إعدادات التطبيق من أجل الراحة
- تعليمات قائمة على الملفات من أجل الاستمرارية
وهذا يجعل استخدام واجهة سطر الأوامر لاحقًا سهل الفهم أيضًا، لأن التعليمات الأساسية نفسها تبقى حاضرة هناك.
ما زال AGENTS.md الخاص بالمشروع مهمًا، لكنه ليس محور القصة
لا أريد لهذه المقالة أن تتحول إلى درس عن تداخل ملفات AGENTS.md، رغم أن Codex يدعم ذلك جيدًا.
الصيغة التي أتبناها أبسط:
AGENTS.mdالشخصي يمنح Codex سلوكي الافتراضيAGENTS.mdالخاص بالمستودع يمنح Codex توقعات هذا المستودع تحديدًا- الملفات الأعمق في المسارات الفرعية مخصصة للحالات النادرة التي تحتاج ذلك فعلًا
وهكذا يظل النظام سهل الفهم.
إذا فتحت مستودعًا عشوائيًا وتصرف Codex بشكل سيئ، فأنا أريد أن أعرف السبب بسرعة. وفي الغالب ينبغي أن تكون الإجابة واحدة من هذه:
- قواعدي العامة غير واضحة
- تعليمات المستودع مفقودة
- المهمة نفسها واسعة أكثر من اللازم
وليس: "نسيت أي طبقة من سبع طبقات خفية رجّحت كفة هذه الجولة."
أين تأتي واجهة سطر الأوامر في إعداد Codex لدي
تطبيق ماك هو واجهتي الأساسية. وواجهة سطر الأوامر ليست بديلًا من الدرجة الثانية. إنها النظام نفسه، لكن في وضع استخدام مختلف.
ومع ذلك، ما زالت واجهة سطر الأوامر مهمة لعدة أسباب:
- لأنه يجعل الإعداد القائم على الملفات واضحًا جدًا
- ولأنه يسهّل فحص السلوك بدقة أو تضمينه في السكربتات
أنا لا أريد تصورًا منفصلًا عن واجهة سطر الأوامر. أريد ملف AGENTS.md الشخصي نفسه، وإرشادات المستودع نفسها، والضوابط نفسها في الحالتين.
وهذا الاتساق جزء كبير من سبب شعوري بأن المنتج متماسك.
إعداد Codex العملي الذي أستخدمه الآن
لو كنت سأعد هذا من الصفر على جهاز ماك اليوم، فغالبًا سأرتبه بهذا الشكل.
1. اكتب التعليمات الشخصية أولًا داخل التطبيق
افتح إعدادات تطبيق Codex باستخدام Cmd+,، ثم اذهب إلى Personalization، واكتب التعليمات المخصصة هناك أولًا. ما زلت أفكر انطلاقًا من ~/.codex/AGENTS.md، لكن التطبيق هو المكان الأساسي الذي أضبط فيه هذا وأراجعه.
2. اجعل الملف الشخصي قصيرًا وواضحًا
هندسة المشروع لا مكان لها هنا. ما ينتمي إلى هذا الملف هو القواعد البرمجية الدائمة:
- تعريف صارم للأنواع
- أخطاء صريحة
- لا سلوكيات احتياطية صامتة
- تعديلات محدودة
- سلاسل توثيق بدل الوثائق المبعثرة
- عادات نظيفة في الطرفية
3. أضف AGENTS.md الخاص بالمستودع فقط لما يخص المستودع نفسه
الأوامر، والهندسة، والقيود، وتوقعات الاختبار، والتسمية، والمناطق الحساسة. هذه هي طبقة المستودع.
لماذا يبدو Codex واعدًا بالنسبة إلي الآن
ما زلت في بداية الطريق مع Codex، لذلك لن أبالغ في الترويج له.
لكن هذه التركيبة قوية بالفعل:
- طبقة تعليمات حقيقية قائمة على الملفات
- تطبيق وواجهة سطر الأوامر يبدوان مترابطين بدل أن يبدوا متناقضين
وهذا يكفيني لأواصل استخدامه.
الإعداد الذي يعمل معي أفضل من غيره حتى الآن هو أيضًا الأقل استعراضًا: اكتب تعليمات دائمة جيدة، وافصل إرشادات المستودع، ودع الوكيل يبدأ من أساس يطابق طريقتك في العمل أصلًا.
النمط نفسه مع Cursor. والنمط نفسه مع Claude Code. منتج مختلف، والدرس نفسه: تسير الجلسة على نحو أفضل عندما يتوقف الوكيل عن تخمين من تكون.
إذا كنت تريد المقالات المرافقة، فهي هنا:
- قواعد Cursor IDE للذكاء الاصطناعي: https://kirill-markin.com/ar/maqalat/qawaid-cursor-ide-lilthakaa-alistinaei-tahseen-barmaja/
- قواعد Claude Code للذكاء الاصطناعي: https://kirill-markin.com/ar/maqalat/qawaid-claude-code-lilthakaa-alistinaei/
