بسیاری از توسعه‌دهندگان Claude Code را یک رابط گفت‌وگویی (chat interface) پیشرفته‌تر می‌دانند و همین باور، هزینه‌ی پنهان یادگیری‌شان را چند برابر می‌کند. این ابزار یک مدل اجرایی (execution model) متفاوت دارد که بدون درک معماری حلقه‌ی ایجنتی و استراتژی بودجه‌بندی context، حتی با پرامپت‌های بهینه هم نتیجه‌ی قابل‌قبول نمی‌دهد.

Claude Code چه تفاوتی با chat interface معمولی دارد؟#

Claude Code یک حلقه‌ی ایجنتی (agentic loop) در terminal اجرا می‌کند: خواندن فایل، تصمیم‌گیری، ویرایش، اجرای دستور، و تکرار چرخه بدون دخالت کاربر. رابط گفت‌وگویی معمولی یک سؤال می‌گیرد و یک پاسخ متنی می‌دهد؛ Claude Code چند مرحله‌ی عملیاتی را در یک session کامل انجام می‌دهد.

آموزش Claude Code باید با درک همین حلقه شروع شود، نه با نوشتن پرامپت‌های بهتر.

معماری agentic loop: خواندن فایل، تصمیم‌گیری، ویرایش، اجرای test، تکرار#

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

وقتی دستوری مثل «این module را refactor کن» می‌دهید، Claude Code فایل را می‌خواند، ساختار آن را تحلیل می‌کند، ویرایش را اعمال می‌کند، test اجرا می‌کند، و در صورت شکست دوباره ویرایش می‌کند.

هر دور این حلقه token مصرف می‌کند — و اینجاست که اشتباه رایج شروع می‌شود: session‌های بدون checkpoint عملاً بودجه‌ی context را بی‌رویه می‌سوزانند و در میانه‌ی task به limit می‌رسند.

نقش CLAUDE.md به‌عنوان persistent instruction در پروژه#

فایل CLAUDE.md در ریشه‌ی پروژه قرار می‌گیرد و به‌عنوان دستورالعمل ماندگار (persistent instruction) در هر session بارگذاری می‌شود. conventions کدنویسی، ساختار پوشه‌ها، و قوانین test از پیش به مدل منتقل می‌شوند و نیازی به خواندن مجدد فایل‌ها نیست.

بدون CLAUDE.md، هر session از صفر شروع می‌کند و مدل باید دوباره فایل‌ها را بخواند. این یعنی صرف token برای بازیابی اطلاعاتی که قبلاً بارها خوانده شده.

قرار دادن خلاصه‌ی ساختار پروژه در CLAUDE.md عملاً بودجه‌بندی context (context budgeting) را از سطح session به سطح پروژه ارتقا می‌دهد — این را تقریباً همه‌ی کاربران حرفه‌ای که به‌مراحل بعدی رسیده‌اند، دیر کشف می‌کنند.

تفاوت model of execution با Cursor و Copilot#

تفاوت Claude Code با Cursor و Copilot در model of execution است: Claude Code حلقه‌ی ایجنتی در terminal اجرا می‌کند، Cursor پیشنهاد درون‌خطی (inline suggestion) در بافت کد فعلی ارائه می‌دهد، و Copilot تکمیل خودکار (autocomplete) در سطح خط کد انجام می‌دهد.

Cursor یک IDE است که inline suggestion در بافت کد فعلی ارائه می‌دهد. Copilot در سطح خط کد autocomplete انجام می‌دهد. Claude Code در سطح فایل و پروژه عمل می‌کند: چند فایل را هم‌زمان ویرایش می‌کند، دستور shell اجرا می‌کند، و خروجی آن را می‌خواند.

مقایسه‌ی این سه ابزار صرفاً بر اساس «چند درصد کد صحیح تولید می‌کند» گمراه‌کننده است. یک مدل execution را با یک مدل تولید متن نمی‌توان با benchmark یکسانی سنجید.

آموزش Claude Code: مراحل نصب و اولین session#

نصب Claude Code با npm انجام می‌شود، احراز هویت با اشتراک Claude Pro، Claude Max یا API key صورت می‌گیرد، و اولین session با اجرای دستور claude در ریشه‌ی پروژه شروع می‌شود. پیش‌نیاز اصلی Node.js و terminal با دسترسی به فایل سیستم است.

پیش‌نیازها: Node.js، حساب Anthropic، و terminal#

پیش از نصب Claude Code، سه چیز لازم است: Node.js نسخه‌ی LTS، حساب Anthropic با اشتراک فعال یا API key معتبر، و terminal با دسترسی خواندن و نوشتن به فایل سیستم پروژه. چون Claude Code مستقیماً فایل‌ها را ویرایش می‌کند، این دسترسی غیرقابل‌مذاکره است.

گام‌به‌گام نصب، احراز هویت و اجرای اولین session#

  1. با دستور npm install -g @anthropic-ai/claude-code ابزار را نصب کنید.
  2. دستور claude را در ریشه‌ی پروژه اجرا کنید.
  3. در اولین اجرا، صفحه‌ی احراز هویت باز می‌شود؛ با مرورگر به حساب Anthropic خود وارد شوید.
  4. پس از تأیید، session فعال می‌شود و می‌توانید اولین task را بنویسید.
  5. با /help دستورهای داخلی session را ببینید.

تنظیمات اولیه: model selection و permission flags#

Claude Code به‌صورت پیش‌فرض با Claude Sonnet کار می‌کند و برای تغییر مدل می‌توانید از flag مربوطه در session استفاده کنید. Permission flags تعیین می‌کنند که مدل برای هر ویرایش فایل یا اجرای دستور باید تأیید کاربر را بگیرد یا خیر.

گزینه‌ی --dangerously-skip-permissions تمام تأییدها را حذف می‌کند. این flag در پروژه‌های production خطرناک است. اگر واقعاً نیاز به خودکارسازی کامل دارید، حداقل در محیطی sandbox شده استفاده کنید.

اولین workflow عملی: refactor یک module با checkpoint#

اولین workflow عملی در Claude Code باید refactor یک module با دو یا سه فایل باشد، تقسیم‌شده به سه فاز: خواندن و توضیح ساختار، نوشتن proposal بدون ویرایش، و اعمال proposal با اجرای test. بین هر فاز خروجی را بررسی کنید تا مصرف token قابل‌پیش‌بینی بماند.

یک task کوچک انتخاب کنید: refactor یک module با دو یا سه فایل. به‌جای نوشتن یک پرامپت واحد، workflow را به فازها تقسیم کنید:

  1. فاز اول: «فایل X را بخوان و ساختار فعلی را توضیح بده».
  2. فاز دوم: «بر اساس توضیح قبلی، proposal refactor بنویس — هنوز فایل را ویرایش نکن».
  3. فاز سوم: «proposal را اعمال کن و test اجرا کن».

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

مدیریت context window و Extended Thinking در Claude Code#

مدیریت context window در Claude Code با تقسیم session به فازهای کوچک و بودجه‌بندی context انجام می‌شود، نه با نوشتن یک پرامپت واحد بلند. Extended Thinking token مصرفی و زمان پاسخ را افزایش می‌دهد و باید task-dependent فعال شود.

لایه‌های شفاف پنل‌های context که به صورت پشته‌ای و منظم در فضای تاریک معلق هستند
مدیریت لایه‌ای context window کلید پایداری workflow ایجنتی است

الگوی context budgeting: تقسیم task به فازهای قابل‌بررسی با checkpoint#

Context budgeting یعنی هر فاز یک سهم مشخص از بودجه‌ی context داشته باشد. task بزرگ را به زیرفازهایی بشکنید که هر کدام با خواندن یک یا دو فایل قابل‌حل باشند. بعد از هر فاز، خروجی را بررسی و تأیید کنید.

این الگو با راهنمایی‌های مستندات رسمی Anthropic درباره‌ی مدیریت session‌های طولانی هم‌راستا است. کاربران حرفه‌ای در کامیونیتی‌ها گزارش داده‌اند که بدون این الگو، session‌های طولانی اغلب در میانه‌ی task به limit context می‌رسند و کار نیمه‌کاره رها می‌شود.

Extended Thinking: چه زمانی ضروری و چه زمانی هزینه‌ی اضافی#

Extended Thinking مدل را وادار می‌کند قبل از پاسخ، reasoning داخلی انجام دهد. برای debugging شرط رقابتی (race condition)، تحلیل معماری چندلایه، یا taskهایی که چند وابستگی پنهان دارند، این قابلیت ضروری است.

برای refactor ساده، نوشتن کد قالبی (boilerplate) test، یا ویرایش‌های یک‌خطی، Extended Thinking فقط token اضافی مصرف می‌کند و زمان پاسخ را بالا می‌برد. فعال‌سازی آن باید task-dependent باشد، نه blanket.

استراتژی‌های فشرده‌سازی پرامپت و حذف context غیرضروری#

هر بار که فایل بزرگی را در context می‌گذارید، بخشی از بودجه‌ی session مصرف می‌شود. راهکارهای عملی:

  • به‌جای خواندن کل فایل، از grep یا head برای بخش‌های مرتبط استفاده کنید.
  • در CLAUDE.md خلاصه‌ی ساختار بنویسید تا مدل مجبور نباشد هر بار فایل‌ها را از صفر بخواند.
  • Session‌های قدیمی را با /clear پاک کنید و task جدید را در session تازه شروع کنید.
  • خروجی test را فقط در صورت نیاز به context برگردانید، نه به‌صورت خودکار.

مقایسه‌ی عملی رفتار در پروژه‌های Python/JS در برابر Rust/Go#

رفتار Claude Code در پروژه‌های Rust و Go به‌طور محسوسی متفاوت از Python و JavaScript است. در Python و JS، build system سبک است و خطاها سریع بازخورد می‌دهند؛ مدل معمولاً در یک یا دو دور ویرایش و test به نتیجه می‌رسد. در Rust و Go، هر ویرایش یک مرحله‌ی compile اضافه می‌کند و cargo و go mod باعث می‌شوند مدل در هر دور حلقه یک دستور build اجرا کند — session طولانی‌تر و مصرف token بالاتر.

در پروژه‌های Python و JavaScript، Claude Code معمولاً در یک یا دو دور ویرایش و test به نتیجه می‌رسد.

در پروژه‌های Rust و Go، context budgeting حیاتی‌تر است و فازها باید کوچک‌تر باشند. این تفاوت را بسیاری از کاربران Python که به Rust مهاجرت می‌کنند، نادیده می‌گیرند و بعد از چند session ناامید، ابزار را رها می‌کنند.

MCP و ساخت ایجنت خودکار با Claude Code#

Model Context Protocol (MCP) یک استاندارد متن‌باز client-server برای tool discovery است. نوشتن MCP server سفارشی به Claude Code اجازه می‌دهد ابزارهای داخلی سازمان را با schema validation فراخوانی کند. این صرفاً یک API wrapper نیست.

معماری MCP: client-server، tool discovery و schema validation#

در معماری MCP، یک server ابزارها را با schema تعریف‌شده ارائه می‌دهد. Claude Code به‌عنوان client این ابزارها را کشف و فراخوانی می‌کند. هر ابزار ورودی و خروجی type-safe دارد. اگر فراخوانی با schema مطابقت نکند، model به‌جای اجرای ناقص، خطا می‌گیرد.

SDKهای رسمی Anthropic برای نوشتن MCP server در Python و TypeScript موجودند. ساختار server شامل تعریف ابزارها، handlerهای هر ابزار، و transport layer است.

گام‌به‌گام نوشتن اولین MCP server سفارشی#

  1. SDK رسمی را با npm یا pip نصب کنید.
  2. یک فایل server بسازید و ابزار مورد نظر را با schema تعریف کنید.
  3. handler ابزار را پیاده‌سازی کنید: ورودی را بخوانید، منطق را اجرا کنید، خروجی را برگردانید.
  4. server را اجرا کنید و در تنظیمات Claude Code آدرس آن را ثبت کنید.
  5. در session جدید، ابزار کشف‌شده را با نام فراخوانی کنید.

Pattern ساخت ایجنت خودکار: Claude Code + MCP server + cron/CI trigger#

وقتی MCP server ابزارهای سازمانی (دیتابیس، API داخلی، سیستم ticket) را در اختیار Claude Code می‌گذارد، می‌توان workflow خودکار ساخت. یک cron job یا CI trigger session را شروع می‌کند، مدل task را اجرا می‌کند، و نتیجه را در سیستم مقصد ثبت می‌کند.

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

اکوسیستم MCP servers موجود#

مجموعه‌ای از MCP servers آماده برای ابزارهای رایج توسعه وجود دارد: filesystem، GitHub، database و ابزارهای monitoring. قبل از نوشتن server سفارشی، بررسی کنید که آیا نسخه‌ی آماده‌ای برای نیازتان وجود دارد.

پادترن‌هایی که کاربران حرفه‌ای Claude Code را خراب می‌کنند#

رایج‌ترین الگوهای ضد (anti-pattern) استفاده از Claude Code: پرامپت تک‌مرحله‌ای (one-shot prompt) به‌جای چند مرحله با checkpoint، توصیه‌ی «پرامپت بلندتر بنویس» در حالی که مشکل context management است، و استفاده از Opus برای همه‌ی tasks در حالی که Sonnet در بسیاری موارد بهینه‌تر است.

پادترن one-shot prompt#

پرامپت تک‌مرحله‌ای (one-shot prompt) که همه‌چیز را یکجا بخواهد، نتایج کم‌کیفیت‌تری از چند مرحله‌ی کوچک با checkpoint می‌دهد. دلیلش ساده است: در one-shot، مدل نمی‌داند آیا خروجی فاز اول درست است یا نه. اگر در میانه‌ی حلقه خطا کند، کل خروجی بی‌اعتبار می‌شود.

پادترن «فقط پرامپت بلندتر بنویس»#

مشکل اصلی context management است نه طول پرامپت. پرامپت بلندتر یعنی token بیشتر در هر دور حلقه، یعنی بودجه‌ی context سریع‌تر تمام می‌شود. اگر task به نتیجه‌ی درست نمی‌رسد، اول فازها را کوچک‌تر کنید، بعد پرامپت را.

پادترن انتخاب مدل#

استفاده‌ی blanket از Opus برای همه‌ی tasks پادترن است. Claude Sonnet برای refactor، نوشتن test، و ویرایش چندفایلی سرعت و هزینه بهینه‌تری دارد. Opus برای tasks پیچیده‌ی معماری و debugging چندلایه مناسب‌تر است. انتخاب مدل باید task-dependent باشد.

پادترن امنیتی: --dangerously-skip-permissions#

این flag تمام تأییدهای کاربر را حذف می‌کند. در پروژه‌ی شخصی با test coverage خوب شاید قابل‌قبول باشد، اما در پروژه‌ی team یا production ریسک بالایی دارد. جایگزین امن‌تر: استفاده از allowlist برای پوشه‌ها و دستورهای مجاز.

پادترن جایگزینی IDE#

Claude Code مکمل IDE است نه جایگزین آن. debugging visual، refactoring UI، و code navigation در IDE باقی می‌مانند. انتظار اینکه Claude Code همه‌ی کارهای IDE را انجام دهد، منجر به سرخوردگی و رها کردن ابزار می‌شود.

Claude Code در برابر Cursor، Copilot و Windsurf: مقایسه معماری و workflow#

مقایسه‌ی این ابزارها صرفاً بر اساس benchmark گمراه‌کننده است. تفاوت اصلی در model of execution است: Claude Code حلقه‌ی ایجنتی در terminal، Cursor inline suggestion در IDE، و Copilot autocomplete در خط کد. هر کدام جای مشخصی در workflow توسعه‌دهنده دارند.

جدول مقایسه‌ای: معماری، scope، نوع تعامل#

ابزار معماری Scope عمل نوع تعامل
Claude Code Agentic loop در terminal چند فایل + اجرای دستور + خواندن خروجی Task-based با checkpoint
Cursor IDE با AI layer فایل باز + بافت کد فعلی Inline suggestion + chat
Copilot Extension در IDE خط کد فعلی Autocomplete
Windsurf IDE با flow-based agent چند فایل در IDE Flow chain در محیط IDE

چه زمانی Claude Code گزینه‌ی بهتری است#

Claude Code زمانی گزینه‌ی بهتری است که task شامل ویرایش چندفایلی، اجرای test، و اصلاح خطا در یک چرخه باشد. وقتی می‌خواهید یک workflow تکراری را خودکار کنید. وقتی پروژه‌ی شما CLI-centric است و IDE نقش کمتری دارد.

چه زمانی Cursor یا Copilot بهترند#

برای کدنویسی تعاملی لحظه‌ای، debugging visual، refactoring UI، و code navigation، IDE با AI layer تجربه‌ی بهتری دارد. Claude Code این کارها را انجام نمی‌دهد و نباید انتظارش را داشت.

محدودیت‌های Claude Code#

پروژه‌های با فایل‌های binary (تصاویر، فایل‌های PDF) خارج از scope هستند. Build systemهای پیچیده session را طولانی می‌کنند. ویرایش‌های نیازمند درک بصری (layout، color) عملاً غیرممکن‌اند.

مدل قیمت‌گذاری#

Claude Code خود رایگان نصب می‌شود اما استفاده‌ی عملی از آن مستلزم اشتراک Claude Pro، Claude Max، یا پرداخت بر اساس token با API key است. Claude Max در دو tier با سهمیه‌ی استفاده‌ی بالاتر نسبت به Pro ارائه می‌شود. جزئیات قیمت و سهمیه در صفحه‌ی pricing رسمی Anthropic است.

جمع‌بندی: از نصب تا workflow پایدار#

Claude Code ابزار قدرتمندی است، اما فقط اگر execution model آن را درک کنید. حلقه‌ی ایجنتی، context budgeting، و انتخاب task-dependent مدل، سه ستون استفاده‌ی حرفه‌ای هستند. بدون این سه، ابزار همان chat interface است که فقط در terminal اجرا می‌شود.

اگر می‌خواهید این مفاهیم را در عمل و با پروژه‌های واقعی تمرین کنید، کامیونیتی پرداختی Claude در اسکول دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» را دارد که از setup اولیه تا ساخت ایجنت و workflow پیشرفته را پوشش می‌دهد.