درس 12. بر جای گذاشتن یک تحویل تمیز در پایان هر نشست

Code examples: code/ Practice project: Project 06. Build a Complete Agent Workspace

ایجنت (agent) شما تمام بعدازظهر را کار می‌کند، 20 فایل را تغییر می‌دهد، کد را کامیت می‌کند، و نشست به پایان می‌رسد. نشست بعدی ایجنت آغاز به کار می‌کند و بلافاصله متوجه می‌شود: بیلد شکسته است، آزمون‌ها قرمز هستند، فایل‌های خطایابی موقت در همه‌جا پراکنده‌اند، فهرست ویژگی‌ها (feature list) به‌روزرسانی نشده است، و پیشرفت کار کاملاً مبهم است. 30 دقیقه نخست نشست جدید کاملاً صرف «فهمیدن اینکه نشست پیشین واقعاً چه کرده است» می‌شود.

هم OpenAI و هم Anthropic به‌روشنی بیان می‌کنند: قابلیت اطمینان بلندمدت به انضباط عملیاتی وابسته است، نه صرفاً به موفقیت در یک اجرای منفرد. کیفیت وضعیت در پایان هر نشست مستقیماً کارایی نشست بعدی را تعیین می‌کند.

رشد آنتروپی حالت پیش‌فرض است#

قوانین لمن دربارهٔ تکامل نرم‌افزار به ما می‌گویند سیستم‌هایی که دستخوش تغییرات مداوم هستند، به‌طور اجتناب‌ناپذیری پیچیده‌تر می‌شوند مگر آنکه به‌طور فعالانه مدیریت گردند. این امر به‌ویژه برای ایجنت‌های کدنویسی هوش مصنوعی صادق است. هر نشست تغییراتی را وارد می‌کند، و بدون پاک‌سازی در هنگام خروج، بدهی فنی به‌صورت نمایی انباشته می‌شود.

در طول پنج ماه آزمایش با Codex، شرکت OpenAI نکتهٔ جالب‌توجهی را مشاهده کرد: ایجنت‌ها الگوهایی را که در حال حاضر در مخزن (repository) وجود دارند کپی می‌کنند، حتی زمانی که آن الگوها ناسازگار یا مادون بهینه باشند. با گذشت زمان، این کپی‌برداری به‌طور اجتناب‌ناپذیری به انحراف منجر می‌شود. نخستین فرد فنجان قهوه را در فضای مشترک رها می‌کند؛ فرد دوم با خود می‌گوید «اینجا که از قبل کثیف است» و فنجان دیگری می‌گذارد؛ یک هفته بعد میز زیر خرواری از فنجان‌ها مدفون شده است. یک پایگاه کد دقیقاً به همین شیوه عمل می‌کند.

تیم OpenAI در ابتدا روزهای جمعه را — یک روز کاری، حدود 20% از ظرفیت هفته — برای پاک‌سازی دستی «شلوغ‌کاری‌های هوش مصنوعی» کنار گذاشت. با افزایش توان عملیاتی، هزینهٔ پاک‌سازی دستی بیش از بازده آن شد. آن‌ها در نهایت به یک راه‌حل سیستماتیک دست یافتند:

1. کدگذاری «قواعد طلایی» درون مخزن: قواعدی مانند «بستهٔ ابزار مشترک را به توابع کمکی دست‌ساز محلی ترجیح دهید» (متمرکز نگه‌داشتن تغییرناپذیرها) و «ساختارهای داده را حدس نزنید» (اعتبارسنجی مرزها یا تکیه بر SDKهای تایپ‌شده). این قواعد ملموس، مکانیکی، و به‌طور خودکار قابل‌بررسی هستند.
2. استقرار جریان‌های کاری پاک‌سازی دوره‌ای: ناوگانی از وظایف پس‌زمینهٔ Codex که به‌طور منظم انحرافات را پایش می‌کنند، نمرات کیفیت را به‌روزرسانی می‌نمایند، و PRهای بازآرایی هدفمند باز می‌کنند. بیشتر این PRها ظرف یک دقیقه بازبینی و به‌طور خودکار ادغام می‌شوند.
3. ثبت سلیقهٔ انسانی برای یک‌بار و اعمال پیوستهٔ آن: کامنت‌های بازبینی، PRهای بازآرایی، و باگ‌های مواجه‌شده توسط کاربران همگی به به‌روزرسانی‌های مستندات تبدیل می‌شوند یا مستقیماً درون ابزارها کدگذاری می‌گردند. وقتی مستندات کافی نباشد، قاعده را به کد ارتقا دهید.

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

منبع: OpenAI: Harness engineering: leveraging Codex in an agent-first world

وضعیت تمیز: فراتر از «کد کامپایل می‌شود»#

وضعیت تمیز (clean state) صرفاً این نیست که «کد کامپایل می‌شود». بیلد بدون خطا پایه‌ای‌ترین نیاز است — نشست بعدی نباید ابتدا خطاهای بیلد را رفع کند. تمام آزمون‌ها نیز باید پاس شوند، از جمله آزمون‌هایی که پیش از این نشست وجود داشتند؛ نشست مسئول نشکستن کارکردهای موجود است. و این باید در CI راستی‌آزمایی (verification) شود، نه صرفاً «روی سیستم من کار می‌کند».

flowchart LR
    Work["Feature work complete"] --> Build{"Build passes?"}
    Build -->|yes| Test{"Tests pass?"}
    Build -->|no| Fix["Fix before exit"]
    Test -->|yes| Record["Update feature list + progress"]
    Test -->|no| Fix
    Record --> Cleanup["Remove temp artifacts / debug code"]
    Cleanup --> Startup{"Standard startup path works?"}
    Startup -->|yes| Clean["Clean handoff"]
    Startup -->|no| Fix
    Fix --> Build

اما این هنوز کافی نیست. پیشرفت کنونی باید در مصنوعات (artifacts) ماشین‌خوان ثبت شود: زیروظایف تکمیل‌شده همراه با معیارهای قبولی، زیروظایف در جریان اما ناقص با وضعیت کنونی، و زیروظایفی که هنوز آغاز نشده‌اند. پیشرفت و نتایج راستی‌آزمایی را در فایل‌های دارای نسخه ثبت کنید تا نشست بعدی بتواند وضعیت را بررسی نماید. مصنوعات موقت — لاگ‌های دیباگ، فایل‌های موقت، کدهای کامنت‌شده، و نشانه‌های TODO — نیز باید پاک‌سازی شوند، زیرا بار شناختی را برای نشست بعدی افزایش می‌دهند. مسیر استاندارد راه‌اندازی نیز باید کارآمد باقی بماند. آیا نشست بعدی می‌تواند بدون دخالت دستی شروع به کار کند؟ مقداردهی اولیهٔ محیط، بارگذاری پایگاه کد، دستیابی به زمینه (context)، و انتخاب وظیفه — هیچ‌یک از این مسیرها نباید دچار شکستگی باشند.

flowchart LR
    Dirty["Session ends with<br/>red tests / temp files not deleted / no progress recorded"] --> Diagnose["Next session first has to<br/>figure out what happened"]
    Diagnose --> Fragile["Then continues modifying<br/>an already messy repo"]
    Fragile --> More["More debug files, more broken checks,<br/>more unclear progress"]
    More --> Dirty

    Clean["Session ends with<br/>green tests / progress updated / temp files deleted"] --> Fast["Next session opens the repo<br/>and can keep coding"]
    Fast --> Stable["No need to fight fires first"]
    Stable --> Clean

مفاهیم اصلی#

• وضعیت تمیز: سیستم باید پنج شرط را در پایان نشست برآورده کند — بیلد پاس شود، آزمون‌ها پاس شوند، پیشرفت ثبت شود، مصنوع کهنه‌ای باقی نماند، و مسیر راه‌اندازی در دسترس باشد. فقدان هرکدام یعنی نشست «تمام نشده» است.
• جامعیت نشست (Session Integrity): همانند تراکنش‌های پایگاه داده — یا کاملاً کامیت کنید و یک وضعیت تمیز بر جای بگذارید، یا به آخرین وضعیت سازگار بازگردید (rollback). هیچ حد وسطی وجود ندارد.
• سند کیفیت (Quality Document): مصنوعی فعال که پیوسته امتیازات کیفی هر ماژول را ثبت می‌کند. نه یک ارزیابی یک‌باره، بلکه یک ردیاب که نشان می‌دهد آیا پایگاه کد با گذشت زمان قوی‌تر می‌شود یا ضعیف‌تر.
• حلقهٔ پاک‌سازی (Cleanup Loop): یک نشست نگهداری منظم با هدف کاهش سیستماتیک آنتروپی در پایگاه کد. نه یک اصلاح اضطراری، بلکه عملیاتی روزمره.
• ساده‌سازی هارنس (Harness Simplification): هم‌گام با ارتقای توانمندی‌های مدل، مؤلفه‌هایی از هارنس (harness) را که دیگر ضروری نیستند به‌طور دوره‌ای حذف کنید. قیدی که امروز ضروری است ممکن است سه ماه دیگر بار اضافی غیرضروری باشد.
• پاک‌سازی پادتوان (Idempotent Cleanup): عملیات پاک‌سازی صرف‌نظر از اینکه چند بار اجرا شوند نتیجهٔ یکسانی تولید می‌کنند، که تضمین می‌کند پاک‌سازی حتی در سناریوهای تلاش مجدد ناشی از شکست ایمن باقی می‌ماند.

«بعداً پاک‌سازی می‌کنم» یعنی هرگز پاک‌سازی نمی‌کنم#

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

بدتر از آن، هر نشست اهداف کاری خود را دارد. نشست جدید آمده تا کارهای جدید انجام دهد، نه اینکه شلوغ‌کاری‌های نشست پیشین را جمع کند. آن آشفتگی را نادیده می‌گیرد و کار جدید را بر روی آن آغاز می‌کند، و آشفتگی بیشتری پدید می‌آورد. این همان حلقهٔ بازخورد مثبت آنتروپی است.

برای یک پروژهٔ فرضی 12 هفته‌ای، مقادیر زیر را در نظر بگیرید:

• هفته 1: نرخ قبولی بیلد 100%، نرخ قبولی آزمون‌ها 100%، راه‌اندازی نشست جدید 5 دقیقه
• هفته 4: بیلد 95%، آزمون‌ها 92%، راه‌اندازی 15 دقیقه
• هفته 8: بیلد 82%، آزمون‌ها 78%، راه‌اندازی 35 دقیقه
• هفته 12: بیلد 68%، آزمون‌ها 61%، راه‌اندازی بیش از 60 دقیقه

همان پروژه با یک راهبرد پاک‌سازی:

• هفته 1: 100%، 100%، 5 دقیقه
• هفته 12: 97%، 95%، 9 دقیقه

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

چگونه این کار را انجام دهیم#

1. وضعیت تمیز یک شرط لازم برای اتمام کار است#

در هارنس به‌طور صریح تعریف کنید: اتمام نشست = وظیفه راستی‌آزمایی را پاس کند AND بررسی وضعیت تمیز پاس شود. فقدان هرکدام یعنی نشست کامل نشده است. در CLAUDE.md بنویسید:

## Session Exit Checklist
- [ ] Build passes (npm run build)
- [ ] All tests pass (npm test)
- [ ] Feature list updated
- [ ] No debug code remaining (console.log, debugger, TODO)
- [ ] Standard startup path available (npm run dev)

2. راهبرد پاک‌سازی دومنظوره#

دو حالت پاک‌سازی را ترکیب کنید:

پاک‌سازی فوری (در پایان هر نشست): مصنوعات موقت ایجادشده در طول نشست را پاک کنید، وضعیت فهرست ویژگی‌ها را به‌روزرسانی نمایید، و از قبولی بیلد و آزمون‌ها اطمینان یابید. این پاک‌سازی به سبک «شمارش ارجاع» است — به محض اتمام استفاده از چیزی، آن را پاک کنید.

پاک‌سازی دوره‌ای (هفتگی): اسکن کامل سیستم — رسیدگی به مشکلات ساختاری انباشته‌شده، به‌روزرسانی اسناد کیفیت، و اجرای آزمون‌های بنچمارک برای تشخیص انحراف. این پاک‌سازی به سبک «ردیابی» است — یک گذر نگهداری فراگیر با ضرب‌آهنگی منظم.

3. نگهداری یک سند کیفیت#

سند کیفیت مصنوعی فعال است که به‌طور مداوم به هر ماژول نمره می‌دهد:

# Quality Document

## User Authentication Module (Quality: A)
- Verification passing: Yes
- Agent understandable: Yes
- Test stability: Stable
- Architecture boundaries: Compliant
- Code conventions: Followed

## Payment Module (Quality: C)
- Verification passing: Partial (payment callback untested)
- Agent understandable: Difficult (logic spread across 3 files)
- Test stability: Unstable (2 flaky tests)
- Architecture boundaries: Violations present
- Code conventions: Partially followed

نشست‌های جدید این سند را می‌خوانند و بی‌درنگ می‌دانند کجای کار را در اولویت قرار دهند. ماژولی را که کمترین نمره را دارد ابتدا اصلاح کنید.

4. ساده‌سازی دوره‌ای هارنس#

هر مؤلفهٔ هارنس به این دلیل وجود دارد که مدل نتوانسته است به‌تنهایی و به‌طور قابل‌اعتماد کاری را انجام دهد. اما با ارتقای مدل‌ها، این مفروضات کهنه می‌شوند.

گزارش هارنس Anthropic این را مستقیماً نشان می‌دهد. نخستین هارنس سه ایجنتی، که برای Opus 4.5 ساخته شده بود، تولیدکننده را در اسپرینت‌ها به کار می‌گرفت. با عرضهٔ Opus 4.6، مدل توانست تفکیک کارها را مدیریت کند، بنابراین ساختار اسپرینت غیرضروری شد. در اجرای به‌روزرسانی‌شدهٔ DAW، سازنده بیش از دو ساعت بدون انحراف به‌طور پیوسته کار کرد.

اما ارزیاب داستان متفاوتی داشت. حتی با توانمندی‌های قوی‌تر Opus 4.6، وقتی وظایف به مرز توانمندی مدل نزدیک می‌شدند، ارزیاب همچنان ارزش واقعی ارائه می‌کرد — و کارکردهای از قلم افتاده و پیاده‌سازی‌های صوری تولیدکننده را می‌گرفت. این بدان معناست که ارزیاب یک تصمیم صفر و یکی ثابت نیست؛ بلکه به نسبت سختی وظیفه با توانمندی مدل بستگی دارد.

تجربهٔ توصیه‌شده: هر ماه یک مؤلفهٔ هارنس را انتخاب کنید، آن را موقتاً غیرفعال نمایید، و وظایف بنچمارک را اجرا کنید. اگر نتایج افت نکرد، آن را برای همیشه حذف کنید. اگر افت کرد، آن را بازگردانید یا با گزینه‌ای سبک‌تر جایگزین سازید.

اصلی عمیق‌تر: با بهبود مدل‌ها، ترکیب‌های جذاب در یک هارنس کوچک نمی‌شوند — بلکه جابجا می‌گردند. مشکلاتی که قبلاً نیازمند راه‌حل‌های صریح بودند توسط توانمندی‌های مدل جذب می‌شوند، اما مرزهای توانمندی جدید فضاهایی از طراحی هارنس را می‌گشایند که قبلاً ناممکن بودند. وظیفهٔ مهندس هوش مصنوعی این است که پیوسته ترکیب ارزشمند بعدی را بیابد.

5. عملیات پاک‌سازی باید پادتوان باشد#

اسکریپت‌های پاک‌سازی باید برای اجرای مکرر ایمن باشند — یک‌بار دیگر اجرای آن‌ها نباید اثر جانبی به بار آورد:

# Idempotent cleanup operations
rm -f /tmp/debug-*.log  # -f ensures no error when files don't exist
git checkout -- .env.local  # Restore to known state
npm run test  # Verify cleanup didn't break anything

6. توان عملیاتی بالا فلسفهٔ ادغام را تغییر می‌دهد#

هنگامی که خروجی ایجنت بسیار فراتر از ظرفیت بازبینی انسان می‌رود، فلسفهٔ سنتی ادغام نیاز به تعدیل دارد. تجربهٔ تیم OpenAI: در محیطی که ایجنت روزانه 3.5 پول‌ریکوئست (PR) باز می‌کند (و بعداً حتی بیشتر)، به حداقل رساندن گیت‌های مسدودکنندهٔ ادغام تصمیمی درست است. PRها باید عمر کوتاهی داشته باشند؛ ناپایداری آزمون‌ها معمولاً با اجراهای بعدی حل می‌شود تا اینکه پیشرفت را به‌طور بی‌پایان مسدود کند. در سیستمی که هزینهٔ اصلاح پایین و هزینهٔ انتظار بالاست، حرکت سریع همراه با اصلاحات سریع راهبردی بهتر از تاییدهای کند است.

هشدار: این رویکرد در یک محیط با توان عملیاتی پایین غیرمسئولانه است. اما هنگامی که خروجی ایجنت به‌مراتب از توجه انسان فراتر می‌رود، اغلب بده‌بستان درستی محسوب می‌شود. معیار کلیدی: میانگین هزینهٔ رفع یک باگ در برابر میانگین هزینهٔ انتظار برای بازبینی PR توسط انسان. هنگامی که اولی کمتر از دومی باشد، ادغام سریع انتخاب درستی است.

موردی از دنیای واقعی#

یک برنامهٔ Electron که طی 12 هفته با ایجنت‌ها توسعه یافت، مقایسهٔ دو رویکرد:

بدون راهبرد پاک‌سازی (گروه کنترل): هفته 12، نرخ قبولی بیلد 68%، نرخ قبولی آزمون‌ها 61%، راه‌اندازی نشست جدید بیش از 60 دقیقه، و 103 مصنوع کهنه.

با راهبرد پاک‌سازی (گروه آزمایش): بررسی کامل وضعیت تمیز در پایان هر نشست، به‌علاوهٔ یک حلقهٔ پاک‌سازی هفتگی. هفته 12، نرخ قبولی بیلد 97%، نرخ قبولی آزمون‌ها 95%، راه‌اندازی نشست جدید 9 دقیقه، و 11 مصنوع کهنه.

تا هفته 12، نرخ‌های قبولی بیلد و آزمون گروه پاک‌سازی نزدیک به نقطهٔ آغازین باقی ماند، یک نشست جدید می‌توانست به‌سرعت آغاز به کار کند، و مصنوعات کهنه اندک بودند. پاک‌سازی چند دقیقه در هر نشست زمان برد و وضعیتی آغازین را بازگرداند که نشست بعدی می‌توانست به آن اعتماد کند.

نکات کلیدی#

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

منابع بیشتر#

• Clean Code - Robert C. Martin — اصول سیستماتیک تمیزی کد
• Harness Engineering - OpenAI — تکرارپذیری به‌عنوان یکی از الزامات اصلی طراحی هارنس
• Effective Harnesses - Anthropic — نقش حیاتی خروج‌های تمیز نشست‌ها در قابلیت اطمینان بلندمدت
• Programs, Life Cycles, and Laws of Software Evolution - Lehman — قوانین تکامل نرم‌افزار که اثبات می‌کنند پیچیدگی سیستم بدون نگهداری فعالانه به‌طور اجتناب‌ناپذیری رشد می‌کند

تمرین‌ها#

1. چک‌لیست وضعیت تمیز: یک چک‌لیست خروج از نشست برای پایگاه کد خود طراحی کنید که هر پنج بُعد را پوشش دهد. آن را در 5 نشست متوالی به کار بگیرید و تعداد تخلفات در هر بُعد را ثبت کنید.

2. مقایسهٔ بنچمارک: از یک مجموعه وظیفهٔ ثابت با دو گونهٔ مختلف هارنس (با/بدون الزامات وضعیت تمیز) استفاده کنید. نرخ تکمیل، تعداد تلاش‌های مجدد، و نرخ فرار نقص‌ها را مقایسه نمایید.

3. تمرین ساده‌سازی هارنس: یک مؤلفهٔ هارنس را انتخاب کنید، آن را موقتاً غیرفعال نمایید، و وظایف بنچمارک را اجرا کنید. نتایج را با و بدون آن مقایسه کنید. تصمیم بگیرید آیا آن را نگه دارید، حذف کنید، یا جایگزین نمایید.