درس 02. هارنس در واقع چیست | مهندسی هارنس

Code examples: code/ Practice project: Project 01. Prompt-only vs. rules-first

واژهٔ «هارنس» (harness) در محافل ایجنت‌های کدنویسی هوش مصنوعی بسیار به کار می‌رود، اما بیشتر اوقات وقتی افراد می‌گویند «هارنس»، منظورشان صرفاً یک فایل پرامپت (prompt) است. یک فایل پرامپت هارنس نیست.

این درس به هارنس تعریفی دقیق و کاربردی ارائه می‌دهد — نه یک انتزاع آکادمیک، بلکه چارچوبی که می‌توانید همین امروز آن را به کار بگیرید. یک هارنس از پنج زیرسیستم تشکیل شده است: دستورالعمل‌ها، ابزارها، محیط، وضعیت، و بازخورد. هر زیرسیستم دارای مسئولیت‌ها و معیارهای ارزیابی شفافی است.

شروع با یک تمثیل#

تصور کنید مهندسی تازه‌استخدام هستید و در پروژه‌ای بدون هیچ‌گونه مستندات رها شده‌اید. بدون README، بدون کامنتی در کدها، هیچ‌کس به شما نمی‌گوید آزمون‌ها را چگونه اجرا کنید، و پیکربندی CI در جایی پنهان شده است. آیا می‌توانید کد خوبی بنویسید؟ شاید — اگر به اندازهٔ کافی باهوش و صبور باشید. اما زمان بسیار زیادی را صرف «فهمیدن اینکه این پروژه دربارهٔ چیست» خواهید کرد تا صرف «حل مسئله».

یک ایجنت هوش مصنوعی با دقیقاً همین مخمصه روبه‌رو است، و حتی بدتر. شما دست‌کم می‌توانید از یک همکار سؤال بپرسید. ایجنت فقط می‌تواند فایل‌هایی را که روبه‌رویش قرار می‌دهید و دستوراتی را که می‌تواند اجرا کند ببیند.

شرکت OpenAI اصل بنیادین مهندسی هارنس را این‌گونه بیان می‌کند که «مخزن همان مشخصات است» — تمام زمینهٔ (context) ضروری باید در مخزن جای داشته باشد، که از طریق فایل‌های دستورالعمل ساختاریافته، دستورات صریح راستی‌آزمایی (verification)، و سازماندهی شفاف دایرکتوری‌ها ارائه می‌شود. مستندات ایجنت‌های بلندمدت شرکت Anthropic بر پایداری وضعیت (state)، مسیرهای بازیابی صریح، و ردیابی ساختاریافتهٔ پیشرفت تأکید دارد. این دو شرکت بر جنبه‌های متفاوتی تمرکز دارند، اما هر دو یک سخن می‌گویند: تمام زیرساخت‌های مهندسی خارج از مدل تعیین می‌کنند چه میزان از توانمندی مدل واقعاً محقق می‌شود.

به چند ابزاری که از قبل می‌شناسید نگاهی بیندازید:

Claude Code تجسم تفکر هارنس است. فایل CLAUDE.md را از مخزن شما می‌خواند، می‌تواند دستورات شل را اجرا کند، در محیط محلی شما اجرا می‌شود، تاریخچهٔ نشست را نگه می‌دارد، و می‌تواند آزمون‌ها را برای مشاهدهٔ نتایج اجرا کند. اما اگر به آن نگویید که چگونه آزمون‌ها را اجرا کند، هیچ راهی ندارد تا راستی‌آزمایی کند که آیا کارها را درست انجام داده است یا خیر.

Cursor منطق مشابهی را دنبال می‌کند. فایل .cursorrules منبع دستورالعمل‌های آن است، ترمینال ابزار آن است، و می‌تواند ساختار پروژه و پیکربندی لینت شما را بخواند. با این حال، مدیریت وضعیت در Cursor نسبتاً ضعیف است — محیط توسعه (IDE) را ببندید و دوباره باز کنید، تمام زمینهٔ قبلی از دست رفته است.

Codex (ایجنت کدنویسی OpenAI) از ورک‌تری‌های گیت برای جداسازی محیط اجرای هر وظیفه استفاده می‌کند، همراه با یک پشتهٔ مشاهده‌پذیری محلی (گزارش‌ها، معیارها، ردگیری‌ها)، تا هر تغییر در محیطی مستقل راستی‌آزمایی شود. عملکرد آن در مخازنی با فایل AGENTS.md و دستورات شفاف راستی‌آزمایی بسیار بهتر از مخازن «برهنه» است.

AutoGPT یک داستان عبرت‌آموز است. فقدان مدیریت وضعیت ساختاریافته در آن باعث می‌شود زمینه در وظایف طولانی به‌طور بی‌پایان انباشته شود، و نبود سازوکارهای بازخورد دقیق باعث می‌شود ایجنت در حلقه بیفتد. افراد بسیاری می‌گویند AutoGPT «کار نمی‌کند»، اما در واقعیت این هارنس است که کار نمی‌کند.

مفاهیم اصلی#

هارنس چیست: تمام چیزهایی که در زیرساخت مهندسی خارج از وزن‌های مدل قرار دارند. شرکت OpenAI شغل اصلی مهندس را در سه چیز خلاصه می‌کند: طراحی محیط‌ها، بیان نیت، و ساخت حلقه‌های بازخورد. شرکت Anthropic مستقیماً SDK ایجنت کلود خود را یک «هارنس ایجنت چندمنظوره» می‌نامد.
مخزن تنها منبع حقیقت است: هر چیزی که ایجنت نتواند ببیند، عملاً وجود ندارد. OpenAI مخزن را به‌عنوان «منبع مرجع» در نظر می‌گیرد — تمام زمینهٔ لازم باید در آنجا باشد و از طریق فایل‌های ساختاریافته و سازماندهی تمیز دایرکتوری‌ها ارائه شود.
نقشه بدهید، نه کتابچهٔ راهنما: تجربهٔ OpenAI نشان می‌دهد که AGENTS.md باید صفحه‌ای مانند فهرست باشد، نه یک دانشنامه. حدود 100 خط کافی است. اگر در آن نمی‌گنجد، آن را به دایرکتوری docs/ تقسیم کنید و بگذارید ایجنت بنا بر نیاز آن را بخواند.
محدود کنید، نه اینکه ریزمدیریت کنید: یک هارنس خوب از قواعد قابل‌اجرا برای محدود کردن ایجنت بهره می‌گیرد، نه اینکه دستورالعمل‌ها را یکی‌یکی بشمارد. OpenAI می‌گوید «تغییرناپذیرها را اعمال کنید، پیاده‌سازی را ریزمدیریت نکنید»؛ Anthropic دریافت که ایجنت‌ها کار خود را با اعتمادبه‌نفس بیش از حد تحسین می‌کنند، و راه‌حل این است که «فردی که کار را انجام می‌دهد» از «فردی که کار را بررسی می‌کند» تفکیک شود.
یکی‌یکی حذف کنید و مشاهده نمایید: برای سنجش ارزش مرزی هر مؤلفهٔ هارنس، آن‌ها را یکی‌یکی حذف کنید و ببینید کدام حذف بزرگ‌ترین افت عملکرد را ایجاد می‌کند. این به شما می‌گوید کدام مؤلفه‌ها در حال حاضر بیشترین ارزش را دارند، و همچنین آشکار می‌سازد کدام مؤلفه‌ها هنوز مشارکت معناداری ندارند. Anthropic از این روش استفاده کرد و دریافت با قوی‌تر شدن مدل‌ها، برخی مؤلفه‌ها اهمیت حیاتی خود را از دست می‌دهند — اما همواره مؤلفه‌های حیاتی جدیدی پدیدار می‌شوند.

مدل پنج‌زیرسیستمی هارنس#

بازگردیم به آن تمثیل. یک هارنس دارای پنج زیرسیستم است:

flowchart LR
    Rules["Project rules<br/>AGENTS.md / CLAUDE.md"] --> Agent["AI Agent"]
    State["Progress and git<br/>PROGRESS.md / commits"] --> Agent
    Agent --> Tools["Tools<br/>shell / files / tests"]
    Tools --> Env["Runtime<br/>deps / services / versions"]
    Env --> Checks["Check results<br/>test / lint / build"]
    Checks --> Agent

زیرسیستم دستورالعمل‌ها: فایلی با نام AGENTS.md (یا CLAUDE.md) بسازید که شامل نمای کلی پروژه و هدف آن، پشتهٔ فناوری و نسخه‌ها، دستورات اجرای اولیه، محدودیت‌های سفت‌وسخت غیرقابل‌مذاکره، و پیوندهایی به مستندات با جزئیات بیشتر باشد.

زیرسیستم ابزارها: اطمینان حاصل کنید که ایجنت دسترسی کافی به ابزارها دارد. شل را به‌خاطر «دلایل امنیتی» غیرفعال نکنید — اگر ایجنت حتی نتواند pip install را اجرا کند، چگونه قرار است کاری را به سرانجام برساند؟ اما همه‌چیز را هم باز نگذارید — اصل حداقل دسترسی را رعایت کنید.

زیرسیستم محیط: کاری کنید که وضعیت محیط خودتوصیف‌گر باشد. از pyproject.toml یا package.json برای قفل‌کردن وابستگی‌ها، از .nvmrc یا .python-version برای مشخص‌کردن نسخه‌های زمان اجرا، و از Docker یا devcontainers برای بازتولیدپذیر کردن محیط بهره ببرید.

زیرسیستم وضعیت: وظایف طولانی باید دارای ردیابی پیشرفت باشند. از یک فایل سادهٔ PROGRESS.md استفاده کنید که در آن ثبت شود: چه کارهایی انجام شده است، چه کارهایی در دست اقدام است، و چه مواردی مسدود شده‌اند. قبل از پایان هر نشست آن را به‌روزرسانی کنید؛ و با شروع نشست بعدی آن را بخوانید.

زیرسیستم بازخورد: این زیرسیستم بالاترین نرخ بازگشت سرمایه را دارد. دستورات راستی‌آزمایی را به‌صورت صریح در AGENTS.md فهرست کنید:

Verification commands:
- Tests: pytest tests/ -x
- Type check: mypy src/ --strict
- Lint: ruff check src/
- Full verification: make check (includes all above)

فقدان هر یک از پنج زیرسیستم به‌معنای یک هارنس ناقص است و کار کردن با ایجنت همواره نامطلوب و ناهماهنگ احساس خواهد شد.

سنجش کمّی ارزش مؤلفه‌های هارنس: از یک «آزمون حذف متغیر کنترل‌شده» بهره بگیرید. مدل را ثابت نگه دارید، پنج زیرسیستم را یکی‌یکی حذف کنید، و مشاهده کنید حذف کدام زیرسیستم بیشترین افت عملکرد را به همراه دارد. مؤلفه‌ای با بیشترین افت عملکرد، بالاترین سهم مرزی را برای وظیفهٔ فعلی دارد و شایستهٔ اولویت‌بندی است. اینکه آیا باید آن را تقویت کرد به انتساب علت شکست بستگی دارد، نه صرفاً به میزان افت عملکرد. مؤلفه‌هایی با اثر نزدیک به صفر را نباید بی‌درنگ کنار گذاشت: ممکن است زاید باشند، طراحی ضعیفی داشته باشند، یا صرفاً توسط وظیفهٔ کنونی به کار گرفته نشده باشند. این آزمایش پاسخ می‌دهد که «در حال حاضر کدام مؤلفه ارزشمندترین است» — این آزمایش به‌تنهایی نمی‌تواند اثبات کند که «گلوگاه کجاست». برای یافتن واقعی گلوگاه، ابتدا باید سوابق شکست و انتساب علل را بررسی کنید: آیا وظیفه مبهم بود، آیا زمینه ناکافی بود، آیا محیط بازتولیدناپذیر بود، آیا بازخورد راستی‌آزمایی مفقود بود، یا مدیریت وضعیت گسسته بود؟ نتایج مطالعهٔ حذفی مؤلفه‌ها صرفاً می‌تواند نقش شواهد پشتیبان را ایفا کند.

داستان واقعی یک تیم#

تیمی از GPT-4o برای توسعهٔ یک برنامهٔ فرانت‌اند TypeScript + React (حدود 20,000 خط کد) استفاده کردند. آن‌ها چهار مرحله را پشت سر گذاشتند که در اصل افزودن تک‌تک مؤلفه‌های هارنس بود:

مرحلهٔ 1: فقط یک شرح پایه‌ای پروژه در README. از 5 اجرا، 1 مورد موفق شد (20%). شکست‌های اصلی: انتخاب اشتباه مدیر بسته (npm در برابر yarn)، عدم رعایت قراردادهای نام‌گذاری مؤلفه‌ها، و ناتوانی در اجرای آزمون‌ها.

مرحلهٔ 2: افزودن AGENTS.md که نسخه‌های پشتهٔ فناوری، قراردادهای نام‌گذاری، و تصمیمات کلیدی معماری را مشخص می‌کرد. نرخ موفقیت به 60% رسید. شکست‌های باقی‌مانده بیشتر ناشی از مسائل محیط و نبود راستی‌آزمایی بود.

مرحلهٔ 3: فهرست کردن دستورات راستی‌آزمایی در AGENTS.md: دستور yarn test && yarn lint && yarn build. نرخ موفقیت به 80% افزایش یافت.

مرحلهٔ 4: معرفی قالب‌های فایل پیشرفت که ایجنت کارهای تکمیل‌شده و ناتمام را در هر اجرا در آن‌ها ثبت می‌کرد. نرخ موفقیت در محدودهٔ 80 تا 100% تثبیت شد.

چهار تکرار، مدل هیچ تغییری نکرد، و نرخ موفقیت از 20% به نزدیک 100% رسید. شما به مدل بهتری سوییچ نکردید — آنچه تغییر کرد هارنس بود.

نکات کلیدی#

هارنس = دستورالعمل‌ها + ابزارها + محیط + وضعیت + بازخورد. تمام این پنج زیرسیستم ضروری هستند.
اگر جزو وزن‌های مدل نیست، هارنس است. هارنس شما تعیین می‌کند چه میزان از توانمندی مدل محقق خواهد شد.
در میان پنج زیرسیستم، زیرسیستم بازخورد معمولاً کمترین سرمایه‌گذاری و بیشترین بازدهی را دارد. ابتدا دستورات راستی‌آزمایی خود را به‌درستی تنظیم کنید.
از «آزمون‌های حذف متغیر کنترل‌شده» برای سنجش کمّی سهم مرزی هر زیرسیستم بهره ببرید؛ برای پیدا کردن گلوگاه واقعی، به سوابق شکست و انتساب علت‌ها اتکا کنید، نه صرفاً به مطالعهٔ حذفی.
هارنس نیز همانند کد دچار فرسودگی می‌شود. مرتباً آن را بازبینی کنید، و بدهی هارنس را دقیقاً همانند بدهی فنی تسویه نمایید.

منابع بیشتر#

تمرین‌ها#

بازبینی پنج‌گانهٔ هارنس: پروژه‌ای را که در حال حاضر در آن از ایجنت هوش مصنوعی استفاده می‌کنید بردارید و با بهره‌گیری از چارچوب پنج‌گانه یک بازبینی کامل انجام دهید. به هر زیرسیستم امتیازی بین 1 تا 5 بدهید. زیرسیستمی را که کمترین امتیاز را دارد پیدا کنید، 30 دقیقه برای بهبود آن وقت بگذارید، و سپس تغییر در عملکرد ایجنت را مشاهده نمایید.
آزمون حذف متغیر کنترل‌شده: یک مدل و یک وظیفهٔ چالش‌برانگیز را برگزینید. به‌صورت متوالی دستورالعمل‌ها را حذف کنید (حذف AGENTS.md)، بازخورد را حذف کنید (عدم ارائهٔ دستورات راستی‌آزمایی)، و وضعیت را حذف کنید (نبود فایل‌های پیشرفت) — هر بار فقط یکی را حذف نمایید و میزان افت عملکرد را اندازه بگیرید. از نتایج برای رتبه‌بندی ارزش مرزی هر زیرسیستم در وظیفهٔ فعلی بهره ببرید. اگر می‌خواهید گلوگاه را بیابید، باید در کنار مطالعهٔ حذفی، گزارش‌های شکست را ثبت کرده و انتساب علت ریشه‌ای را انجام دهید.
تحلیل توانمندی عمل (Affordance analysis): سناریویی در پروژهٔ خود پیدا کنید که در آن ایجنت «می‌خواهد کاری انجام دهد اما نمی‌تواند» (برای نمونه، می‌داند باید از پرس‌وجوهای پارامتری استفاده کند اما الگوهای ORM پروژهٔ شما را نمی‌داند). تحلیل کنید که آیا این یک شکاف اجرا (نمی‌داند چگونه عمل کند) است یا یک شکاف ارزیابی (نمی‌داند آیا کار را درست انجام داده است یا خیر)، و سپس یک بهبود هارنس طراحی کنید تا این شکاف را پر کند.