درس 05. زنده نگه‌داشتن زمینه در طول نشست‌ها | مهندسی هارنس

Code examples: code/ Practice project: Project 03. Multi-session continuity

شما از کلود کد (Claude Code) می‌خواهید یک قابلیت کامل را پیاده‌سازی کند. 30 دقیقه اجرا می‌شود، بیشتر کار را پیش می‌برد، اما زمینه (context) رو به اتمام است. یک نشست جدید باز می‌کنید تا کار ادامه یابد — و متوجه می‌شوید به یاد نمی‌آورد دفعهٔ پیش چه تصمیماتی گرفته شده است، چرا گزینهٔ الف به‌جای گزینهٔ ب انتخاب شده، کدام فایل‌ها قبلاً ویرایش شده‌اند، یا وضعیت آزمون‌ها چگونه است. 15 دقیقه را صرف کاوش دوباره در پروژه می‌کند، و ممکن است رویکردی اتخاذ کند که با دفعهٔ پیش متناقض باشد.

این همان معضل واقعی است که ایجنت‌های (agent) کدنویسی هوش مصنوعی در وظایف چندنشستی با آن روبه‌رو می‌شوند. این درس توضیح می‌دهد که چرا ایجنت‌ها رشتهٔ کار را در وظایف طولانی گم می‌کنند، و چگونه پایدارسازی ساختاریافتهٔ وضعیت (state) به نشست جدید امکان می‌دهد به‌سرعت از همان‌جایی که نشست قبلی متوقف شد، کار را ادامه دهد.

پنجره‌های زمینه: نامحدود نیستند#

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

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

شرکت Anthropic در پژوهش‌های خود روی ایجنت‌های بلندمدت نکتهٔ جالبی را مشاهده کرد: وقتی ایجنت‌ها حس می‌کنند زمینه رو به پایان است، رفتار «پایان شتاب‌زده» از خود نشان می‌دهند — شتاب برای پایان دادن به کار جاری، رد کردن مراحل راستی‌آزمایی (verification)، یا انتخاب راه‌حلی ساده به‌جای راه‌حل بهینه. Anthropic این پدیده را «اضطراب زمینه» (context anxiety) می‌نامد.

جریان پیوستگی نشست#

بدون فایل‌های پایداری وضعیت، هر نشست جدید باید همه‌چیز را از صفر آغاز کند:

flowchart LR
    S1["Session 1<br/>feature is half done"] --> End1["Context is nearly full<br/>session ends"]
    End1 --> S2["Session 2 starts fresh"]
    S2 --> Guess["Re-read folders, rerun tests,<br/>guess why the code was written this way"]
    Guess --> Drift["Work gets repeated<br/>and recovery is slow"]

با وجود فایل‌های پایداری وضعیت، نشست‌های جدید می‌توانند به‌سرعت کار را در دست بگیرند:

flowchart LR
    Work["Session 1 work"] --> Progress["PROGRESS.md<br/>done / in progress / next step"]
    Work --> Decisions["DECISIONS.md<br/>why this approach was chosen"]
    Work --> Verify["Verification notes<br/>which tests pass and fail"]
    Work --> Commit["Git checkpoint<br/>exact repo state"]

    Progress --> Rebuild["Session 2 rebuild"]
    Decisions --> Rebuild
    Verify --> Rebuild
    Commit --> Rebuild

    Rebuild --> Resume["New session picks up quickly"]

مفاهیم اصلی#

پنجره‌های زمینه محدود هستند: صرف‌نظر از ادعایی که دربارهٔ اندازهٔ پنجره مطرح می‌شود (128 هزار، 200 هزار، یا 1 میلیون توکن)، وظایف طولانی در نهایت آن را به پایان می‌رسانند. پس از اتمام، یا فشرده‌سازی (از دست رفتن اطلاعات) لازم است یا بازنشانی (شروع نشستی تازه) — که هر دو با از دست رفتن مواردی همراه‌اند.
فایل‌های پایداری وضعیت: فایل‌های پایدار وضعیت که به نشستی تازه امکان می‌دهند بدون ابهام از همان‌جایی که نشست پیشین متوقف شده بود، کار را ادامه دهد. پایه‌ای‌ترین شکل شامل گزارش‌های پیشرفت، سوابق راستی‌آزمایی، و اقدامات بعدی است.
هزینهٔ بازسازی (Rebuild Cost): زمانی که نشستی تازه نیاز دارد تا به یک وضعیت قابل‌اجرا برسد. یک هارنس (harness) خوب، پیشرفت، نتایج راستی‌آزمایی، و گام‌های بعدی را در فایل‌ها باقی می‌گذارد تا نشست جدید از وضعیتی مکتوب آغاز شود.
انحراف (Drift): فاصلهٔ میان درک ایجنت و وضعیت واقعی مخزن کد. هر مرز نشست انحراف ایجاد می‌کند؛ بدون کنترل، این انحراف نشست‌به‌نشست انباشته می‌شود.
اضطراب زمینه (Context Anxiety): پدیده‌ای که توسط Anthropic مشاهده شده است — ایجنت‌ها هنگام نزدیک شدن به محدودهٔ زمینه، رفتار اتمام شتاب‌زده نشان می‌دهند و وظایف را پیش از موعد به پایان می‌رسانند تا از دست رفتن اطلاعات جلوگیری کنند. در اصل، این یک اضطراب غیرمنطقی دربارهٔ منابع است.
فشرده‌سازی در برابر بازنشانی: فشرده‌سازی، زمینه را در همان نشست خلاصه می‌کند («چیستی» را نگه می‌دارد، ممکن است «چرایی» را از دست بدهد)؛ بازنشانی، نشستی جدید باز کرده و آن را بر اساس مصنوعات پایدار بازسازی می‌کند (وضعیتی تمیز اما وابسته به کامل بودن مصنوعات).

چه اتفاقی می‌افتد وقتی پیوستگی قطع می‌شود#

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

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

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

همچنین شکاف راستی‌آزمایی وجود دارد. نتایج راستی‌آزمایی نشست پیشین (کدام آزمون‌ها پاس شدند، کدام رد شدند، چرا رد شدند) ثبت نشده‌اند. نشست جدید مجبور است تمام راستی‌آزمایی را از نو اجرا کند تا وضعیت کنونی را بفهمد. هر نشست از صفر عیب‌یابی می‌کند، و هر بار زمینهٔ ارزشمند هدر می‌رود.

هم OpenAI و هم Anthropic در مستندات خود بر پایداری ساختاریافتهٔ وضعیت تأکید می‌کنند. مقالهٔ مهندسی هارنس OpenAI مخزن را به‌عنوان «سوابق عملیاتی» در نظر می‌گیرد — نتایج هر عملیات باید شواهدی قابل‌ردگیری در مخزن به جا بگذارد. مستندات ایجنت‌های بلندمدت Anthropic به‌ویژه «فایل‌های تحویل (handoff files)» را توصیه می‌کند — اسنادی ساختاریافته شامل وضعیت کنونی، مشکلات شناخته‌شده، و اقدامات بعدی.

رویکردهای عملی برای پایداری وضعیت#

رویکرد اصلی: با ایجنت مانند مهندسی رفتار کنید که حافظهٔ کوتاه‌مدتش در هر نشست پاک می‌شود. پیش از آنکه «کارت خروج بزند»، باید اطلاعات حیاتی را مکتوب کند تا ایجنت «شیفت بعدی» بتواند کار را به‌سرعت ادامه دهد.

ابزار 1: فایل پیشرفت (PROGRESS.md). پایه‌ای‌ترین فایل پایداری وضعیت:

# Project Progress

## Current State
- Latest commit: abc1234 (feat: add user preferences endpoint)
- Test status: 42/43 passing (test_pagination_edge_case failing)
- Lint: passing

## Completed
- [x] User model and database migration
- [x] Basic CRUD endpoints
- [x] Auth middleware integration

## In Progress
- [ ] Pagination feature (90% - edge case test failing)

## Known Issues
- test_pagination_edge_case returns 500 on empty result sets
- Need to confirm whether deleted users should appear in listings

## Next Steps
1. Fix pagination edge case bug
2. Add "include deleted users" query parameter
3. Update API documentation

ابزار 2: گزارش تصمیمات (DECISIONS.md). تصمیمات مهم طراحی و دلایل آن‌ها را ثبت کنید. نیازی به اسناد تفصیلی طراحی نیست — فقط «چه تصمیمی، چرا، چه زمانی»:

# Design Decisions

## 2024-01-15: Use Redis for user preferences caching
- Reason: High read frequency (every API call), small data size
- Rejected alternative: PostgreSQL materialized view (high change frequency makes maintenance cost not worthwhile)
- Constraint: Cache TTL of 5 minutes, active invalidation on write

ابزار 3: کامیت‌های گیت به‌عنوان نقاط بررسی (checkpoints). پس از تکمیل هر واحد اتمام‌پذیر کار، کامیت کنید. پیام‌های کامیت باید توضیح دهند چه کاری انجام شده و چرا. این‌ها عکس‌های لحظه‌ای از وضعیت، به‌صورت رایگان و با نسخه‌بندی خودکار هستند.

ابزار 4: فایل init.sh یا جریان مقداردهی اولیهٔ هارنس. در فایل AGENTS.md روال‌های «ورود به شیفت» و «خروج از شیفت» را مشخص کنید:

## At session start (clock in)
1. Read PROGRESS.md for current state
2. Read DECISIONS.md for important decisions
3. Run make check to confirm repo is in consistent state
4. Continue from PROGRESS.md "Next Steps" section

## Before session end (clock out)
1. Update PROGRESS.md
2. Run make check to confirm consistent state
3. Commit all completed work

راهبرد ترکیبی: همهٔ وظایف نیاز به بازنشانی زمینه ندارند. کارهای کوتاه (زیر 30 دقیقه) می‌توانند در یک نشست کامل شوند. کارهای طولانی (در طول چند نشست) باید از فایل‌های پیشرفت و گزارش تصمیمات برای حفظ پیوستگی بهره ببرند. معیار تصمیم‌گیری: اگر وظیفه‌ای بیش از 60% از پنجره را نیاز دارد، آماده‌سازی برای تحویل (handoff) را آغاز کنید.

نگاهی دقیق‌تر به اضطراب زمینه#

پژوهش مارس 2026 شرکت Anthropic نشانه‌های مشخص اضطراب زمینه را بیشتر آشکار ساخت: در مدل Sonnet 4.5، وقتی زمینه به محدودهٔ پنجره نزدیک می‌شود، ایجنت رفتار شدید «اتمام شتاب‌زده» از خود نشان می‌دهد.

دو راهبرد به این موضوع می‌پردازند:

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

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

داده‌های واقعی Anthropic: برای Sonnet 4.5، اضطراب زمینه به اندازه‌ای شدید است که فشرده‌سازی به‌تنهایی کافی نیست — بازنشانی زمینه به مؤلفه‌ای حیاتی در طراحی هارنس تبدیل می‌شود. اما برای Opus 4.5، این رفتار بسیار کاهش یافته است و فشرده‌سازی می‌تواند بدون اتکا به بازنشانی، زمینه را مدیریت کند. این بدان معناست: طراحی هارنس نیازمند درک اختصاصی از مدل هدف است، نه یک قالب یکسان برای همه.

منبع: Anthropic: Harness design for long-running application development

رویکرد Anthropic: تحویل در طول نشست‌های کدنویسی#

شرکت Anthropic نمونه‌ای از شبیه‌سازی وب‌سایت کلود را شرح می‌دهد که در آن مقداردهی اولیه، مشخصات را به بیش از 200 قابلیت گسترش داد که در ابتدا همگی به‌صورت ناموفق علامت‌گذاری شده بودند. مقداردهی اولیه همچنین یک فایل init.sh، یک فایل پیشرفت، و کامیت اولیهٔ گیت را ایجاد کرد. نشست‌های کدنویسی بعدی، فایل پیشرفت و تاریخچهٔ گیت را خواندند، به‌صورت تدریجی روی قابلیت‌ها کار کردند، رفتارها را راستی‌آزمایی نمودند، و به‌روزرسانی‌ها را برای نشست بعدی باقی گذاشتند.

این مورد یک سازوکار پیوستگی را مستند می‌کند؛ درصد تکمیل قابلیت‌ها، نقص‌های پنهان، یا درصد بازسازی زمینه که قبلاً در اینجا نشان داده شده بود را گزارش نمی‌دهد. کد همراه آن یک شبیه‌سازی آموزشی است، نه سنجش عملکرد مدل.

Anthropic

شرکت LangChain یک بهبود واقعی هارنس را با استفاده از همان مدل gpt-5.2-codex روی Terminal Bench 2.0 (یک بنچمارک با 89 وظیفه) گزارش می‌دهد: امتیاز از 52.8% به 66.5% رسید، که افزایشی معادل 13.7 واحد درصد است. تغییرات شامل هدایت راستی‌آزمایی، میان‌افزار، و مدیریت زمینه بود. این نتیجه حاصل چندین تغییر هم‌زمان در هارنس است، نه مزیتی اندازه‌گیری‌شده صرفاً برای فایل‌های پیشرفت. LangChain: Improving Deep Agents

نکات کلیدی#

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

منابع بیشتر#

تمرین‌ها#

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