‏Harness Handbook؛ نقشهٔ رفتاری هارنس ایجنت‌ها

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

مشکل از نظرشون نبود کد نیست، نبود مسیر از رفتار به پیاده‌سازیه. برای مثال Codex رو مثال زدن که مدل و ابزار و state و دسترسی‌ها و محیط اجرا رو هماهنگ می‌کنه، ولی پیاده‌سازیش بین ۲۲۶۷ فایل، بیش از ۳۴ هزار تابع و نزدیک ۱۶۰ هزار ارتباط کدی پخش شده. تو این مقیاس، درخت فایل فقط می‌گه کد کجاست، نه اینکه تیکه‌ها چطور با هم یه رفتار می‌سازن.

راه‌حلشون یه نقشهٔ رفتاری سه‌لایه‌ست. L1 نمای کلی سیستمه و یه درخواست رو از ابتدا تا انتها دنبال می‌کنه؛ L2 اون جریان رو به «واحدهای رفتاری» می‌شکنه با مسئولیت، ورودی و خروجی، وابستگی و state کلیدی؛ و L3 می‌ره داخل یه واحد: کی فعال می‌شه، چطور اجرا می‌شه، بعد از خطا چه مسیری می‌ره و کدوم فایل و تابع شاهدشه.

نکتهٔ مهم اینه که نقشه با خلاصه کردن فایل‌ها به دست نمیاد. اول واقعیت‌های ایستا استخراج می‌شن — فایل‌ها، توابع، کلاس‌ها، روابط فراخوانی، خوندن و نوشتن state و فراخوانی API بیرونی — و یه program graph می‌سازن. بعد این گراف به نقشهٔ رفتار بازچینی می‌شه و یه حلقهٔ proposer–reviewer اون‌قدر اصلاحش می‌کنه تا مرزها و شواهد کد بخونن.

روی همین نقشه، چیزی که اسمشو Behavior-Guided Progressive Disclosure گذاشتن اجرا می‌شه: از سؤال رفتاری شروع می‌کنی، L1 زمینهٔ سیستمی می‌ده، L2 واحد مربوطه رو پیدا می‌کنه و L3 جزئیات قابل‌راستی‌آزمایی رو باز می‌کنه. سه کاربردش هم فهمیدن، ممیزی امنیتی و تغییر دادن سیستمه — هر سه از یه مسیر شواهد رد می‌شن.

برای اینکه ببینن واقعاً کار می‌کنه، یه ایجنت کدنویس مبتنی بر NexAU با پلنر DeepSeek-V4-Pro رو روی دو هارنس واقعی یعنی Terminus-2 و Codex تست کردن؛ تنها تفاوت دو حالت این بود که پلنر قبل از پیدا کردن محل تغییر، هندبوک رو می‌خونه یا نه. سه مدل داور مستقل — GPT-5.5، Opus 4.8 و DeepSeek-V4-Pro — نتیجه رو قضاوت کردن.

به گفتهٔ نویسنده‌ها، حالت با هندبوک هم بیشتر برنده شده و هم توکن کمتری خرج کرده؛ یعنی مزیت از «کانتکست بیشتر» نمیاد، از رسیدن زودتر به کد مرتبط میاد. Recall و precision و F1 تو تقریباً همهٔ حالت‌ها بالا رفتن و موارد Wrong — جایی که پلنر کلاً تو زیرسیستم اشتباه فرود میاد — به‌شدت کم شدن، و این مزیت تو تسک‌های سخت هم از بین نرفته.

بخش آخر Handbook Studio ـه: یه میزکار که ریپو رو وصل می‌کنی، هندبوک سه‌لایه ساخته می‌شه و همون‌جا می‌خونی، با کلیک روی هر واحد رفتاری سورس مربوطه تو پنل کناری باز می‌شه، و تغییر رو هم روی نقشه توصیف می‌کنی تا یه edit plan و دیف قابل‌بازبینی تولید بشه. تا وقتی تأیید نکنی، هیچی روی ریپو نوشته نمی‌شه.

نکات کلیدی:

• مشکل اصلی نبود کد نیست، نبود مسیر از «رفتار» به «پیاده‌سازی»ـه
• ساختار سه‌لایه: نمای سیستم، نمای واحدهای رفتاری، جزئیات یک واحد
• نقشه از روی program graph ساخته می‌شه، نه از خلاصه‌سازی فایل‌ها؛ شعارشون اینه که متن توضیح می‌ده و واقعیت‌های کد لنگر می‌ندازن
• تو آزمایش روی Terminus-2 و Codex، پلنر با هندبوک هم دقیق‌تر بود هم ارزون‌تر
• Handbook Studio همین نقشه رو به میزکار خوندن، راستی‌آزمایی و تغییر تبدیل می‌کنه
• کنترل دست کاربره؛ کد و هندبوک فقط بعد از تأیید آپدیت می‌شن