تحليل تصميم harness في Codex

لعل Codex من OpenAI أكثر المنتجات الأربعة ارتباطًا بـ «أصول harness»—فمقال «Harness Engineering» الذي منح المجال كله اسمه، هو في حد ذاته خلاصة خبرة فريق OpenAI في بناء منتج باستخدام Codex. لذلك فإن تحليل تصميم harness في Codex هو، إلى حد بعيد، تحليل للممارسات الهندسية الكامنة وراء ذلك المقال.

يمكن تلخيص فلسفة Codex في جملة واحدة: المستودع هو مصدر الحقيقة (repository as the system of record)، وAGENTS.md مجرد صفحة فهرس، وتكمن قيمة الهندسة في تصميم البيئة، والتعبير عن المقصد، وبناء حلقات التغذية الراجعة.

التعريف في جملة واحدة

استخدم فريق OpenAI‏ Codex لتسليم منتج بلغ في النهاية أكثر من مليون سطر من الشيفرة خلال بضعة أسابيع، وكتب Codex كل سطر منها (راجع قسم «Designing for growth» في Harness Engineering). وتجيب تجربتهم عن سؤال: كيف ينبغي تنظيم النظام عندما يتحول دور المهندس من «كتابة الشيفرة» إلى «تصميم harness»؟ أما Codex CLI نفسه فهو ملف تنفيذي أحادي مفتوح المصدر (منفذ بلغة Rust، في github.com/openai/codex)، لكن إسهامه في harness يتمحور أساسًا حول الأعراف (convention) وهندسة السياق، لا حول نقاط توسعة براقة.

النظام الفرعي للتعليمات: AGENTS.md صفحة فهرس لا موسوعة

هذه أكثر أفكار Codex تأثيرًا في نظرية harness:

لا يسهل فحص ملف تعليمات عملاق واحد آليًا (من حيث التغطية، وحالة التحديث، والملكية، والروابط المتقاطعة)، ولا يمكن تجنب ابتعاده عن الواقع. لذلك لم نعد نتعامل مع AGENTS.md بوصفه موسوعة، بل بوصفه صفحة فهرس. وتوجد معرفة قاعدة الشيفرة في وثائق منظمة، بينما يشير AGENTS.md إليها.

(ما سبق نقل مباشر بالمعنى لقسم «AGENTS.md should be a directory page» في النص الأصلي لمقال Harness Engineering.)

تقول المحاضرة الرابعة إن «ملف التعليمات العملاق الواحد يفشل»، ويقدم Codex الحل الصحيح مباشرة: أبقِ AGENTS.md في حدود 100 سطر تقريبًا (يوصي النص الأصلي بنحو 100 سطر، وانقله إلى docs/ عند الاقتراب من الحد)، وقسّم ما لا يتسع له إلى دليل docs/ ليقرأه الـ agent عند الطلب. وهذا هو المصدر الموثوق لعبارة «قدّم خريطة، لا دليل تعليمات».

ويسمى المبدأ المصاحب فرض الثوابت بدل الإدارة الدقيقة للتنفيذ (في النص الأصلي: "don't micromanage the implementation；focus on invariants"): لا يُكتب في AGENTS.md سوى القيود الصلبة التي لا يجوز انتهاكها وأوامر التحقق، ويُترك للنموذج تقرير كيفية التنفيذ. وهذا يقابل مباشرة «القيود لا الإدارة الدقيقة» في المحاضرة الثانية.

النظام الفرعي للسياق: Write-Select-Compress-Isolate

يمكن تلخيص هندسة السياق في Codex بأربع استراتيجيات. وقد صاغ المجتمع هذا الإطار بعد أن أصبحت «هندسة السياق» مجالًا مستقلًا، ثم واءمه مع Codex (راجع مصدر الإطار Context Engineering for Codex CLI):

• Write (الكتابة إلى الخارج): حفظ السياق خارج النافذة—تُكتب الاستنتاجات في الوثائق، والحالة في الملفات، بدل إبقائها في المحادثة. ويقابل ذلك «المستودع هو مصدر الحقيقة».
• Select (الانتقاء إلى الداخل): إدخال الـ token المطلوبة فقط إلى النافذة—يشير AGENTS.md إلى الطريق، وتُقرأ الملفات عند الطلب، بدل حشر المستودع كله فيها.
• Compress (compaction): الاحتفاظ بما يهم فعلًا—يتضمن Codex compaction تلقائيًا وأمر /compact يدويًا، ويمكن تخصيص compact_prompt (راجع Context Engineering for Codex CLI).
• Isolate (العزل): تقسيم السياق إلى حدود مختلفة—استخدام subagent لعزل سياق كل مهمة، بحيث لا يرى subagent الواجهة الأمامية مخطط قاعدة بيانات الواجهة الخلفية مطلقًا.

ولدى Codex تفصيلة دقيقة في تصميم سياق البيئة: يوضح تحليل المجتمع للشيفرة المصدرية في codex-harness-internals أن build_environment_update_item لا يخرج إلا الحقول المتغيرة (CWD، وفرع git، ونظام الملفات) عند تغير البيئة، بدل لصق سياق النظام كاملًا في كل جولة. وهذه تفصيلة هندسية تحقق مبدأ «عدم الاحتفاظ بـ token مكررة في السياق».

الأدوات والحدود: عزل worktree + subagents

لدى Codex آليتان جوهريتان في harness:

1. عزل البيئة بواسطة git worktree. يوضح قسم «Environment» في النص الأصلي لمقال Harness Engineering أن كل مهمة تعمل في git worktree مستقل، مع مكدس محلي لقابلية الرصد (السجلات، والمقاييس، والتتبعات)، كي يُتحقق من كل تغيير في بيئة مستقلة. وهذا هو التطبيق المادي للمحاضرة السابعة «وضع حدود واضحة لكل مهمة agent»—فالحدود لا تعتمد على التوسل في التعليمات، بل تفرضها عزلة البيئة. وهنا يتحول النظام الفرعي للبيئة (environment) إلى عزل صلب.

2. subagents على مستوى النواة. أداتا spawn_agent وwait_agent في Codex أداتان على مستوى النواة: ينشئ النموذج subagent صراحة، ويمنحه سجل session ومجموعة أدوات مستقلين، ثم ينتظر النتيجة. يرث subagent تعليمات AGENTS.md من الأب، لكنه يعمل في سياقه الخاص. ويوضع الإعداد في .codex/agents/*.toml، مع إمكان تحديد نماذج وتعليمات مختلفة (راجع قسم Sub-agents في Context Engineering for Codex CLI). وهذا تطبيق مباشر لـ «عزل السياق»—ولروح «التسليم» في المحاضرة الثانية عشرة أيضًا: فكل subagent وحدة عمل ذات حدود واضحة.

النظام الفرعي للتغذية الراجعة: كتابة أوامر التحقق في المواصفات

أهم ما تؤكد عليه تجربة OpenAI هو إدراج أوامر التحقق صراحة في AGENTS.md، بحيث تصبح «كيفية التأكد من صحة العمل» جزءًا من المستودع. وفي سير العمل الهندسي لـ Codex، يولّد Codex الاختبارات، وCI، والوثائق، وإعدادات قابلية الرصد—وكلها «مسارات تحقق قابلة للتنفيذ». ولا يكون حل مشكلة نموذج قوي القدرات لكنه غير موثوق هو الدعاء بأن ينضبط من تلقاء نفسه، بل جعل مسار التحقق مكوّنًا افتراضيًا في harness.

أما approval policies وplan mode فهما وجه آخر للتغذية الراجعة: إذ تُعرض الخطة وتُطلب الموافقة قبل تنفيذ العمليات عالية المخاطر، فتتحول «حدود المهمة» و«سلطة القرار البشري» إلى ضوابط runtime.

المواءمة مع إطار الدورة

النظام الفرعي	تطبيق Codex	التقييم
التعليمات	صفحة فهرس AGENTS.md + التقسيم إلى docs/ + فرض الثوابت	تطبيق نموذجي يعرّف «قدّم خريطة لا دليل تعليمات»
الأدوات	عزل worktree + الوكلاء الفرعيون spawn_agent	حدود قوية تفرضها عزلة البيئة
البيئة	worktree مستقل + مكدس قابلية الرصد	عزل worktree هو علامته المميزة
الحالة	استراتيجية Write (كتابة الحالة في الملفات/الوثائق)	تعتمد على العرف لا على ذاكرة مضمّنة
التغذية الراجعة	أوامر التحقق في المواصفات + سياسات الموافقة + plan mode	جعل مسار التغذية الراجعة افتراضيًا، وهو جدير بالاقتباس

المقارنة بين Codex وClaude Code ممتعة: Claude Code يتبع «الإضافة»—إذ يضمّن الذاكرة وpermissions وsubagents كلها في النواة؛ بينما يتبع Codex «الطرح»—فيحافظ على نواة منضبطة وينقل مزيدًا من المسؤولية إلى أعراف المستودع وهندسة السياق. ولهذا كثيرًا ما يقول المجتمع إن «فلسفة harness في Codex أثمن من شيفرته».

تصميمات جديرة بالاقتباس

1. كتابة AGENTS.md كصفحة فهرس: أبقه في حدود 100 سطر تقريبًا، وأشر إلى التفاصيل في docs/، واجعله قابلًا للفحص الآلي.
2. كتابة الثوابت فقط، من دون إدارة التنفيذ تفصيليًا: قيود صلبة + أوامر تحقق، وترك الباقي للنموذج.
3. استخدام worktree لعزل البيئة: فرض حدود المهمة عبر البيئة، لا بالتوسل في التعليمات.
4. تمرير التغيرات فقط في سياق البيئة: إخراج الحقول المتغيرة في كل جولة، من دون تكرار لصق سياق النظام كاملًا.
5. استخدام subagents لعزل السياق: قسّم السياق عند تقسيم المهمة، ولا تدع المهام الفرعية تلوث الحلقة الرئيسية.

المصادر المرجعية (النص الأصلي / الشيفرة المصدرية)

يمكن تتبع كل ادعاء إلى النص الأصلي أو الشيفرة المصدرية أدناه، تجنبًا للنقل اعتمادًا على الانطباع:

• مقال OpenAI‏ «Harness Engineering»: صفحة فهرس AGENTS.md والتوصية بنحو 100 سطر، وexecutive invariants / don't micromanage، وعزل worktree + مكدس قابلية الرصد، وإدراج أوامر التحقق في المواصفات، وحالة المنتج ذي أكثر من مليون سطر، وسياسات الموافقة، وplan mode. وهو المصدر الرئيسي لجميع الادعاءات الجوهرية في هذه المقالة.
  https://openai.com/index/harness-engineering/
• مواصفة OpenAI الرسمية «AGENTS.md» (معيار AGENTS.md بوصفه عرفًا عابرًا للأدوات):
  https://openai.com/index/agents-md/
• مستودع Codex CLI المفتوح المصدر (ملف تنفيذي أحادي بلغة Rust):
  https://github.com/openai/codex
• Context Engineering for Codex CLI (من المجتمع): إطار Write-Select-Compress-Isolate، و/compact وcompact_prompt، وsubagents عبر spawn_agent / wait_agent، وإعداد .codex/agents/*.toml.
  https://codex.danielvaughan.com/2026/06/10/context-engineering-codex-cli-write-select-compress-isolate-june-2026/
• codex-harness-internals (تحليل مجتمعي للشيفرة المصدرية): تفاصيل التنفيذ مثل سياق البيئة التزايدي في build_environment_update_item.
  https://github.com/AlexKenbo/codex-harness-internals

المحاضرات ذات الصلة: المحاضرة الثالثة · جعل مستودع الشيفرة مصدر الحقيقة الوحيد ｜ المحاضرة الرابعة · تقسيم التعليمات بين ملفات مختلفة ｜ المحاضرة السابعة · وضع حدود واضحة لكل مهمة agent