فصل جدیدمعماری یک عامل هوش مصنوعی (The Architecture of an AI Agent)

۱. مقدمه و پارادایم جدید برنامه‌نویسی CLI با عامل‌های هوش مصنوعی

یک ابزار خط فرمان (CLI) سنتی مانند grep یا curl در واقع یک تابع قطعی (Deterministic) است: آرگومان‌ها را دریافت کرده، عملیاتی مشخص را اجرا می‌کند و پایان می‌یابد. در این پارادایم، پیمان سیستم ساده و غیرقابل‌تغییر است؛ یک دستور، یک اقدام و خروجی کاملاً پیش‌بینی‌پذیر. ابزار grep هرگز تصمیم نمی‌گیرد که پس از جستجو دستور sed را اجرا کند، یا curl به‌طور خودکار فایلی را باز نکرده و ویرایش نمی‌کند. اما یک خط فرمان مبتنی بر عامل (Agentic CLI) تمام این قواعد را در هم می‌شکند. چنین ابزاری پرامپت زبان طبیعی را دریافت کرده، ابزارهای لازم را بر اساس شرایط انتخاب می‌کند، آن‌ها را با ترتیبی پویا به اجرا درمی‌آورد، نتایج را ارزیابی کرده و این چرخه را تا زمان تکمیل تسک یا توقف توسط کاربر ادامه می‌دهد. در اینجا «برنامه» یک سری دستورات ثابت و پیش‌کامپایل‌شده نیست، بلکه یک حلقه حول مدل زبانی است که سلسله‌دستورات خود را در زمان اجرا (Runtime) تولید می‌کند؛ فراخوانی ابزارها اثرات جانبی (Side Effects) بوده و استدلال مدل، همان کنترل جریان (Control Flow) برنامه است.

Claude Code پیاده‌سازی عملیاتی و تجاری همین پارادایم توسط Anthropic است: یک مونو‌لیت قدرتمند TypeScript با نزدیک به ۲۰۰۰ فایل که محیط ترمینال را به یک محیط توسعه کامل و متکی بر Claude تبدیل می‌کند. انتشار این محصول برای صدها هزار توسعه‌دهنده به این معناست که تمام تصمیمات معماری آن تحت فشارهای واقعی محیط تولید (Production) و چالش‌های مقیاس‌پذیری اتخاذ شده‌اند. محتوای این مقاله بر اساس مهندسی معکوس دقیق سورس‌مپ‌های (.js.map) افشاشده در نسخه npm نوشته شده است؛ جایی که فیلد sourcesContent شامل کدهای اصلی و کامل TypeScript بود.

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

برای کالبدشکافی دقیق این مونو‌لیت ۲۰۰۰ فایلی، ابتدا باید استخوان‌بندی زیرین سیستم را تحلیل کنیم؛ جایی که ۶ مفهوم انتزاعی پایه، شالوده اصلی تمام رفتارهای پیشرفته عامل را شکل می‌دهند.

۲. شش مفهوم انتزاعی کلیدی در سیستم (The Six Key Abstractions)

در لایه زیرین Claude Code، شش مفهوم انتزاعی پایه وجود دارند که استخوان‌بندی و شالوده اصلی تمام امکانات سیستم را تشکیل می‌دهند. تمام قابلیت‌های جانبی—از بیش از ۴۰۰ فایل کمکی گرفته تا فورک اختصاصی رندر ترمینال، ایمولیشن ویما (Vim) و سیستم ردیابی هزینه—همگی صرفاً برای پشتیبانی و سرویس‌دهی به این ۶ مفهوم وجود دارند.

۲.۱. حلقه پرس‌وجو (The Query Loop)

قلب تپنده کل سیستم، حلقه پرس‌وجو است که در فایل query.ts (با حدود ۱,۷۰۰ سطر کد) پیاده‌سازی شده است. این ساختار یک تولیدکننده ناهمگام (AsyncGenerator) است که جریان خروجی مدل را دریافت کرده، فراخوانی ابزارها را جمع‌آوری و اجرا می‌کند، نتایج را به تاریخچه پیام‌ها پیوست کرده و مجدداً چرخه را تکرار می‌کند. تمام تعاملات سیستم—اعم از محیط REPL، SDK، زیر-عامل‌ها و حالت بدون رابط (--print)—همگی از مسیر این تابع واحد عبور می‌کنند.

حلقه query.ts اشیای ورودی/خروجی از نوع Message را برای مصرف در UI تولید (yield) می‌کند. خروجی نهایی این ژنراتور، یک تایپ اختصاصی متمایز شده (Discriminated Union) با نام Terminal است که علت دقیق توقف حلقه را به صورت کاملاً تایپ‌شده مشخص می‌سازد:

// ساختار انتزاعی خروجی تایپ‌شده حلقه query.ts type Terminal = | { type: 'normal' } | { type: 'user_abort' } | { type: 'token_budget_exhausted'; limit: number } | { type: 'stop_hook_intervention'; reason: string } | { type: 'max_turns_reached'; turns: number } | { type: 'unrecoverable_error'; error: Error };

استفاده از الگوی AsyncGenerator به جای Callbackها یا Event Emitterها، قابلیت کنترل فشار معکوس (Backpressure) به صورت طبیعی، لغو تمیز اجرای فرآیندها (.return()) و مدیریت وضعیت‌های توقف با تایپ مشخص (Typed Terminal States) را برای معماران سیستم فراهم می‌کند.

۲.۲. سیستم ابزارها (The Tool System)

سیستم ابزارها (پیاده‌شده در Tool.ts، tools.ts و پوشه services/tools/) نمایانگر هر نوع اقدامی است که عامل می‌تواند در محیط خارجی انجام دهد؛ مانند خواندن فایل، اجرای دستورات شل، ویرایش کد یا جستجو در وب.

این سیستم ابزارها را صرفاً به عنوان یک تابع ساده ندیده، بلکه رابط‌های غنی برای آن‌ها تعریف می‌کند. هر ابزار شامل منطق بررسی مجوزها (Permissions)، اعلام هم‌زمانی (Concurrency Declarations)، گزارش پیشرفت (Progress Reporting) و نحوه رندر UI اختصاصی خود است. سیستم اجرای ابزارها، فراخوانی‌ها را به دسته‌های موازی (برای عملیات‌های ایمن و فقط-خواندنی) و متوالی (برای عملیات تغییردهنده) افراز (Partitioning) می‌کند. علاوه بر این، مجری استریمینگ (StreamingToolExecutor) اجرای گمانه‌زنانه (Speculative Execution) ابزارهای موازی را حتی پیش از اتمام کامل پاسخ متنی مدل آغاز می‌کند.

۲.۳. لایه تسک‌ها (Tasks Layer)

تسک‌ها (پیاده‌شده در Task.ts و پوشه tasks/) واحدهای کاری پس‌زمینه—عمدتاً زیر-عامل‌ها (Sub-agents)—هستند. ماشین وضعیت تسک‌ها، چرخه حیات زیر را طی می‌کند: pending -> running -> completed | failed | killed

ابزار اختصاصی AgentTool امکان ساخت یک ژنراتور query() جدید و مستقل را فراهم می‌کند که دارای تاریخچه پیام، مجموعه ابزارها و مود مجوز مجزای خود است. این لایه، قابلیت بازگشتی (Recursive Capability) را به Claude Code می‌دهد؛ به‌طوری‌که یک عامل می‌تواند وظایف را به زیر-عامل‌ها ارجاع دهد و آن‌ها نیز به نوبه خود کار را به زیر-عامل‌های خردتر واگذار کنند.

۲.۴. لایه وضعیت دوسطحی (Two-Tier State Layer)

سیستم مدیریت وضعیت در این معماری به دو سطح کاملاً مجزا تفکیک شده است:

1. شیء سینگلتون تغییرپذیر (STATE): این شیء حاوی حدود ۸۰ فیلد زیرساختی در سطح جلسه کاری (Session-level) است؛ از جمله مسیر پروژه، پیکربندی مدل، ردیابی هزینه، شمارنده‌های تل‌متری و شناسه جلسه. این شیء در زمان راه‌اندازی مقداردهی شده و مستقیماً تغییر می‌یابد و فاقد هرگونه قابلیت واکنش‌پذیری (Non-reactive) است.
2. استور واکنش‌پذیر UI: یک استور واکنش‌پذیر بسیار سبک (۳۴ سطری، مشابه ساختار Zustand) که صرفاً وضعیت‌های مرتبط با رابط کاربری مانند پیام‌ها، مود ورودی کاربر، تاییدیه ابزارها و نشانگرهای پیشرفت را مدیریت می‌کند.

علت این تفکیک معماری در این است که وضعیت‌های زیرساختی به نادرست تغییر می‌کنند و نیازی به تحریک رندر مجدد UI ندارند، در حالی که وضعیت‌های UI مرتباً در حال تغییر بوده و نیازمند واکنش‌پذیری سریع هستند.

۲.۵. سیستم حافظه (Memory System)

سیستم حافظه (واقع در memdir/) مسئول حفظ کانتکست ماندگار در طول جلسات کاری مختلف، بدون نیاز به پایگاه داده خارجی یا دیتابیس‌های برداری (Vector DBs) و بر پایه فایل‌های Markdown است. این حافظه در ۳ سطح سازمان‌دهی می‌شود:

• سطح پروژه: فایل‌های CLAUDE.md در مخزن کد.
• سطح کاربر: فایل ~/.claude/MEMORY.md.
• سطح تیم: اشتراک‌گذاری از طریق Symlinkها.

مکانیزم بازخوانی حافظه با مدل زبانی (LLM Recall)

در زمان راه‌اندازی، سیستم ابتدا یک اسکن سبُک (Prefetch) روی تمام فایل‌های حافظه اجرا کرده و تنها ۳۰ سطر اول (بخش Frontmatter و عنوان) هر فایل را می‌خواند تا مانفیست حافظه را تشکیل دهد. سپس، یک کوئری جانبی ناهمگام به مدل Sonnet صادر می‌شود. مدل Sonnet مانفیست حافظه، کوئری جدید کاربر و ابزارهای فعال را تحلیل کرده و لیستی شامل حداکثر ۵ فایل مرتبط را در قالب یک خروجی ساختاریافته JSON ({ selected_memories: string[] }) برمی‌گرداند.

فایل‌های انتخاب‌شده پس از خوانده شدن، همراه با یک هشدار کهنگی داده (Staleness Warning) انسان‌فهم به کانتکست اضافه می‌شوند. سیستم با محاسبه اختلاف زمانی، برچسب‌هایی مانند "today"، "yesterday" یا "47 days ago" درج می‌کند. برچسب‌گذاری صریح بر حسب تعداد روز گذشته، توانایی استدلال مدل را در خصوص اعتبارسنجی مجدد داده‌های قدیمی به‌شدت ارتقا می‌دهد.

۲.۶. سیستم قلاب‌ها (Hooks System)

سیستم قلاب‌ها (در hooks/ و utils/hooks/) امکان رهگیری رویدادهای چرخه حیات سیستم را در ۲۷ رویداد مختلف و در قالب ۴ نوع اجرا فراهم می‌سازد: دستورات شل (Shell Commands)، پرامپت‌های تک‌مرحله‌ای LLM، مکالمات چندمرحله‌ای عامل‌ها، و وب‌هوک‌های HTTP.

قلاب‌ها می‌توانند اجرای ابزارها را مسدود کنند، ورودی‌ها را تغییر دهند، کانتکست اضافی تزریق کنند یا روند حلقه پرس‌وجو را قطع نمایند. حتی سیستم مجوزدهی نیز جزئاً از طریق قلاب‌ها پیاده‌سازی شده است؛ به عنوان مثال قلاب‌های PreToolUse می‌توانند فراخوانی یک ابزار را پیش از ظهور پرامپت تعاملی کاربر مسدود کنند.

جدول خلاصه‌سازی مفاهیم ۶‌گانه معماری

نام مفهوم فایل اصلی در سورس‌کد الگوی پیاده‌سازی وظیفه اصلی دلیل وجودی حلقه پرس‌وجو (Query Loop) query.ts AsyncGenerator ناهمگام مدیریت استریم مدل، فراخوانی ابزار و کنترل چرخه ایجاد فشار معکوس طبیعی، کنترل لغو و تایپ خروجی سیستم ابزارها (Tool System) Tool.ts / tools.ts / services/tools/ اینترفیس خودتوصیف‌گر غنی تعریف اعمال خارجی، افراز موازی/متوالی و اجرای گمانه‌زنانه ایزوله‌سازی منطق مجوز و هم‌زمانی درون خود ابزارها لایه تسک‌ها (Tasks Layer) Task.ts / tasks/ ماشین وضعیت خطی مستقیم مدیریت وظایف پس‌زمینه و زیر-عامل‌های بازگشتی امکان ساخت ساختارهای چندعاملی و ارجاع کار وضعیت دوسطحی (State Layer) STATE / AppState تفکیک سینگلتون از استور مدیریت وضعیت زیرساخت و متغیرهای واکنش‌پذیر UI جلوگیری از رندر مجدد بی‌پایان UI با حذف واکنش‌پذیری زاید سیستم حافظه (Memory System) memdir/ فایل‌محور با بازخوانی LLM حفظ دانش پروژه، تنظیمات کاربر و نکات تیم در جلسات یادگیری ماندگار بدون پیچیدگی و هزینه پایگاه داده برداری سیستم قلاب‌ها (Hooks System) hooks/ / utils/hooks/ رهگیرهای چرخه حیات (Interceptors) انباشت کانتکست، مسدودسازی و سفارشی‌سازی رفتارهای سیستم توسعه‌پذیری ایمن و اعمال سیاست‌های کنترلی شفاف

این شش مفهوم انتزاعی مستقل از هم نیستند؛ بلکه زنجیره عملیاتی داده در سیستم را شکل می‌دهند که در بخش بعدی تحت عنوان «مسیر طلایی» بررسی شده است.

۳. جریان داده عملیاتی: مسیر طلایی (The Golden Path)

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

بازسازی گام‌به‌گام چرخه درخواست

1. دریافت ورودی و شروع حلقه: ورودی کاربر در REPL دریافت شده و به ژنراتور query.ts ارسال می‌گردد.
2. تزریق کانتکست و حافظه: کانتکست سیستم به همراه حافظه‌های مرتبط اسکن‌شده از memdir/ (منتخب توسط کوئری جانبی Sonnet) به پرامپت اولیه پیوست می‌شوند.
3. استریم درخواست به API: درخواست به صورت استریم به API مدل زبانی ارسال می‌شود.
4. استخراج و اجرای گمانه‌زنانه ابزارها: مجری استریمینگ (StreamingToolExecutor) به محض استریم شدن نام و آرگومان‌های یک ابزار فقط-خواندنی (مانند خواندن فایل تابع لاگین)، اجرای آن را قبل از اتمام کامل خروجی متنی مدل آغاز می‌کند.
5. ارزیابی مجوز و اجرای ابزار: لایه مجوزها، سطح دسترسی ابزار را ارزیابی کرده و در صورت مجاز بودن، ابزار در سیستم ابزارها به اجرا درمی‌آید.
6. چرخه مجدد (Re-entrancy): خروجی ابزار به تاریخچه پیام‌ها پیوست شده و حلقه query.ts مجدداً مدل را با کانتکست به‌روزرسانی‌شده فراخوانی می‌کند. این چرخه تا زمانی که مدل هیچ فراخوانی ابزار جدیدی صادر نکند ادامه می‌یابد.

[ورودی REPL] │ ▼ [حلقه Query Loop (query.ts)] ──(تزریق حافظه)──► [سیستم حافظه (memdir/)] │ ▼ [کلاینت API مدل] ──(استریم پاسخ)──► [StreamingToolExecutor] │ │ │ (چرخه Re-entrant) ▼ (اجرای گمانه‌زنانه) └─────────────────────────── [سیستم ابزارها & لایه مجوزها]

تحلیل ۳ ویژگی کلیدی جریان داده

• کنترل فشار معکوس (Backpressure): رابط کاربر (REPL) پیام‌ها را از ژنراتور با استفاده از ساختار for await دریافت می‌کند. این امر باعث می‌شود که اگر UI توانایی پردازش سریع پیام‌ها را نداشته باشد، ژنراتور به‌طور خودکار منتظر مانده و از لگ یا بلاک شدن ترمینال جلوگیری کند.
• اجرای گمانه‌زنانه (Speculative Execution): هم‌پوشانی فراخوانی ابزارهای فقط-خواندنی با استریم مدل باعث می‌شود که زمان تاخیر شبکه به حداقل برسد؛ زیرا نتایج خواندن فایل معمولاً پیش از پایان استدلال متنی مدل آماده هستند.
• حلقه مجدد (Re-entrancy): هیچ فاز یا خط لوله مجزایی برای "مدیریت خروجی ابزار" وجود ندارد. نتایج ابزار مستقیماً به کانتکست اضافه می‌شوند و این خود مدل است که با صادر نکردن ابزار جدید، خاتمه حلقه را تعیین می‌کند.

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

۴. معماری سیستم مجوزها و سطح دسترسی (The Permission System)

اجرای دستورات شل، دستکاری فایل‌ها و برقراری ارتباطات شبکه‌ای توسط یک عامل هوش مصنوعی بدون سیستم دسترسی، یک فاجعه امنیتی محسوب می‌شود. سیستم مجوزها در Claude Code خط مرز میان یک ابزار کاربردی و یک ریسک امنیتی است.

زنجیره ارزیابی مجوزها (Permission Resolution Chain)

هنگامی که یک ابزار در خواست دسترسی صادر می‌کند، تصمیم‌گیری از طریق یک زنجیره ارزیابی ۴ گام و صریح انجام می‌شود:

[درخواست اجرای ابزار] │ ▼ [۱. ارزیابی قواعد قلاب‌ها (PreToolUse Hooks)] ──► (در صورت رد/تایید صریح، خروج سریع) │ ▼ [۲. بررسی مود فعال مجوز (Permission Mode)] ──► (تطبیق با مودهای ۷‌گانه) │ ▼ [۳. ارزیابی مدل طبقه‌بندی‌کننده (Transcript Classifier)] ──► (در مود auto) │ ▼ [۴. پرامپت تعاملی کاربر (User Prompt)] ──► (تایید یا رد نهایی توسط انسان)

این سیستم از ۷ مود امنیتی پشتیبانی می‌کند که به ترتیب از بیشترین به کمترین سطح دسترسی تنظیم شده‌اند:

جدول حالت‌های ۷‌گانه دسترسی (Permission Modes)

مود امنیتی (Mode) رفتار سیستم (Behavior) bypassPermissions تمامی دسترسی‌ها مجاز است. هیچ بررسی انجام نمی‌شود (صرفاً برای تست‌های داخلی). dontAsk تمامی دستورات اجرا می‌شوند، اما تمام اقدامات در لاگ ثبت می‌گردند. پرامپتی به کاربر نشان داده نمی‌شود. auto یک مدل طبقه‌بندی‌کننده (LLM Transcript Classifier) درباره مجاز یا غیرمجاز بودن تصمیم می‌گیرد. acceptEdits تغییرات و ویرایش فایل‌ها به صورت خودکار تایید می‌شوند؛ اما سایر عملیات جهش‌یافته نیازمند پرامپت هستند. default حالت تعاملی استاندارد. کاربر باید تک‌تک عملیات حساس را دستی تایید کند. plan حالت فقط-خواندنی (Read-only). تمام تغییرات و جهش‌ها روی دیسک مسدود می‌شوند. bubble تصمیم‌گیری به عامل والد (Parent Agent) ارتقا می‌یابد (مخصوص زیر-عامل‌ها).

تحلیل عمیق حالت Auto و Bubble

کارکرد مود auto

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

الزام زیر-عامل‌ها به مود bubble

زیر-عامل‌ها به‌طور پیش‌فرض روی مود bubble قرار دارند. این ساختار تضمین می‌کند که یک زیر-عامل نتواند به صورت پنهانی دستورات تخریبی یا تغییرات ناخواسته را روی سیستم اجرا کند؛ بلکه تمام درخواست‌های سطح دسترسی به عامل اصلی یا در نهایت به کاربر منتقل می‌شوند.

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

۵. معماری چندارائه‌دهنده و سیستم بیلد (Multi-Provider & Build System)

پشتیبانی از ارائه‌دهندگان مختلف ابری (از جمله Direct API، AWS Bedrock، Google Vertex AI و Foundry) بدون آلوده کردن منطق اصلی حلقه پرس‌وجو، یکی از چالش‌های مهم معماری سیستم است.

۵.۱. لایه انتزاع API مدل

سیستم با استفاده از یک تابع کارخانه‌ای به نام getAnthropicClient() کلاینت یکپارچه را بر اساس متغیرهای محیطی ثبت‌شده در STATE می‌سازد.

// شبه‌کد ساختار انتزاعی تابع کارخانه‌ای کلاینت function getAnthropicClient(): AnthropicClientWrapper { const provider = STATE.provider; // Direct, Bedrock, Vertex, Foundry

switch(provider) { case 'bedrock': return new AnthropicBedrockClient({ region: STATE.awsRegion }); case 'vertex': return new AnthropicVertexClient({ projectId: STATE.gcpProject }); default: return new AnthropicDirectClient({ apiKey: STATE.apiKey }); } }

[Direct API] [AWS Bedrock] [Google Vertex AI] [Foundry] │ │ │ │ └─────────────────┴─────────┬─────────┴──────────────────┘ ▼ getAnthropicClient() │ ▼ (Anthropic SDK Wrapper) │ ▼ callModel() │ ▼ حلقه اصلی query.ts

توابعی مانند callModel() و حلقه query.ts بدون اطلاع از سرویس‌دهنده فعال، صرفاً با یک اینترفیس واحد از Anthropic SDK تعامل دارند. تعیین ارائه‌دهنده در زمان راه‌اندازی انجام شده و در STATE ذخیره می‌شود؛ بنابراین تغییر ارائه‌دهنده نیازی به تغییر کد در حلقه عامل ندارد.

۵.۲. سیستم بیلد و تکنیک Feature Flags

Claude Code از ابزار bun:bundle و الگوی Feature Flag برای مدیریت قابلیت‌ها بهره می‌برد:

// وارد کردن شرطی ماژول‌ها توسط پرچم‌های قابلیت const reactiveCompact = feature('REACTIVE_COMPACT') ? require('./services/compact/reactiveCompact.js') : null

در زمان بیلد، تابع feature('FEATURE_NAME') به یک مقدار بولین ثابت (true یا false) تبدیل می‌شود. معماران سیستم هوشمندانه از require() پویا درون شرط استفاده کرده‌اند؛ زیرا برخلاف import() دینامیک که یک Promise برمی‌گرداند و باندلرها نمی‌توانند آن را در زمان بیلد حذف کنند، require() پویا تحت یک گارد ثابت کامپایل، به کامپایلر اجازه می‌دهد تا کدهای غیرفعال را کلاً از خروجی بیلد حذف کند (Dead Code Elimination).

داستان سورس‌مپ‌ها

علی‌رغم حذف موفق کدها از فایل اجرایی finale JavaScript، انتشار فایل‌های .js.map روی npm که حاوی فیلد sourcesContent بودند، باعث شد کد منبع TypeScript کامل—حتی مسیرهای کدی غیرفعال و داخلی—افشا گردد. همین مسئله امکان مهندسی معکوس دقیق سیستم را برای معماران نرم‌افزار فراهم ساخت.

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

۶. معماران پیشرفته هوش مصنوعی: الگوهای کاربردی و قابل انتقال (Apply This)

ارزش واقعی بررسی معماری Claude Code در بازتولید نرم‌افزار انحصاری نیست، بلکه در استخراج الگوهای ساختاری قابل انتقال (Transferable Patterns) به دیگر سیستم‌های ایجنتیک است.

۱. الگوی AsyncGenerator برای حلقه عامل

• توصیف الگوی معماری: استفاده از یک تولیدکننده ناهمگام به عنوان هسته اصلی حلقه عامل جهت استریم پیام‌ها و بازگرداندن خروجی نهایی تایپ‌شده.
• مسئله‌ای که حل می‌کند: در حلقه‌های مبتنی بر Callback یا Event Emitter، تشخیص زمان دقیق پایان کار عامل، دلیل خروج و مدیریت لغو عملیات بسیار مبهم و پیچیده است. الگوی AsyncGenerator با ارائه خروجی تایپ‌شده (Terminal) و متد .return()، کنترل جریان و لغو عملیات را شفاف می‌سازد.

۲. رابط ابزار خودتوصیف‌گر (Self-Describing Tool Interface)

• توصیف الگوی معماری: متمرکز کردن تمام خصوصیات منطقی، دسترسی، هم‌زمانی و رندرینگ درون ساختار خود ابزار.
• مسئله‌ای که حل می‌کند: قرار دادن منطق دسترسی و هم‌زمانی ابزارها درون ارکستریتور مرکزی، آن را به یک God Object تبدیل می‌کند که با افزودن هر ابزار جدید نیازمند دستکاری کدهای پایه است. ابزارهای خودتوصیف‌گر خطی مقیاس‌پذیر می‌شوند.

۳. تفکیک وضعیت زیرساختی از وضعیت واکنش‌پذیر

• توصیف الگوی معماری: جداسازی متغیرهای ثابت زیرساختی از متغیرهای تعاملی و بصری UI در دو سطح کاملاً مجزا.
• مسئله‌ای که حل می‌کند: واکنش‌پذیر (Reactive) کردن تمام متغیرهای سیستم باعث مصرف شدید حافظه، اشتراک‌گذاری بی‌مورد و رندرهای مجدد بی‌نهایت در UI می‌شود. تفکیک دوسطحی، هزینه پردازش را به شدت کاهش می‌دهد.

۴. مودهای سیستماتیک مجوز به جای بررسی‌های پراکنده

• توصیف الگوی معماری: ارزیابی تمام تصمیمات دسترسی امنیتی از طریق یک زنجیره رزولوشن واحد متمرکز بر مودهای مشخص (plan, default, auto, bypass).
• مسئله‌ای که حل می‌کند: پراکندگی شرط‌های if (isAllowed) در کدهای ابزارها منجر به بروز ثغور امنیتی و عدم یکنواختی دسترسی‌ها می‌شود. سیستم زنجیره‌ای متمرکز، ریسک‌های امنیتی را کنترل می‌کند.

۵. معماری عامل‌های بازگشتی از طریق تسک‌ها

• توصیف الگوی معماری: ساخت زیر-عامل‌ها به عنوان نمونه‌های جدید و کامل از همان حلقه اصلی query() با تاریخچه پیام مستقل.
• مسئله‌ای که حل می‌کند: ایجاد کدهای اختصاصی و استثنایی برای زیر-عامل‌ها باعث ناهماهنگی در رفتار و مدیریت خطا می‌شود. استفاده از حلقه یکسان باعث ارث‌بری تمام تضمین‌های ایزوله‌سازی و امنیتی والد می‌شود.

۷. نتیجه‌گیری و گام بعدی

معماری Claude Code نشان می‌دهد که یک عامل هوش مصنوعی قدرتمند در محیط تولید، فرثرات از یک پرامپت ساده و فراخوانی API است. هماهنگی میان ۶ مفهوم انتزاعی پایه، لایه امنیتی ۷‌میزانه، تفکیک مدیریت وضعیت و ساختار استریمینگ، سیستمی سریع، ایمن و قابل توسعه را شکل داده است.

گام بعدی

در فصل ۲: شروع سریع — پایپ‌لاین بوت‌استرپ (Starting Fast — The Bootstrap Pipeline)، به کالبدشکافی نحوه راه‌اندازی ۵ فازی این عامل و تکنیک‌های موازی‌سازی I/O خواهیم پرداخت که زمان شروع به کار برنامه را به زیر ۲۴۰ میلی‌ثانیه می‌رسانند.