کالبدشکافی طراحی هارنس Codex

ابزار Codex از شرکت OpenAI شاید محصولی باشد که در میان این چهار مورد، عمیق‌ترین پیوند را با «مفاهیم بنیادین هارنس» دارد. مقاله‌ای که کل این حوزه را مهندسی هارنس (Harness Engineering) نامید، خود خلاصه‌ای از تجارب تیم OpenAI در ساخت یک محصول با Codex بود. بنابراین، کالبدشکافی طراحی هارنس Codex عمدتاً به معنای بررسی شیوه‌های مهندسی پشت آن مقاله است.

فلسفه Codex را می‌توان در یک جمله خلاصه کرد: مخزن منبع مرجع است، AGENTS.md تنها یک صفحه فهرست است، و ارزش مهندسی در طراحی محیط‌ها، بیان نیت و ساخت حلقه‌های بازخورد نهفته است.

در یک جمله#

تیم OpenAI از Codex برای تحویل محصولی استفاده کرد که در عرض چند هفته به بیش از یک میلیون خط کد رسید، و تک‌تک خطوط کد توسط Codex نوشته شده بود (بخش "Designing for growth" در مقاله Harness Engineering را ببینید). تجربه آن‌ها به این پرسش پاسخ می‌دهد: هنگامی که نقش مهندس از «کدنویسی» به «طراحی هارنس» تغییر می‌یابد، یک سیستم چگونه باید سازماندهی شود؟ باینری Codex CLI خود یک باینری یکپارچه متن‌باز پیاده‌سازی‌شده با Rust است (github.com/openai/codex)، اما سهم اصلی آن در طراحی هارنس در عرف‌ها و قراردادها و مهندسی زمینه نهفته است، نه در نقاط گسترش پرزرق‌وبرق.

زیرسیستم دستورالعمل‌ها: AGENTS.md یک صفحه فهرست است، نه یک دانشنامه#

این اثرگذارترین سهم Codex در تئوری هارنس است:

یک فایل دستورالعمل غول‌پیکر را به‌سختی می‌توان از نظر پوشش، تازگی، مالکیت و پیوندهای متقابل به‌صورت مکانیکی بررسی کرد، بنابراین انحراف و فرسودگی آن اجتناب‌ناپذیر است. از این رو، ما برخورد با AGENTS.md به عنوان یک دانشنامه را متوقف کردیم و آن را به عنوان یک صفحه فهرست (directory page) در نظر گرفتیم. دانش پایگاه کد در مستندات ساختاریافته زندگی می‌کند، و AGENTS.md به آن اشاره می‌نماید.

(بخش فوق نقل مستقیمی از بخش "AGENTS.md should be a directory page" در مقاله Harness Engineering است.)

درس 4 می‌گوید «یک فایل دستورالعمل غول‌پیکر شکست می‌خورد»، و Codex پاسخ مستقیم را ارائه می‌دهد: حجم AGENTS.md را در حدود 100 سطر نگه دارید (نسخه اصلی حدود 100 سطر را توصیه می‌کند و با نزدیک شدن به این سقف، انتقال محتوا به پوشه docs/ را پیشنهاد می‌دهد). اگر جا نمی‌شود، آن را به دایرکتوری docs/ تقسیم کنید و اجازه دهید ایجنت فایل‌ها را بر حسب تقاضا بخواند. این منبع معتبر اصل «نقشه را بده، نه دفترچه راهنما را» است.

اصل همراه با آن، اعمال نامتغیرها (invariants) است، نه ریزمدیریت پیاده‌سازی (در متن اصلی: "don't micromanage the implementation; focus on invariants"). فایل AGENTS.md باید تنها شامل محدودیت‌های غیرقابل‌نقض و دستورات راستی‌آزمایی باشد، و جزئیات پیاده‌سازی به مدل واگذار شود. این مستقیماً به مفهوم «محدودیت‌ها به جای ریزمدیریت» در درس 2 نگاشت می‌شود.

زیرسیستم زمینه: نوشتن-انتخاب-فشرده‌سازی-ایزوله‌سازی#

مهندسی زمینه در Codex را می‌توان در چهار راهبرد خلاصه کرد. این چارچوب توسط جامعه کاربری پس از ظهور «مهندسی زمینه» به عنوان یک شاخه مستقل تدوین شد و سپس بر روی Codex نگاشت گردید (چارچوب را در Context Engineering for Codex CLI ببینید):

• نوشتن (Write): ماندگارسازی زمینه در بیرون از پنجره — نوشتن نتیجه‌گیری‌ها در مستندات و ثبت وضعیت در فایل‌ها به جای رها کردن آن‌ها در گفتگو. این با «مخزن به عنوان منبع مرجع» همخوانی دارد.
• انتخاب (Select): کشیدن تنها توکن‌های ضروری به درون پنجره — اجازه دهید AGENTS.md مسیر را نشان دهد و فایل‌ها بر حسب تقاضا خوانده شوند به جای بارگذاری کل مخزن.
• فشرده‌سازی (Compress): حفظ آنچه واقعاً اهمیت دارد — ابزار Codex از فشرده‌سازی خودکار و دستی /compact با یک compact_prompt قابل تنظیم پشتیبانی می‌کند (به Context Engineering for Codex CLI مراجعه کنید).
• ایزوله‌سازی (Isolate): تقسیم زمینه در مرزهای مختلف — استفاده از زیر-ایجنت‌ها برای ایزوله کردن زمینه وظایف مختلف، به طوری که یک زیر-ایجنت فرانت‌اند هرگز اسکیمای دیتابیس بک‌اند را نبیند.

همچنین Codex طراحی دقیقی برای زمینه محیطی دارد. تحلیل سورس‌کد جامعه کاربری در codex-harness-internals نشان می‌دهد که تابع build_environment_update_item در زمان تغییر محیط، تنها فیلدهای تغییریافته (CWD، شاخه گیت، فایل‌سیستم) را خروجی می‌دهد، به جای اینکه کل زمینه سیستم را در هر نوبت الصاق کند. این یک جزئیات مهندسی است که از نگهداری توکن‌های تکراری در زمینه جلوگیری می‌کند.

ابزارها و مرزها: ایزوله‌سازی با ورک‌تری + زیر-ایجنت‌ها#

ابزار Codex دو سازوکار محوری هارنس دارد:

1. ایزوله‌سازی محیط با ورک‌تری‌های گیت. بخش "Environment" در Harness Engineering بیان می‌کند که هر وظیفه در یک ورک‌تری (worktree) مستقل گیت اجرا می‌شود، همراه با پشته مشاهده‌پذیری محلی (لاگ‌ها، سنجه‌ها، و ردگیری‌ها)، تا هر تغییری در یک محیط ایزوله قابل راستی‌آزمایی باشد. این پیاده‌سازی فیزیکی اصل «ترسیم مرزهای شفاف برای هر وظیفه ایجنت» در درس 7 است: مرز از طریق ایزوله‌سازی محیط اعمال می‌شود، نه از طریق درخواست در دستورالعمل‌ها. در اینجا، زیرسیستم محیط به ایزوله‌سازی سخت تبدیل می‌شود.

2. زیر-ایجنت‌ها در سطح هسته. دستورات spawn_agent / wait_agent ابزارهای اصلی Codex هستند: مدل به طور صریح یک زیر-ایجنت می‌سازد، تاریخچه نشست و مجموعه ابزار مستقل به آن می‌دهد و منتظر نتیجه می‌ماند. زیر-ایجنت‌ها دستورالعمل‌های AGENTS.md را از والد خود به ارث می‌برند، اما در زمینه اختصاصی خود اجرا می‌شوند. پیکربندی آن‌ها در .codex/agents/*.toml قرار دارد، جایی که مدل‌ها و دستورالعمل‌های مختلف می‌توانند تعیین شوند (برای جزئیات به بخش Sub-agents در Context Engineering for Codex CLI مراجعه نمایید). این پیاده‌سازی مستقیم «جداسازی زمینه» است و روح درس 12 درباره تحویل‌ها را تجسم می‌بخشد: هر زیر-ایجنت یک واحد کاری با مرزهای شفاف است.

زیرسیستم بازخورد: قرار دادن دستورات راستی‌آزمایی در مشخصات#

یکی از قوی‌ترین تأکیدها در تجربه OpenAI، فهرست کردن صریح دستورات راستی‌آزمایی در AGENTS.md است، که «نحوه تأیید صحت کار» را به بخشی از مخزن تبدیل می‌کند. در جریان کاری مهندسی Codex، تست‌ها، CI، مستندات و پیکربندی مشاهده‌پذیری همگی توسط Codex تولید می‌شوند، و تک‌تک آن‌ها یک «مسیر راستی‌آزمایی قابل اجرا» فراهم می‌آورند. پاسخ به مدل‌های قدرتمند اما غیرقابل‌اعتماد این نیست که امیدوار باشیم مدل مسئولانه رفتار کند؛ بلکه این است که مسیرهای راستی‌آزمایی را به مؤلفه پیش‌فرض هارنس تبدیل کنیم.

سیاست‌های تأیید (approval policies) و حالت طرح (plan mode) بازخورد را در جهت دیگر فراهم می‌کنند: پیش از اجرای عملیات پرخطر، سیستم ابتدا یک طرح تولید می‌کند و درخواست تأیید می‌نماید، و بدین ترتیب «مرزهای وظیفه» و «اختیار تصمیم‌گیری انسان» را به کنترل‌های زمان اجرا تبدیل می‌سازد.

نگاشت به چارچوب دوره#

تضاد میان Codex و Claude Code روشنگر است. ابزار Claude Code از رویکرد «افزایشی» استفاده می‌کند و حافظه، مجوزها و زیر-ایجنت‌ها را درون هسته می‌گذارد. اما Codex از رویکرد «کاهشی» بهره می‌برد، هسته را مهارشده نگه می‌دارد و مسئولیت بیشتری را بر دوش عرف‌های مخزن و مهندسی زمینه می‌گذارد. به همین دلیل است که جامعه کاربری اغلب می‌گوید «فلسفه هارنس Codex ارزشمندتر از کد آن است».

طرح‌های شایسته الگوبرداری#

1. فایل AGENTS.md را به عنوان صفحه فهرست بنویسید: آن را در حدود 100 سطر نگه دارید، به جزئیات در docs/ ارجاع دهید، و آن را به صورت مکانیکی قابل بررسی بسازید.
2. فقط نامتغیرها را مشخص کنید؛ پیاده‌سازی را ریزمدیریت نکنید: محدودیت‌های سخت + دستورات راستی‌آزمایی، و واگذاری بقیه به مدل.
3. از ورک‌تری‌ها برای ایزوله‌سازی محیط استفاده کنید: مرزهای وظایف را از طریق محیط اعمال کنید، نه از طریق خواهش در دستورالعمل‌ها.
4. تنها تغییرات (دلتا) زمینه محیطی را ارسال کنید: در هر نوبت تنها فیلدهای تغییریافته را خروجی دهید به جای الصاق مکرر کل زمینه سیستم.
5. از زیر-ایجنت‌ها برای جداسازی زمینه استفاده کنید: همگام با تقسیم وظیفه، زمینه را نیز تقسیم نمایید تا زیروظایف حلقه اصلی را آلوده نسازند.

مراجع (منابع اصلی / سورس کد)#

تمام ادعاها را می‌توان در منابع اصلی یا سورس کدهای زیر ردگیری کرد:

• OpenAI, Harness Engineering: صفحه فهرست AGENTS.md و توصیه به حدود 100 سطر، اعمال نامتغیرها / عدم ریزمدیریت، ایزوله‌سازی ورک‌تری + پشته مشاهده‌پذیری، دستورات راستی‌آزمایی در مشخصات، مطالعه موردی محصول یک میلیون خطی، سیاست‌های تأیید و حالت طرح. منبع اصلی برای تمام ادعاهای محوری این مقاله.
  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 (جامعه کاربری): چارچوب نوشتن-انتخاب-فشرده‌سازی-ایزوله‌سازی، /compact و compact_prompt، زیر-ایجنت‌های 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

درس‌های مرتبط: درس 3 · تبدیل مخزن به یگانه منبع حقیقت ｜ درس 4 · چرا یک فایل دستورالعمل غول‌پیکر شکست می‌خورد ｜ درس 7 · ترسیم مرزهای شفاف وظایف برای ایجنت‌ها