کاهش هزینه و سرعت Claude Code
با استفاده از دستور /context در Claude Code، حجم Context را مدیریت کنید تا از کندی جلسات طولانی و افزایش هزینهی ارسال مجدد توکنها جلوگیری شود.
چگونه از کند شدن و پرهزینه شدن جلسات طولانی Claude Code جلوگیری کنیم
جلسات طولانی Claude Code کند و پرهزینه میشوند، زیرا در هر مرحله تمام Context مجدداً ارسال میشود و این Context مدام در حال افزایش است. راه حل، رعایت بهداشت (hygiene) با ترتیب مشخص است. ابتدا دستور /context را اجرا کنید تا ببینید چه مواردی باعث پر شدن پنجره شده است؛ سپس مواردی که هزینه هر درخواست را افزایش میدهند، حذف کنید. سپس در فاصله بین وظایف بیارتباط از /clear و در حین یک وظیفه طولانی با استفاده از یک دستور از /compact استفاده کنید. در بازههای زمانی مداوم کار کنید، زیرا یک Prompt Cache سرد، یک خواندن ارزان را به بازنویسی کامل تمام گفتههای شما تبدیل میکند.
دلیل اصلی فعال شدن شمارنده در شمارنده توکن در پشت یک جلسه Agent توضیح داده شده است.
قبل از هرگونه تغییر، /context را بخوانید
از محتوای داخل پنجره حدس نزنید. Claude Code آن را به شما میگوید.
/context [all] میزان استفاده از context فعلی را به صورت یک شبکه رنگی نمایش میدهد و پیشنهادات بهینهسازی برای ابزارهای پرحجم و مصرف بیش از حد حافظه را ارائه میدهد؛ all جزئیات هر آیتم را در حالت fullscreen نمایش میدهد. نتیجه را در قالب پنج دسته بخوانید.
- The system prompt. دستورالعملهای چارچوب Claude Code. در طول session ثابت است.
- Tool definitions. طرحواره (schema) برای تمام ابزارهایی که agent میتواند فراخوانی کند، شامل تمام سرورهای MCP (Model Context Protocol) متصل شده.
- Memory files. فایلهای
CLAUDE.mdو حافظه خودکار (auto memory) که در شروع session بارگذاری میشوند. - Files and tool results. تمام فایلهای خوانده شده و هر آنچه دستورات شما چاپ کردهاند.
- Message history. پیامهای شما و پاسخهای آن.
سه مورد اول، هزینهای ثابت هستند که در هر درخواست در طول session پرداخت میشود. دو مورد آخر افزایش مییابند. هزینهی ثابت را یکبار در شروع کار کاهش دهید؛ بخش در حال رشد را به صورت مداوم مدیریت کنید.
دو رشته متن نشان میدهند که پنجره پر شده است:
Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.اولی یک محدودیت سختگیرانه است و درخواست رد میشود؛ خطای API مربوطه Prompt is too long است. دومی یک پنجره فشردهسازی (compaction window) است که در یک مدل با 1 million توکن، میتواند کمتر از پنجره context واقعی مدل باشد. درخواستها حتی پس از آن هم با موفقیت انجام میشوند، بنابراین آن مورد بیشتر یک هشدار است تا رد درخواست.
در طرحهای پولی، /usage نیمه دیگر را اضافه میکند و رفتارهایی مانند context طولانی یا cache misses را علامتگذاری کرده و استفاده اخیر را به مهارتها، subagents و سرورهای MCP اختصاص میدهد.
CLAUDE.md یک هزینه دائمی است، پس آن را سبک نگه دارید
CLAUDE.md شما در شروع session بارگذاری شده و در آن باقی میماند. اگر این فایل شامل یک دستورالعمل دقیق استقرار (deployment) باشد، آن توکنها حتی هنگام اصلاح یک غلط تایپی در یک فایل تست، در context حضور دارند. راهنمای Anthropic پیشنهاد میکند فقط موارد ضروری را لحاظ کنید و حجم فایل را زیر 200 خط نگه دارید.
دستورالعملها را به skills منتقل کنید. یک skill تنها هنگام فراخوانی بارگذاری میشود؛ بنابراین گردش کاری که هفتهای 2 بار آن را اجرا میکنید، در روزهای دیگر هیچ هزینهای ندارد. skills پس از یک عملیات compaction بودجه مخصوص به خود را دارند: محتوا دوباره تزریق میشود، سقف هر skill برابر با 5,000 توکن و سقف کل 25,000 توکن است و قدیمیترین موارد ابتدا حذف میشوند. عملیات truncation بخش ابتدایی فایل را حفظ میکند، پس مهمترین دستورالعملها را در ابتدای SKILL.md قرار دهید.
آنچه از یک compaction باقی میماند، تعیین میکند که یک دستورالعمل باید کجا قرار بگیرد.
- system prompt و سبک خروجی تغییر نمیکنند، زیرا بخشی از تاریخچه پیامها (message history) نیستند.
- فایل
CLAUDE.mdدر project-root، قوانین بدون محدوده (unscoped rules) و auto memory از روی دیسک دوباره تزریق میشوند. - قانونی که دارای frontmatter از نوع
paths:باشد، تا زمانی که فایل مشابه دوباره خوانده نشود، از دست میرود. - یک
CLAUDE.mdتو در یک زیردایرکتوری، تا زمانی که فایلی در آن زیردایرکتوری دوباره خوانده نشود، از دست میرود. - hooks بدون تغییر باقی میمانند، زیرا یک hook به عنوان کد اجرا میشود و هرگز وارد context نمیشود.
بنابراین قانونی که به آن وابسته هستید، باید در CLAUDE.md در project-root باشد: Claude Code ابتدا خروجیهای قدیمیتر ابزارها را پاک میکند و سپس خلاصهسازی میکند، بنابراین ممکن است دستورالعملهای ابتدای گفتگو از دست بروند. حافظه را با /memory ویرایش کنید. Claude Code نسخهای را که در شروع session بارگذاری کرده نگه میدارد، بنابراین یک trim در میان session، prompt cache را حفظ میکند و تا /clear، /compact یا restart بعدی اعمال نمیشود.
/clear بین وظایف، /compact در داخل یک وظیفه
این دو دستور مشابه به نظر میرسند اما هزینه آنها بسیار متفاوت است.
/clear [name] یک گفتگو را با context خالی شروع میکند. این دستور هیچ درخواستی ارسال نمیکند، بنابراین هزینهای ندارد. یک نام را برای برچسبگذاری گفتگوی قبلی در انتخابگر /resume ارسال کنید؛ /reset و /new نامهای مستعار هستند. بلافاصله پس از تغییر به یک وظیفه بیارتباط از آن استفاده کنید، زیرا در غیر این صورت، وظیفه قدیمی در هر پیام از وظیفه جدید، دوباره ارسال و دوباره هزینه خواهد داشت.
/compact [instructions] با ادامه دادن همان گفتگو، context را آزاد میکند: این دستور تاریخچه تا این لحظه را خلاصه کرده و جایگزین آن میکند. از آن در داخل یک وظیفه طولانی که همچنان به تداوم نیاز دارید، استفاده کنید.
همیشه به /compact یک دستور بدهید. یک دستور /compact خالی، بر اساس یک prompt پیشفرض خلاصه میکند که نمیداند شما هنوز به کدام بخش از کار نیاز دارید. یک دستور داده شده، آن بخش را حفظ میکند:
/compact focus on the auth bug fix
/compact keep only the plan and the diffاگر هر بار به یک دلیل مشابه نیاز به compact کردن دارید، یک دستور ثابت در CLAUDE.md پروژه خود تحت یک heading از نوع # Compact instructions قرار دهید. در یک session جدید، /compact عبارت Not enough messages to compact. را چاپ میکند که فقط به معنای نبود تاریخچه است.
در اینجا دو نوع هزینه با هم اشتباه گرفته میشوند. درخواست خلاصهسازی از prefix شما استفاده میکند، بنابراین به جای پردازش مجدد تاریخچه، از cache موجود میخواند و بیشتر زمان آن صرف تولید خلاصه میشود. compact کردن یک context بزرگ همچنان یک درخواست بزرگ است، زیرا گفتگویی که خلاصه میشود، ورودی (input) است. مرحله بعد از compaction بخش کند نیست: این مرحله cache را برای یک prompt بسیار کوتاهتر بازسازی میکند.
دو دستور ارزانتر وجود دارد. /rewind [description] کد و گفتگو را به یک checkpoint باز میگرداند؛ برای مسیری که میخواهید کاملاً رها کنید، این دستور از compact کردن بهتر است، زیرا به یک prefix که قبلاً cache شده است، باز میگردد. /recap یک خلاصه را به عنوان خروجی دستور اضافه میکند، به جای اینکه تاریخچه را جایگزین کند، بنابراین prefix ذخیره شده دستنخورده باقی میماند.
اجرای خودکار و مکرر compaction این عبارت را چاپ میکند:
Autocompact is thrashing: the context refilled to the limit...Compaction با موفقیت انجام شد، اما خروجی یک فایل یا ابزار چندین بار متوالی پنجره را پر کرد، بنابراین Claude Code از تلاش مجدد دست کشید. برای بازیابی، فایل حجیم را در بازههای خطی (line ranges) بخوانید، از /compact با تمرکزی که خروجی بزرگ را حذف میکند استفاده کنید، آن کار را به یک subagent منتقل کنید، یا اگر گفتگوی قبلی تمام شده است، از /clear استفاده کنید.
سرورهای MCP دارای سربار ثابت هستند
هر سرور MCP که متصل میکنید، به تمام درخواستها در طول یک session اضافه میشود. هزینه این اتصال، چه از آن استفاده کنید و چه نکنید، پرداخت میشود.
Claude Code این مسئله را کاهش میدهد. تعاریف ابزارهای MCP به صورت پیشفرض به تعویق میافتند (deferred)، بنابراین تا زمانی که Claude از یک ابزار خاص استفاده نکند، فقط نام ابزارها وارد context میشود. برای مشاهده هزینه واقعی سرورهای خود از /context و برای حذف سروری که امروز از آن استفاده نمیکنید از /mcp disable <name> استفاده کنید. اگر your own MCP servers on a VPS را اجرا میکنید، همین محاسبات محدودیت تعداد ابزارهایی که یک سرور باید ارائه دهد را تعیین میکند.
این کار را در شروع یک session انجام دهید. تا زمانی که تعاریف در حالت deferred باقی بمانند، متصل یا قطع کردن یک سرور فقط به گفتگو اضافه میشود و cache حفظ میشود. اما در جاهایی که تعاریف در prefix بارگذاری میشوند (به دلیل خاموش بودن جستجوی ابزار یا معاف بودن سرور از حالت deferral)، همین تغییر باعث میشود درخواست بعدی تمام موارد را دوباره بخواند.
فیلتر کردن خروجی پرجزئیات ابزار پیش از ورود به context
نتیجه یک ابزار به عنوان input در نظر گرفته میشود و این input در هر مرحله (turn) بعدی دوباره ارسال میگردد. یک اجرای تست که 20,000 token خروجی تولید میکند، هزینه یکباره نیست: شما در هر مرحله تا زمانی که آن خروجی از محدوده window خارج نشود، دوباره هزینه آن را پرداخت میکنید.
فیلتر کردن را در منبع انجام دهید. یک hook که خروجی یک اجرای تست را فقط به موارد شکستخورده (failures) محدود میکند، آن حجم عظیم خروجی را به چند صد token تبدیل میکند؛ هم در این مرحله و هم در هر بار ارسال مجدد آن:
npm test 2>&1 | grep -E "FAIL|Error:" | head -40Hookها هرگز خودشان وارد context نمیشوند، زیرا به صورت کد اجرا میشوند. این کار را برای هر ابزاری که خروجی آن از اندازه یک صفحه فراتر میرود، انجام دهید. همین منطق برای یک فایل 3,000 خطی نیز صدق میکند: فقط محدوده خطوط مورد نیاز خود را درخواست کنید، زیرا وقتی کل فایل وارد شود، در window باقی میماند.
محدوده خواندن agent را تعیین کنید و کارهای پرحجم را به دیگران واگذار کنید
درخواستی که نام فایل و علامت خطا را ذکر میکند، آن فایل را میخواند. یک درخواست باز برای مرتبسازی پروژه، هر آنچه را که agent مرتبط تشخیص دهد میخواند و تمام این خواندنها در پنجره باقی میماند.
کارهای پرحجم را به یک subagent واگذار کنید. اجرای تستها و پردازش logها هر دو از context واقعی استفاده میکنند؛ یک subagent آن خروجی را در پنجره خود نگه میدارد و فقط یک خلاصه را بازمیگرداند. هزینه این کار: یک subagent در اولین فراخوانی خود بدون hit در cache عمل میکند و حتی در حالت subscription، از lifetime 5 دقیقهای cache استفاده میکند. واگذاری کار به صورت قابل اتکایی از context اصلی شما محافظت میکند. این کار همیشه باعث کاهش کل tokenها نمیشود.
زمانبندی حافظه پنهان: در بازههای زمانی کار کنید
قابلیت Prompt caching باعث کاهش هزینه ارسال مجدد میشود: هزینه خواندن prefix برابر با 0.1x نرخ پایه ورودی است، در حالی که هزینه نوشتن آن 1.25x و برای مدت زمان ماندگاری یکساعته، 2x است. هر بار استفاده، بدون هزینه اضافی، ورودی را بهروزرسانی میکند؛ بنابراین زمانبندی از آخرین زمان استفاده محاسبه میشود.
مدت زمان ماندگاری بستگی به نحوه احراز هویت شما دارد؛ به همین دلیل عبارت کلی «حافظه پنهان شما پس از پنج دقیقه منقضی میشود» اشتباه است.
- در اشتراک Claude، ابزار Claude Code بهطور خودکار مدت زمان ماندگاری یکساعته را درخواست میکند.
- پس از اتمام سقف طرح خود و استفاده از اعتبار مصرفی (usage credits)، هزینه آن محاسبه میشود، بنابراین مدت زمان به پنج دقیقه کاهش مییابد.
- در حالت API key یا ارائهدهنده ابری، مدت زمان روی پنج دقیقه باقی میماند.
ENABLE_PROMPT_CACHING_1H=1برای مدت زمان یکساعته انتخاب میکند وFORCE_PROMPT_CACHING_5M=1آن را دوباره به پنج دقیقه محدود میکند.
توصیه مربوط به ریتم کار در هر دو حالت یکسان است: در بازههای زمانی مداوم کار کنید، زیرا ایجاد وقفه در زمان بیکاری (idle) فراتر از مدت ماندگاری، باعث میشود در نوبت بعدی کل prefix انباشته شده دوباره نوشته شود. یک session مجزای Claude Code در tmux در زمان بیکاری هیچ هزینهای ندارد، و حافظه پنهان گرم (warm cache) همان چیزی است که در زمان بیکاری حفظ میشود.
برخی اقدامات باعث حذف حافظه پنهان در حین کار میشوند: تغییر مدل، تغییر سطح تلاش (effort level)، فعال کردن fast mode، اتصال یا قطع کردن یک MCP server، فعال یا غیرفعال کردن یک plugin، رد کردن یک tool کامل، فشردهسازی (compacting) و ارتقای Claude Code. /model یک مورد غافلگیرکننده معمول است، زیرا هر مدل حافظه پنهان مخصوص خود را دارد؛ بنابراین درخواست بعدی کل تاریخچه را میخواند و با وجود یکسان بودن محتوا، هیچ کشبندی (cache hit) صورت نمیگیرد.
ویرایش فایلها، ویرایش CLAUDE.md، فراخوانی مهارتها و دستورات، اجرای /recap، بازگشت به عقب (rewinding) و ایجاد یک subagent، همگی حافظه پنهان را حفظ میکنند. محدوده حافظه پنهان به یک ماشین و یک دایرکتوری محدود میشود، بنابراین دو session در دایرکتوریهای متفاوت، حافظه پنهان یکدیگر را در دسترس ندارند.
برای بررسی عملکرد حافظه پنهان، current_usage را بخوانید. cache_creation_input_tokens با نرخ نوشتن در حافظه پنهان نوشته شد؛ cache_read_input_tokens با تقریباً یکدهم نرخ استاندارد ورودی ارائه شد. نسبت بالای خواندن به ایجاد (read-to-creation ratio) نشاندهنده وضعیت مطلوب است. اگر نرخ ایجاد در هر نوبت بالا باقی میماند، بخشی از prefix شما مدام در حال تغییر است.
آیا یک context window بزرگتر این مشکل را حل میکند؟
تا حدودی. چندین مدل فعلی از یک context window با ظرفیت 1 million token پشتیبانی میکنند و فرآیند compaction در این محدودهی بزرگتر نیز به همان صورت عمل میکند. از نظر اقتصادی تغییری ایجاد نمیشود، زیرا prompt کامل همچنان در هر turn مجدداً ارسال میشود و هزینه آن محاسبه میگردد. یک window بزرگتر تعیین میکند که چه زمانی مجبور به اقدام هستید؛ اما رعایت اصول hygiene هزینه را تعیین میکند. اگر مشکل به جای سقف ظرفیت، میزان هزینه باشد، بررسی کنید کدام طرح Claude با سبک کاری شما سازگار است تعیین میکند که آیا در حال صرف دلار هستید یا از سهمیه طرح خود استفاده میکنید.
ویرایش و فشردهسازی Context در API دو قابلیت متفاوت هستند
اگر در حال ساخت عامل (agent) اختصاصی خود بر پایه Messages API هستید، هیچ دستور اسلش (slash command) وجود ندارد و شما باید این قابلیت را خودتان پیادهسازی کنید. دو قابلیت سمت سرور این کار را انجام میدهند که با هم متفاوت هستند.
Context editing با رشد تاریخچه گفتگو، محتوای خاصی را به صورت انتخابی پاک میکند و هر نتیجهی پاک شده را با یک متن جایگزین (placeholder) عوض میکند تا Claude بداند محتوایی حذف شده است. این قابلیت در مرحله beta است: مقدار anthropic-beta: context-management-2025-06-27 را ارسال کنید و استراتژیها را تحت context_management.edits پیکربندی کنید. clear_tool_uses_20250919 نتایج ابزار (tool results) را پاک میکند و clear_thinking_20251015 بلوکهای تفکر (thinking blocks) را مدیریت میکند. مقدار پیشفرض trigger برابر با 100,000 توکن ورودی، keep برابر با 3 مورد آخر استفاده از tool، و clear_tool_inputs برابر با false است؛ بنابراین ورودیها باقی میمانند و فقط نتایج حذف میشوند.
Compaction یک خلاصه تولید میکند و کل تاریخچه گفتگو را با آن جایگزین میکند. این قابلیت نیز در مرحله beta است: مقدار anthropic-beta: compact-2026-01-12 را ارسال کنید و از نوع ویرایش compact_20260112 استفاده کنید. مقدار پیشفرض برای شروع (trigger) برابر با {"type": "input_tokens", "value": 150000} است و مقدار باید حداقل 50,000 باشد.
Compaction یک قانون انتقال (handoff rule) دارد که باعث خرابی بیسر و صدای عاملها میشود. پاسخ با یک بلوک محتوای compaction شروع میشود که خلاصه را در خود دارد و پس از آن بلوک متنی معمولی قرار میگیرد. شما باید آن بلوک را در درخواستهای بعدی دوباره ارسال کنید، در غیر این صورت API تمام بلوکهای محتوایی قبل از آن را حذف میکند. در عمل: کل محتوای response.content را اضافه کنید، نه فقط متن را.
مستندات Anthropic، فشردهسازی سمت سرور را استراتژی اصلی برای مدیریت context در گفتگوهای طولانی مینامد و ویرایش context را گزینهای برای کنترل دقیقتر بر روی موارد حذف شده میداند. ابتدا پشتیبانی مدل را بررسی کنید. مدلهای فعلی Opus، Sonnet و Fable از compaction پشتیبانی میکنند؛ claude-haiku-4-5 این پشتیبانی را ندارد و لیست بهروز در صفحه مربوط به compaction موجود است. هیچکدام از این دو قابلیت beta، باعث عملکرد /compact در Claude Code نمیشوند؛ مستندات آن را به عنوان یک درخواست خلاصهسازی یکباره (one-off) توصیف میکند که کلاینت ارسال میکند.
FAQ
چرا با طولانی شدن session در Claude Code، سرعت کمتر و هزینه بیشتر میشود؟
دلیل این است که در هر مرحله، کل گفتگو دوباره ارسال میشود؛ بنابراین یک سوال تکخطی در sessoni که تمام روز باز مانده است، تمام تاریخچه آن روز را با خود حمل میکند. قابلیت Prompt caching تا زمانی که cache گرم باشد، هزینه را پایین نگه میدارد (0.1x نرخ پایه برای خواندن)؛ اما به محض اینکه یک مرحله از cacheMiss شود، همان پیشوند با نرخ 1.25x دوباره ارسال میشود. برای مشاهده آنچه پنجره را پر کرده است دستور /context را اجرا کنید و برای درک مکانیسم هزینهها، مکانیسم صورتحساب Claude Code را بخوانید.
تفاوت بین /clear و /compact در Claude Code چیست؟
دستور /clear یک گفتگو با context خالی شروع میکند. این دستور هیچ درخواستی ارسال نمیکند، بنابراین هزینهای ندارد و برای کارهای بیارتباط با هم، انتخاب مناسبی است. دستور /compact همان گفتگو را حفظ کرده و تاریخچه را با یک خلاصه جایگزین میکند، بنابراین برای انجام یک تسک طولانی مناسب است. مانند دستور /compact keep only the plan and the diff به آن تمرکز (focus) بدهید، زیرا دستورالعمل تعیین میکند چه بخشهایی باقی بمانند.
چگونه ببینم چه چیزی در حال مصرف کردن context window در Claude Code است؟
دستور /context را اجرا کنید، یا برای جزئیات کامل به تفکیک هر آیتم از /context all استفاده کنید. این دستور، system prompt، تعاریف ابزارها (tool definitions)، سرورهای MCP، فایلهای حافظه (memory files) و تاریخچه را به صورت یک جدول رنگی نمایش میدهد و پیشنهاداتی برای ابزارهای پرحجم و bloat حافظه ارائه میدهد. در طرحهای پولی، دستور /usage میزان استفاده اخیر را به مهارتها، subagents و سرورهای MCP اختصاص میدهد.
آیا به جای استفاده از compaction، باید از context window با 1 million token استفاده کنم؟
استفاده از یک پنجره بزرگتر، مشکل را حل نمیکند بلکه فقط آن را به تأخیر میاندازد. چندین مدل فعلی از context window با 1 million token پشتیبانی میکنند، از جمله Opus 4.8 و Sonnet 5، و در آنجا نیز compaction به همین صورت عمل میکند. در هر مرحله، همچنان کل prompt ارسال میشود و هزینه آن محاسبه میگردد؛ بنابراین یک گفتگوی 400,000-token بسیار گران است، چه در یک پنجره بزرگ جا شود و چه نشود.
تفاوت بین context editing و compaction در Claude API چیست؟
Context editing به صورت انتخابی محتوای قدیمی، عمدتاً نتایج ابزارها (tool results) را پاک میکند و در محل هر کدام یک متن جایگزین (placeholder) باقی میگذارد تا Claude بداند آن بخش حذف شده است. Compaction یک خلاصه تولید کرده و کل تاریخچه را با آن جایگزین میکند. مستندات Anthropic، compaction را استراتژی اصلی برای گفتگوهای طولانی میداند و context editing را به عنوان یک گزینه دقیقتر (fine-grained) معرفی میکند. هر دو در مرحله beta هستند و هر دو از /compact در Claude Code مجزا میباشند.