کالبدشکافی طراحی هارنس Claude Code

در مقاله هارنس‌های کارآمد برای ایجنت‌های با اجرای طولانی‌مدت، شرکت Anthropic به صراحت بیان می‌کند که قابلیت اطمینان از هارنس ناشی می‌شود نه از مدل، و ایجنت‌ها به محدودیت‌هایی «در بیرون از مدل» نیاز دارند. ابزار Claude Code نمونه‌ای محصول‌شده از این ایده است؛ خود Anthropic صراحتاً آن را به عنوان یک هارنس ایجنتی (agentic harness) دسته‌بندی می‌کند. این زبان بازاریابی نیست — ابزار Claude Code شاید دقیق‌ترین هارنس عمومی مورد بررسی قرار گرفته تا به امروز باشد: سورس کد آن در دسترس است، گزارش‌های پژوهشی جامعه کاربری درباره آن مفصل است، و تقریباً تمام سازوکارهای محوری مطرح‌شده در درس‌های دوره — حافظه چندلایه‌ای، فشرده‌سازی زمینه، مجوزها، هوک‌ها، زیر-ایجنت‌ها، و ماندگارسازی نشست — را به یک پیاده‌سازی کامل محصولی تبدیل می‌کند.

در این مقاله، ما از چارچوب پنج زیرسیستم دوره برای کالبدشکافی Claude Code استفاده می‌کنیم، با تمرکز بر اینکه چگونه مفاهیم بنیادین هارنس مانند «مدیریت زمینه»، «جلوگیری از اعلام پیروزی زودهنگام» و «محدودیت‌های قطعی» را پیاده‌سازی می‌نماید.

در یک جمله#

در هسته Claude Code یک حلقه ساده while قرار دارد: مدل را فراخوانی کن، ابزار را اجرا کن، نتیجه را مشاهده کن و دوباره مدل را فراخوانی نما. اما بخش اعظم کد در آن حلقه نیست؛ بلکه در سیستم‌های پیرامون حلقه قرار دارد — سیستم مجوزها، پایپ‌لاین فشرده‌سازی زمینه، سازوکارهای گسترش، هماهنگ‌سازی زیر-ایجنت‌ها و ذخیره‌سازی نشست. این جوهره هارنس است: حلقه اسکلت است، اما هر آنچه پیرامون اسکلت قرار دارد قابلیت اطمینان را تعیین می‌کند.

زیرسیستم دستورالعمل‌ها: یک سیستم حافظه چندلایه‌ای#

سیستم حافظه Claude Code مستقیم‌ترین سهم آن در تئوری هارنس است، که با درس‌های دوره درباره «مخزن به عنوان منبع مرجع» و «پیوستگی زمینه بین‌نشستی» همخوانی دارد. مستندات رسمی در چگونه Claude پروژه شما را به خاطر می‌سپارد به روشنی بیان می‌کند که هر نشست با یک پنجره زمینه تازه آغاز می‌شود و دانش را از طریق دو سازوکار در طول نشست‌ها انتقال می‌دهد: فایل‌های CLAUDE.md (دستورالعمل‌هایی که شما می‌نویسید) و حافظه خودکار (auto memory؛ یادداشت‌هایی که Claude خودش می‌نویسد).

از نظر دامنه و محدوده، مستندات رسمی فایل‌های CLAUDE.md را به چهار دسته تقسیم می‌کند (که از عام‌ترین به خاص‌ترین بارگذاری می‌شوند):

• سطح خط‌مشی سازمانی: به صورت مرکزی توسط IT/DevOps مدیریت می‌شود (به عنوان مثال، /etc/claude-code/CLAUDE.md) برای استانداردهای سراسر شرکت.
• سطح کاربری ~/.claude/CLAUDE.md: ترجیحات و قواعد شخصی که در تمام پروژه‌ها اعمال می‌شوند.
• سطح پروژه ./CLAUDE.md یا ./.claude/CLAUDE.md: منبع مرجع در سطح پروژه برای معماری، پشته فناوری و دستورات راستی‌آزمایی، که با مخزن به اشتراک گذاشته می‌شود.
• سطح محلی ./CLAUDE.local.md: ترجیحات شخصی درون یک پروژه، که معمولاً به جای کامیت شدن به .gitignore اضافه می‌شود.

همچنین دو سازوکار مکمل وجود دارد:

• بارگذاری بر حسب تقاضا در سطح زیرپوشه‌ها: فایل‌های CLAUDE.md در زیرپوشه‌ها در زمان راه‌اندازی بارگذاری نمی‌شوند؛ آن‌ها تنها زمانی وارد زمینه می‌شوند که Claude فایل‌هایی را در آن دایرکتوری بخواند.
• حافظه خودکار (Auto memory): ابزار Claude بر اساس اصلاحات و ترجیحات شما به طور فعال یادداشت می‌نویسد. این یادداشت‌ها بر اساس مخزن به اشتراک گذاشته می‌شوند، در سراسر ورک‌تری‌ها اعمال می‌گردند، و در هر نشست حداکثر 200 خط اول یا 25KB را بارگذاری می‌کنند.

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

زیرسیستم زمینه: یک پایپ‌لاین فشرده‌سازی پنج‌لایه‌ای#

بر اساس تحلیل سورس‌کد Claude Code v2.1.88 توسط آزمایشگاه VILA Lab در گزارش بررسی عمیق Claude Code، این سیستم در آن زمان از یک پایپ‌لاین فشرده‌سازی پنج‌لایه‌ای استفاده می‌کرد، نه صرفاً «خلاصه‌سازی در زمان پر شدن». درس 5 توضیح می‌دهد که وظایف طولانی‌مدت چگونه پیوستگی را از دست می‌دهند؛ پاسخ Claude Code یک قیف چندمرحله‌ای است: ابتدا هرس بدون اتلاف (حذف نتایج تکراری ابزارها)، سپس تقطیر ساختاریافته، و تنها پس از آن خلاصه‌سازی با اتلاف LLM، همراه با مدارشکن‌ها (circuit breakers) برای جلوگیری از فشرده‌سازی بیش از حد.

این امر با طراحی ذخیره‌سازی نشست جفت می‌شود: ذخیره‌سازی الحاق‌محور (append-oriented). تمام تاریخچه به history.jsonl الحاق می‌شود، همراه با بازیابی با /resume و شاخه‌های فورک. این تضمین می‌کند که «هر نشست پیش از پایان یک تحویل مناسب بر جای بگذارد» — نه به این دلیل که سیستم حافظه خوبی دارد، بلکه به این دلیل که لایه ذخیره‌سازی الحاقی و قابل بازپخش است.

زیرسیستم ابزارها: چهار سازوکار گسترش#

ابزار Claude Code سطح گسترش خود را به چهار دسته تقسیم می‌کند، که هرکدام نوع متفاوتی از مسئله را حل می‌کنند. این بخشی از طراحی آن است که بیشترین ارزش الگوبرداری را دارد:

• مهارت‌ها (Skills): در مستندات رسمی به عنوان دانش رویه‌ای توصیف‌شده با SKILL.md تعریف شده است، که بر اساس تریگرها و از طریق آشکارسازی پیش‌رونده به طور خودکار بارگذاری می‌شوند. آن‌ها برای دانش حوزه‌ای درباره «چگونه کاری را انجام دهیم» مناسب هستند.
• پروتکل MCP: پروتکل JSON-RPC در مستندات رسمی سیستم‌های خارجی را متصل می‌کند، و رابط استانداردی فراهم می‌سازد که از طریق آن «مدل می‌تواند به دنیای بیرون دسترسی پیدا کند».
• هوک‌ها (Hooks): اسکریپت‌های قطعی متصل به رویدادهای چرخه حیات نظیر PreToolUse، PostToolUse، و Stop، همان‌طور که در مستندات رسمی توصیف شده است.
• پلاگین‌ها / زیر-ایجنت‌ها (Subagents): در مستندات رسمی واگذاری وظایف پیچیده به ایجنت‌های تخصصی شرح داده شده است.

طراحی کلیدی در اینجا تفکیک مسئولیت‌ها است: فایل CLAUDE.md وظیفه مدیریت «چه چیزی» را بر عهده دارد، Skills مدیریت «چگونه»، MCP مدیریت «اتصال به کجا»، و هوک‌ها مدیریت «چه زمانی اعمال شود». اگر تیمی این لایه‌ها را با هم ترکیب کند — به عنوان مثال کاری را که متعلق به MCP است درون CLAUDE.md قرار دهد — نشت زمینه که در دوره تشریح شد پدید می‌آید.

بازخورد و راستی‌آزمایی: محدودیت‌های قطعی + تقسیم کار انسان و ایجنت#

درس 10 توضیح می‌دهد که «تنها اجرای کامل پایپ‌لاین راستی‌آزمایی واقعی محسوب می‌شود». ابزار Claude Code این را از طریق دو مسیر پیاده می‌کند:

1. سیستم مجوزها (محدودیت‌های قطعی). مجوزهای Claude Code صرفاً «درباره همه چیز سوال پرسیدن» نیست. طبق تحلیل VILA Lab روی نسخه v2.1.88، سیستم در آن زمان هفت حالت را با یک دسته‌بند مبتنی بر یادگیری ماشین ترکیب می‌کرد: عملیات کم‌خطر مجاز هستند، در حالی که عملیات پرخطر بر اساس خط‌مشی یا تأیید می‌شوند یا رد می‌گردند (برای جزئیات معماری به تحلیل VILA Lab مراجعه کنید). توجه داشته باشید که نام‌گذاری حالت‌های مجوز از زمان v2.1.88 تغییر یافته است: مستندات فعلی Anthropic در حالت‌های مجوز حالت‌های Manual (پیش‌تر "default"، بازنام‌گذاری‌شده در نسخه v2.1.200+)، Plan، acceptEdits، Auto، dontAsk، و bypassPermissions را فهرست می‌کند. این امر اصل «ترسیم مرزهای شفاف وظایف برای ایجنت‌ها» (درس 7) را به جای یک خواهش در پرامپت، به الزام در زمان اجرا تبدیل می‌نماید.

2. هوک‌ها (جلوگیری از اعلام پیروزی زودهنگام). هوک‌های PostToolUse می‌توانند بررسی‌ها را پس از اجرای ابزار اجباری کرده و نتایج را به زمینه بازگردانند؛ هوک‌های Stop زمانی که ایجنت اعلام اتمام کار می‌کند وارد عمل می‌شوند. این امر «فرد انجام‌دهنده کار» را از «فرد بررسی‌کننده کار» تفکیک می‌کند. Anthropic در مقاله هارنس خود صراحتاً مشاهده کرد که ایجنت‌ها «با اعتمادبه‌نفس از کار خود بیش از حد تمجید می‌کردند»، بنابراین هوک‌ها به جای اعتماد به خودارزیابی مدل، بررسی‌های قطعی را تزریق می‌کنند.

3. زیر-ایجنت‌ها (جداسازی زمینه). تاریخچه گفتگوی هر زیر-ایجنت در یک فایل سایدچین (sidechain) جداگانه ذخیره می‌شود و زمینه ایجنت والد را متورم نمی‌کند (گزارش تحلیل VILA Lab را ببینید). این امر «مرزهای وظیفه» را با «جداسازی زمینه» ترکیب می‌کند: تفکیک یک وظیفه، آلودگی زمینه را نیز ایزوله می‌سازد.

مشاهده‌پذیری و ماندگارسازی نشست#

لاگ‌های Claude Code سوابق کامل الحاق‌محور هستند (history.jsonl). همراه با دستورات صریح مانند /compact، /clear، و /init، این به شما امکان می‌دهد وضعیت زمینه را به صورت کنشگرانه مدیریت کنید نه اینکه منفعلانه منتظر پر شدن آن بمانید. دستور /init حتی اصل «مقداردهی اولیه پیش از آغاز هر وظیفه» (درس 6) را به یک دستور تبدیل می‌کند. مستندات رسمی بیان می‌کند که این دستور به طور خودکار پایگاه کد را تحلیل کرده و یک CLAUDE.md اولیه حاوی دستورات بیلد، دستورالعمل‌های تست و عرف‌های مهندسی تولید می‌نماید.

نگاشت به چارچوب دوره#

طرح‌های شایسته الگوبرداری#

1. دستورالعمل‌ها را بر اساس دامنه لایه‌بندی کنید به جای انباشتن آن‌ها در یک فایل واحد. فایل‌های CLAUDE.md در سطح پوشه‌ها پیاده‌سازی ظریفی از «بارگذاری نزدیک به جایی که دستورالعمل اعمال می‌شود» است.
2. فشرده‌سازی باید یک قیف مرحله‌بندی‌شده باشد: هرس بدون اتلاف پیش از روش‌های با اتلاف؛ کار را با خلاصه‌سازی همه چیز شروع نکنید.
3. از هوک‌ها برای بررسی‌های قطعی استفاده کنید: جلوگیری از اعلام پیروزی زودهنگام نیازمند اعمال در زمان اجراست، نه التماس در پرامپت‌ها.
4. زمینه زیر-ایجنت را ایزوله کنید: هنگام تفکیک یک وظیفه، زمینه را نیز تقسیم کنید تا نتایج زیروظایف حلقه اصلی را آلوده نکنند.
5. ذخیره‌سازی نشست را الحاق‌محور و قابل بازپخش بسازید: تحویل‌ها به لایه ذخیره‌سازی وابسته‌اند، نه به حافظه.

مراجع#

تمام ادعاها را می‌توان در منابع زیر ردگیری کرد:

مستندات رسمی Anthropic#

• Claude Code · Memory: زمینه تازه برای هر نشست، چهار دامنه CLAUDE.md، بارگذاری بر حسب تقاضا بر اساس زیرپوشه، حافظه خودکار (200 سطر / 25KB)، و تولید CLAUDE.md با دستور /init.
  https://code.claude.com/docs/en/memory
• Claude Code · Skills / MCP / Hooks / Sub-agents: تعاریف چهار سازوکار گسترش و رویدادهای آن‌ها (PreToolUse / PostToolUse / Stop).
  https://code.claude.com/docs/en/skills | https://code.claude.com/docs/en/mcp | https://code.claude.com/docs/en/hooks | https://code.claude.com/docs/en/sub-agents
• Claude Code · Permission modes: نام‌های فعلی حالت‌ها شامل Manual (پیش‌تر "default"، بازنام‌گذاری‌شده در نسخه v2.1.200+)، Plan، acceptEdits، Auto، dontAsk، و bypassPermissions.
  https://code.claude.com/docs/en/permission-modes
• Anthropic, Effective harnesses for long-running agents: منبع ادعاهایی مبنی بر اینکه «قابلیت اطمینان از هارنس حاصل می‌شود نه مدل»، اینکه ایجنت‌ها «با اعتمادبه‌نفس از کار خود بیش از حد تمجید می‌کردند»، و اینکه هوک‌ها باید برای راستی‌آزمایی استفاده شوند.
  https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

پژوهش‌های مستقل و جامعه کاربری#

منابع این بخش نشان‌دهنده یک نسخه تاریخی مشخص هستند (Claude Code v2.1.88 در زمان تحلیل VILA Lab) و ممکن است با رفتار فعلی یکسان نباشند.

• VILA Lab, Dive into Claude Code (تحلیل در سطح سورس‌کد نسخه v2.1.88): پایپ‌لاین فشرده‌سازی پنج‌لایه‌ای، هفت حالت مجوز + دسته‌بند یادگیری ماشین، زیر-ایجنت‌های سایدچین، و ذخیره‌سازی الحاق‌محور نشست در history.jsonl.
  https://zhiqiangshen.com/projects/Claude_Code_Report/Claude_Code_Report.pdf
• Claude Code Full Stack Guide (راهنمای جامعه کاربری برای لایه‌های CLAUDE.md / Skills / MCP / Subagents / Hooks): مطالعه تکمیلی پیرامون تفکیک مسئولیت‌ها در میان سازوکارهای گسترش.
  https://jsmanifest.com/claude-code-full-stack-guide

درس‌های مرتبط: درس 3 · تبدیل مخزن به یگانه منبع حقیقت ｜ درس 09 · جلوگیری از اعلام پیروزی زودهنگام توسط ایجنت‌ها ｜ درس 10 · تنها اجرای کامل پایپ‌لاین راستی‌آزمایی واقعی محسوب می‌شود