هنگام کار با ابزارهای کدنویسی مبتنی بر مدل‌های زبانی بزرگ، محدودیت طول پنجره‌ی بافتار (context window) و هزینهی توکن‌ها مانع از آن میشود که یک تسک طولانی را در یک نشست واحد به سرانجام برسانید. اغلب پس از پایان یک نشست، نشست بعدی بدون اطلاع دقیق از مراحل قبل آغاز میشود و ایجنت جدید دقایق زیادی را صرف کشف دوباره‌ی تغییرات، بازآزمایی‌ها و پرسش‌های تکراری از کاربر میکند.
این درس به شما می‌آموزد که چگونه به جای تکیه بر خلاصه‌سازی‌های بی‌کیفیت یا یادداشت‌های دستیِ ناپایدار، یک «بستهی تحویل کار» (handoff packet) خودکار و ساختاریافته در قالب Markdown و JSON بسازید. این بسته از دستسازههای موجود روی میزکار تولید میشود و تضمین میکند که نشست بعدی از نخستین ثانیه، کار خود را با اقدامی معین و بدون گیجی شروع کند.
این نشست کاری به پایان می‌رسد، اما کار نه. «بستهی تحویل کار» (handoff packet) همان دست‌سازه‌ای است که «ایجنت یک ساعت کار کرد» را به «نشست بعدی از همان دقیقه‌ی اول پربازده است» تبدیل میکند. آن را آگاهانه بسازید، نه از سر رفع تکلیف در لحظه‌ی آخر.
اهداف یادگیری
- هفت فیلد ضروری هر بستهی تحویل کار را بشناسید.
- بدون متن‌نویسی دستی، بستهی تحویل را از روی دستسازههای میزکار بسازید.
- لاگ‌های مفصل بازخورد را تا حد خلاصه‌ای مناسب برای بستهی تحویل کوتاه کنید.
- اولین اقدام نشست بعدی را قطعی و پیش‌بینی‌پذیر کنید.
مسئله
نشست تمام میشود. ایجنت می‌گوید: «عالی بود، پیشرفت کردیم.» نشست بعدی باز میشود. ایجنت بعدی می‌پرسد: «کجا بودیم؟» پاسخ ایجنت اول دیگر در دسترس نیست. ایجنت بعدی دوباره همه‌چیز را از اول بررسی میکند، همان دستورها را از نو اجرا میکند، همان پرسش‌ها را تکراری از انسان می‌پرسد و 30 دقیقه وقت می‌سوزاند تا 30 ثانیه‌ی پایانی نشست قبل را بازسازی کند.
تاوان یک تحویلِ بد را در تک‌تک نشست‌های طول عمر آن تسک می‌پردازید. راه‌حل، بسته‌ای است که در پایان هر نشست خودکار تولید شود: چه چیزی تغییر کرد، چرا، چه کارهایی امتحان شد، چه تلاش‌هایی به بن‌بست خورد، چه مواردی باقی مانده و دفعه‌ی بعد دقیقاً از چه کاری باید شروع کرد.
مفهوم
هفت فیلد ضروری در هر بستهی تحویل کار
| فیلد | پاسخی به این پرسش |
|---|---|
summary |
یک پاراگراف از کارهای انجام‌شده |
changed_files |
نگاهی گذرا به تغییرات (diff) |
commands_run |
دستورهایی که در عمل اجرا شدند |
failed_attempts |
تلاشهای انجام‌شده و دلیل کار نکردن آن‌ها |
open_risks |
مسائلی که ممکن است در نشست بعدی دردسرساز شوند، به همراه میزان ریسک |
next_action |
نخستین گام ملموس نشست بعدی |
verdict_pointer |
مسیر منتهی به گزارش‌های ارزیابی صحت و بازبینی |
فیلد next_action ستون اصلی این بسته است. بستهی تحویلی که همه‌چیز داشته باشد جز next_action، صرفاً یک گزارش وضعیت است، نه بستهی تحویل کار.
بسته‌های تحویل تولید می‌شوند، نه نوشته
بستهی تحویل دست‌نویس همان چیزی است که در روزهای سخت و پرمشغله جا می‌افتد. ابزار تولیدکننده، دستسازههای میزکار را می‌خواند و بسته را صادر میکند. وظیفه‌ی ایجنت این است که میزکار را در وضعیتی مرتب تحویل دهد تا تولیدکننده بتواند آن را خلاصه کند، نه اینکه خودش دستی خلاصه بنویسد.
دو ساختار: خوانا برای انسان و خوانا برای ماشین
فایل handoff.md متنی است که انسان می‌خواند؛ handoff.json ساختاری است که ایجنت بعدی بارگذاری میکند. هر دو از یک منبع مشترکِ دست‌سازه‌ها تولید می‌شوند. اگر اختلافی بین این دو باشد، اولویت با JSON است.
خلاصهسازی لاگ بازخورد
فایل کامل feedback_record.jsonl ممکن است صدها رکورد داشته باشد. بستهی تحویل فقط K ورودی آخر به‌همراه تمام مواردی را نگه می‌دارد که با خروجی غیرصفر (non-zero exit) تمام شده‌اند. نشست بعدی اگر نیاز داشت کل لاگ را بارگذاری میکند، اما حجم خودِ بسته همیشه جمع‌وجور می‌ماند.
برجا گذاشتن یک وضعیت پاکیزه
بستهی تحویل، کار انجام‌شده را توصیف میکند؛ وضعیت پاکیزه، ادامه‌پذیری کار را ممکن می‌سازد. این دو یکی نیستند. یک فایل handoff.md بی‌نقص هیچ فایده‌ای ندارد اگر نشست بعدی کارش را با یک diff نیمه‌اعمال‌شده، یک فایل موقتِ فراموش‌شده، یک branch سرگردان و تست‌هایی شروع کند که حتی قبل از اجرا خطا می‌دهند. در چنین وضعیتی، ایجنت بعدی به جای ساختن، باید ده دقیقه‌ی اولش را صرف جمع‌کردن خرابکاری‌های ایجنت قبلی کند؛ هزینه‌ای که نشست به نشست در تمام طول تسک روی هم تلنبار میشود.
پس نشست وقتی تمام نمی‌شود که قابلیت جدید کار کرد؛ پایان واقعی زمانی است که میزکار در وضعیتی باشد که تولیدکننده بتواند آن را خلاصه کند و نشست بعدی بتواند به آن اطمینان داشته باشد. پاکیزه‌سازی مرحله‌ای مستقل است که پیش از تحویل کار اجرا میشود. این مرحله یک ارزیابی ساختاریافته است نه یک عادت، چون عادت همان چیزی است که در روزهای پرفشار کنار گذاشته میشود.
| بررسی | معنای پاکیزه بودن | دلیل مسدودکننده بودن وضعیت ناپاک |
|---|---|---|
| درخت کاری (Working tree) | هر تغییری commit شده یا با یادداشت مشخص stash شده باشد | diff نیمه‌کاره از نظر ایجنت بعدی شبیه کارهای اصلی و عمدی جلوه میکند |
| دستسازههای موقت | هیچ فایل *.tmp، پوشه‌ی موقت، چاپ دیباگ یا بلوک کامنت‌شده‌ای جا نمانده باشد |
فایلهای سرگردان، diff و تصویر ذهنی ایجنت بعدی را مخدوش می‌کنند |
| تست‌ها | سبز باشند، یا در صورت قرمز بودن نام نقص در open_risks آمده باشد |
تست قرمزی که درباره‌اش نگفته باشند، تله‌ای است که نشست بعدی در آن می‌افتد |
| تابلوی قابلیت‌ها (Feature board) | وضعیت feature_list.json بازتاب‌دهنده‌ی واقعیت باشد (فاز 14 · 36) |
تابلوی به‌روزرنشده ایجنت بعدی را سراغ کاری می‌فرستد که قبلاً انجام شده است |
| شاخه (Branch) | روی branch مورد انتظار باشد، بدون detached HEAD یا branchهای رهاشده | شاخه‌ی نادرست باعث میشود نخستین commit نشست بعدی در جای اشتباهی بنشیند |
مرحله‌ی پاکیزه‌سازی، یک فایل clean_state.json از موانع کار تولید میکند؛ خالی بودن این فهرست پیش‌شرطی است که ابزار تولید بستهی تحویل قبل از نوشتن بسته بررسی میکند. بسته‌ای که روی یک درخت کاری نامرتب ساخته شود، بستهی تحویل نیست؛ صرفاً پاس دادن آشفتگی به نفر بعدی است. این دو دست‌سازه مکمل هم هستند: پاکیزه‌سازی ثابت میکند می‌توان با خیال راحت میزکار را ترک کرد؛ بستهی تحویل ثابت میکند نشست بعدی می‌داند کار را از کجا شروع کند.
ساخت ابزار
اسکریپت code/main.py این موارد را پیاده‌سازی میکند:
- یک بارگذار که وضعیت، ارزیابی نهایی، بازبینی و بازخورد را در یک
WorkbenchSnapshotواحد گرد می‌آورد. - تابع
generate_handoff(snapshot) -> (markdown, payload). - فیلتری که K ورودی آخر بازخورد را به همراه همه‌ی خروجی‌های غیرصفر جدا میکند.
- یک اجرای نمونه که
handoff.mdوhandoff.jsonرا در کنار اسکریپت ذخیره میکند.
اجرای آن:
python3 code/main.pyخروجی: نمایش متن بستهی تحویل در خروجی استاندارد، به‌همراه ذخیره‌ی هر دو فایل روی دیسک.
الگوهای محیط عملیاتی
ابزارهای Codex CLI، Claude Code و OpenCode هر کدام رویکرد متفاوتی برای فشردهسازی بافتار پیش گرفته‌اند؛ اما بستهی ساختاریافته‌ی تحویل کار روی هر سه سوار میشود.
استراتژی‌های فشردهسازی بافتار متفاوت‌اند، اما ساختار بستهی تحویل یکی است. در Codex CLI، اندپوینت سروری POST /v1/responses/compact یک blob ماتِ رمزنگاری‌شده با AES است (مسیر سریع برای مدل‌های OpenAI)؛ مسیر جایگزین آن، یک «خلاصه‌ی تحویل» محلی است که به عنوان پیام کاربر با نقش _summary پیوست میشود. Claude Code در 95% پرشدن بافتار، یک فشردهسازی گام‌به‌گامِ پنج‌مرحله‌ای اجرا میکند. OpenCode هم پنهان‌سازی پیام‌ها بر اساس زمان‌بندی را با یک خلاصه‌ی پنج‌بخشی مدل ترکیب میکند. سه سازوکار متفاوت با هدفی یکسان: منظم کردن داده‌هایی که پس از فشردهسازی حفظ می‌شوند در قالب یک دست‌سازه‌ی قابل‌حمل. این بسته دقیقاً همان دست‌سازه است.
تحویل کار به نشست تازه، فشردهسازی بافتار نیست. فشردهسازی عمر یک نشست را طولانیتر میکند؛ تحویل کار پرونده‌ی یک نشست را تمیز میبندد و کار را در نشستی نو پی می‌گیرد. دیدگاه Issue شماره‌ی 20372 پروژه‌ی Hermes (آوریل 2026) کاملاً دقیق است: وقتی فشردهسازی درجا افت کیفیت پیدا میکند، ایجنت باید یک بستهی فشرده تحویل بنویسد، نشست را ببندد و کار را در یک بافتار تازه پی بگیرد. این بسته همان ابزاری است که هزینهی این جابه‌جایی را ناچیز میکند. اشتباه رایج این است که آن‌قدر فشردهسازی را ادامه دهید تا کیفیت کاملاً به هم بریزد؛ راه درست این است که از قبل برای تحویلی به‌موقع و تمیز برنامه‌ریزی کنید.
یک بستهی تحویل فعال به ازای هر branch و موضوع. هماهنگی چند ایجنت، بیش از آنکه از خروجی‌های نامناسب مدل ضربه بخورد، از بسته‌های تحویل تاریخ‌گذشته آسیب می‌بیند. همیشه branch، مقدار last_known_good_commit و وضعیتی شامل active | superseded | archived را در بسته بگنجانید. بسته‌های قدیمی بایگانی می‌شوند و فقط بستهی فعال مبنای نشست بعدی قرار می‌گیرد. تفاوت میان «تحویل مثل یادداشت» و «تحویل مثل وضعیت سیستم» در همین نکته است.
پیش از پر شدن 50 تا 75 درصد بافتار کار را جمع کنید، نه پای دیوار 100 درصد. الگوهای تجربی مبتنی بر مستندات دستی (CLAUDE.md + HANDOVER.md) نشان می‌دهند که بهترین نتیجه زمانی به دست می‌آید که نشست به‌جای 95%، در 50 تا 75 درصد بودجه‌ی بافتار بسته شود. ابزار تولید بسته پیش از آنکه خرابکاری‌های ناشی از فشردهسازی بافتار وضعیت اصلی را آلوده کنند، خروجی تمیزی میدهد. تولید بسته وقتی بافتار هنوز آسیب ندیده ارزان است، اما وقتی مدل کنترل اوضاع را از دست داده، به‌شدت گران تمام میشود.
کاربرد در عمل
الگوهای محیط عملیاتی:
- قلاب پایان نشست (Session-end hook): با بستن چت توسط کاربر، محیط اجرا ابزار تولیدکننده را فراخوانی میکند. بسته در مسیر
outputs/handoff/<session_id>/ذخیره میشود. - الگوی پول‌ریکوئست (PR template): خروجی markdown تولیدکننده مستقیماً متن توضیحات PR میشود. بازبین‌ها بدون نیاز به باز کردن پنج فایل دیگر، از همه‌چیز سر درمی‌آورند.
- تحویل میان دو ایجنت مختلف: کار را با یک ابزار (مثلاً Claude Code) بسازید و با ابزاری دیگر (مثلاً Codex) ادامه دهید. این بسته نقش زبان مشترک را بازی میکند.
این بسته کم‌حجم، منظم و کم‌هزینه است و سود حاصل از صرفه‌جویی آن در طول زمان و در هر نشست روی هم انباشته میشود.
تحویل نهایی
فایل outputs/skill-handoff-generator.md ابزاری برای تولید بستهی تحویل متناسب با مسیر دستسازههای پروژه‌ی شما، یک قلاب پایان نشست برای اجرای آن و ساختار handoff.json برای بارگذاری توسط ایجنت بعدی در ابتدای کار را تحویل میدهد.
تمرین‌ها
- فیلد
assumptions_to_validateرا اضافه کنید تا تمام فرض‌هایی را که سازنده ثبت کرده اما بازبین نمره‌ای بالاتر از 1 به آن‌ها نداده است نشان دهد. - خلاصهسازی بازخورد را برای اجراهای ناموفق متفاوت از اجراهای موفق بنویسید. از این عدم تقارن دفاع کنید.
- فهرست «پرسش‌هایی برای انسان» را اضافه کنید. آستانه‌ی تصمیم‌گیری برای اینکه یک پرسش وارد بستهی تحویل شود یا در قالب پیام چت فرستاده شود چیست؟
- ابزار تولیدکننده را «پایاپای» (idempotent) کنید: به گونه‌ای که دو بار اجرای پشت سر هم، همان بستهی قبلی را بسازد. چه مواردی باید بدون تغییر بمانند تا این ویژگی حفظ شود؟
- بخش «پیش‌نیازهای نشست بعدی» را بیفزایید که دقیقاً دست‌سازه‌هایی را که نشست بعدی باید پیش از هر کاری بارگذاری کند، فهرست کند.
اصطلاحات کلیدی
| اصطلاح | در گفت‌وگوها | معنای دقیق فنی |
|---|---|---|
| بستهی تحویل کار (Handoff packet) | «خلاصه‌ی نشست» | دست‌سازه‌ای تولیدشده شامل هفت فیلد، در دو قالب markdown و JSON |
| اقدام بعدی (Next action) | «قدم اول» | تنها گام ملموسی که شروع نشست بعدی بر پایه‌ی آن شکل می‌گیرد |
| خلاصهسازی بازخورد (Feedback trim) | «خلاصه‌ی لاگ» | K رکورد آخر به همراه همه‌ی مواردی که با خروجی غیرصفر تمام شده‌اند |
| گزارش وضعیت (Status report) | «کارهایی که کردیم» | سندی که فاقد فیلد next_action است؛ خواندنی است، اما بستهی تحویل کار نیست |
| اشارهگر ارزیابی نهایی (Verdict pointer) | «رسید کار» | مسیری به گزارش‌های ارزیابی صحت و بازبینی جهت ردگیری محاسبات |
مطالعه‌ی بیشتر
- Anthropic, Effective harnesses for long-running agents
- OpenAI Agents SDK handoffs
- Codex Blog, Codex CLI Context Compaction: Architecture, Configuration, Managing Long Sessions — اندپوینت POST /v1/responses/compact و گزینه‌ی محلی
- Justin3go, Shedding Heavy Memories: Context Compaction in Codex, Claude Code, OpenCode — مقایسه‌ی فشردهسازی بافتار در سه ارائه‌دهنده
- JD Hodges, Claude Handoff Prompt: How to Keep Context Across Sessions (2026) — شیوه‌ی CLAUDE.md + HANDOVER.md و بودجه‌ی 50 تا 75 درصدی بافتار
- Mervin Praison, Managing Handoffs in Multi-Agent Coding Sessions: Fresh Context Without Losing Continuity — چارچوب‌بندی بر مبنای سیستم‌های توزیع‌شده
- Hermes Issue #20372 — automatic fresh-session handoff when compression becomes risky
- Hermes Issue #499 — Context Compaction Quality Overhaul — پرامپت‌های تحویل‌محور در Codex CLI
- Microsoft Agent Framework, Compaction
- OpenCode, Context Management and Compaction
- LangChain, Context Engineering for Agents
- فاز 14 · 34 — فایل وضعیتی که تولیدکننده می‌خواند
- فاز 14 · 38 — حکم ارزیابی صحتی که بسته به آن اشاره دارد
- فاز 14 · 39 — گزارش بازبینی که درون بسته گنجانده میشود