اگر آموزش Claude Code را با این تصور شروع کنید که «یک autocomplete هوشمندتر است»، در همان جلسه‌ی اول شکست می‌خورید. تفاوت بنیادین این است که Claude Code به filesystem و shell دسترسی مستقیم دارد و در یک session چندگامی کار می‌کند، نه یک پیام و یک پاسخ. این مقاله از نصب تا ساخت ایجنت سفارشی با API، همین تفاوت عملیاتی را باز می‌کند.

Claude Code یک autocomplete نیست: مکانیزم ایجنت ترمینالی (Agentic Loop)#

Claude Code یک autocomplete نیست: حلقه‌ی ایجنت (Agentic Loop) مکانیزم داخلی آن است که مدل را در چرخه‌ی plan → execute → observe نگه می‌دارد. در هر دور، خروجی گام قبلی ورودی گام بعدی می‌شود. برخلاف چت stateless که هر پیام را جدا پردازش می‌کند، این چرخه state را بین گام‌ها حفظ می‌کند و اصلاح را در همان session انجام می‌دهد.

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

تفاوت بنیادین stateful و multi-step با چت stateless#

وقتی در چت از Claude بخواهید «این تابع را بنویس»، یک پاسخ تولید می‌کند و تمام. هیچ‌کدام از فایل‌های شما را نمی‌بیند، test اجرا نمی‌کند و نمی‌داند آیا کدش با بقیه‌ی پروژه سازگار است. Claude Code برعکس عمل می‌کند: اول filesystem را اسکن می‌کند، بعد plan می‌نویسد، بعد edit می‌زند، بعد test اجرا می‌کند و اگر fail شد، خودش اصلاح می‌کند.

این تفاوت فقط یک مسئله‌ی UX نیست — دقیق‌تر بگویم، یک مسئله‌ی هزینه است. در چت، اگر کد تولیدشده یک import غلط داشته باشد، شما متوجه می‌شوید و دوباره پرامپت می‌دهید. در Claude Code، همان test اجرا می‌شود، خطا خوانده می‌شود و اصلاح در همان session اتفاق می‌افتد. یعنی یک چرخه‌ی کامل با یک prompt.

مقایسه‌ی عملیاتی با Cursor، GitHub Copilot و Windsurf#

ابزارنحوه‌ی دسترسی به پروژهاجرای testحالت
GitHub Copilotفقط خط جاری و context اطرافخیرInline completion
CursorChat panel + inline completion، دسترسی محدود به فایلخیر (کاربر اجرا می‌کند)Stateless per prompt
Windsurfمشابه Cursor با flow کمی پیچیده‌ترمحدودNear-stateful
Claude Codeمستقیم به filesystem و shellبله، خودش اجرا و بازخوانی می‌کندStateful، multi-step

این جدول از یک مشاهده‌ی میدانی در پروژه‌های واقعی آمده: تیم‌هایی که از Cursor به Claude Code مهاجرت کردند، معمولاً بعد از دو هفته گفتند «دیگر نمی‌توانم برگردم» — نه به‌خاطر کیفیت پرامپت، به‌خاطر اینکه test را خودش اجرا و بازخوانی می‌کند. این چرخه‌ی خودکار، زمان بین «کد نوشتن» و «فهمیدن اینکه کد کار می‌کند» را حذف می‌کند.

چه‌زمانی agentic loop به‌درد می‌خورد و چه‌زمانی یک autocomplete کافی است#

اگر تسک شما «این کامپوننت را بنویس» است، Copilot یا Cursor سریع‌تر و ارزان‌تر تمام‌شان می‌دهد. حلقه‌ی ایجنت وقتی ارزش می‌آفریند که تسک چندفایلی باشد، نیاز به خواندن context داشته باشد، یا باید test پاس شود. یک قانون ساده: اگر تسک شما بیش از یک فایل را درگیر می‌کند و باید کار کند، Claude Code ابزار درست است.

آموزش Claude Code در ترمینال: نصب، پیکربندی و اولین پروژه#

آموزش Claude Code در ترمینال از یک دستور npm شروع می‌شود و به اتصال حساب Claude Pro یا Max می‌رسد. اولین تجربه‌ی مؤثر با نوشتن CLAUDE.md شکل می‌گیرد، نه با اولین پرامپت. بدون فایل راهنمای پروژه، حتی نصب صحیح هم خروجی قابل‌اتمام‌تر نمی‌دهد.

پیش‌نیازها و نصب گام‌به‌گام#

  1. Node.js نسخه‌ی 18 یا بالاتر نصب باشد.
  2. با npm install -g @anthropic-ai/claude-code نصب کنید.
  3. در ترمینال به دایرکتوری پروژه‌ی خود بروید.
  4. دستور claude را اجرا کنید.
  5. اولین بار از شما احراز هویت می‌خواهد.

نکته‌ای که در مستندات رسمی Anthropic هم آمده: در اوایل عرضه، Claude Code در Windows فقط از طریق WSL کار می‌کرد؛ اکنون پشتیبانی native از Windows هم اضافه شده است. اگر macOS یا Linux دارید، مستقیم در ترمینال native اجرا می‌شود.

اتصال به حساب Claude Pro یا Max#

Claude Code به اشتراک Claude Pro یا Claude Max (یا یک API key با پرداخت به‌ازای توکن) نیاز دارد. Pro برای استفاده‌ی سبک‌تر و Max برای حجم بالای session‌های agentic مناسب‌تر است. برای اعداد دقیق قیمت، صفحه‌ی قیمت‌گذاری Anthropic را چک کنید چون ممکن است تغییر کرده باشد.

اولین تسک در یک پروژه‌ی واقعی — نه Hello World#

اشتباه رایج: نصب می‌کنید، می‌گویید «یک فایل hello world بساز» و نتیجه‌ی خسته‌کننده می‌گیرید. Claude Code در پروژه‌های واقعی درخشان است. یک bug واقعی بردارید، یک feature کوچک اضافه کنید، یا یک refactor انجام دهید. اولین session را این‌طور شروع کنید: «این فایل را بخوان، bug را پیدا کن، اصلاح کن و test را اجرا کن.»

CLAUDE.md: مهم‌ترین اهرم کیفیت خروجی، نه پرامپت بهتر#

CLAUDE.md فایلی در ریشه‌ی پروژه است که conventions، تصمیمات معماری و الگوهای ممنوعه را تعریف می‌کند. بدون آن، هر session بدون حافظه‌ی پروژه شروع می‌شود و خروجی ناسازگار تولید می‌کند. این فایل در هر session به‌طور خودکار خوانده می‌شود و نقش anchor را بازی می‌کند.

ساختار پیشنهادی CLAUDE.md با مثال واقعی#

چرا CLAUDE.md مهم‌تر از پرامپت بهتر است؟ چون پرامپت فقط یک session را هدایت می‌کند، اما CLAUDE.md همه‌ی session‌ها را. یک CLAUDE.md مؤثر این بخش‌ها را دارد:

  • زبان و framework: «TypeScript با React 18، Tailwind CSS»
  • Conventions: «Named export استفاده کن، default export نه»، «فایل‌های کامپوننت با PascalCase»
  • ممنوعیت‌ها: «از any استفاده نکن»، «import به‌صورت relative نه alias»
  • دستور test: «برای اجرای تست از npm run test استفاده کن»
  • ساختار پوشه: توضیح مختصر اینکه هر پوشه چه‌کار می‌کند

این الگو را در پروژه‌های واقعی می‌بینید: تیم‌هایی که CLAUDE.md دقیق دارند، خروجی consistent می‌گیرند. تیم‌هایی که آن را خالی می‌گذارند، هر session یک سبک متفاوت تولید می‌کند و بعد باید خودشان unify کنند.

الگوی شکست: CLAUDE.md خالی یا کلی#

«کد تمیز بنویس» و «از best practice استفاده کن» در CLAUDE.md بی‌فایده است. Claude Code این جملات را نمی‌فهمد به‌عنوان دستور عملیاتی. باید مشخص باشد: «از async/await استفاده کن، نه .then()»، «هر کامپوننت حداکثر 150 خط»، «test‌ها در فایل جدا کنار کامپوننت». هرچه دقیق‌تر، خروجی قابل‌اتمام‌تر.

اتصال MCP Server به Claude Code برای دسترسی به ابزارهای خارجی#

Model Context Protocol (MCP) پروتکلی است که Anthropic معرفی کرد. با آن، Claude Code از ویرایش فایل فراتر رفته و به database، API، browser و deploy pipeline دسترسی پیدا می‌کند. بدون MCP، Claude Code فقط filesystem و shell در اختیار دارد و تسک‌های نیازمند داده‌ی بیرونی عملاً غیرقابل‌حل می‌مانند.

MCP چیست و چرا بدون آن Claude Code محدود به filesystem است#

MCP یک لایه‌ی ارتباطی بین مدل و ابزارهای خارجی است. مثل plugin system عمل می‌کند: یک MCP Server می‌نویسید یا از server‌های موجود استفاده می‌کنید، و Claude Code می‌تواند به آن‌ها tool call بزند. بدون این لایه، Claude Code نمی‌تواند query بنویسد، API صدا بزند یا در browser کار کند.

پیکربندی MCP Server در تنظیمات Claude Code#

مستندات رسمی Anthropic روش پیکربندی را توضیح داده است. به‌طور خلاصه: در فایل تنظیمات Claude Code، یک بخش mcpServers اضافه می‌کنید که نام server، command و arguments آن را تعریف می‌کند. بعد از restart، Claude Code ابزارهای آن server را در اختیار دارد.

مثال واقعی: اتصال به database برای query مستقیم#

در یک پروژه‌ی واقعی، تیمی MCP Server برای PostgreSQL نوشت. بعد از اتصال، Claude Code می‌تواند schema را بخواند، query بنویسد، اجرا کند و نتیجه را تفسیر کند. این یعنی تسک «این report را بساز» بدون نیاز به نوشتن کد ORM انجام می‌شود.

وقتی context window پر می‌شود: استراتژی‌های مدیریت تسک#

وقتی context window پر می‌شود، Claude Code اطلاعات اولیه را فراموش می‌کند و شروع به hallucinating در کد می‌کند. پنجره‌ی context (Context Window) Claude 3.5 Sonnet ظرفیت 200 هزار توکن دارد. راه‌حل: دستور /compact، تقسیم تسک بین چند session و استفاده از CLAUDE.md به‌عنوان anchor برای حفظ تصمیمات.

نشانه‌های پر شدن context و شروع hallucination#

نشانه‌ی واضح: Claude Code تابعی را import می‌کند که وجود ندارد، یا از متغیری استفاده می‌کند که قبلاً تعریف کرده ولی الان فراموش کرده. اگر کد تولیدشده با فایل‌های موجود سازگار نیست، احتمالاً context پر شده. این خطرناک‌تر از خطای compile است، چون خطا نمی‌دهد — کد نادرست و به‌نظر‌سازگار تولید می‌کند.

دستور /compact و زمان استفاده از آن#

دستور /compact خلاصه‌ای از session تا آن لحظه می‌سازد و context را آزاد می‌کند. زمان استفاده: وقتی تسک طولانی شده و حس می‌کنید خروجی‌ها دارند تکراری یا ناسازگار می‌شوند. اما /compact همه‌چیز را حفظ نمی‌کند — تصمیمات مهم را در CLAUDE.md بنویسید تا گم نشوند.

الگوی تقسیم تسک بزرگ بین چند session#

تسک بزرگ را به فاز «طراحی در چت» و فاز «اجرا در Claude Code» تقسیم کنید. در چت معماری و تصمیمات سطح‌بالا را بگیرید (stateless، ارزان‌تر). بعد در Claude Code پیاده‌سازی چندفایلی را انجام دهید. هر فایل یا هر module یک session جدا. این الگو در پروژه‌های واقعی بارها تکرار شده و مشکل context overflow را عملاً حل می‌کند.

Claude Code برای چه کارهایی مناسب نیست؟#

Claude Code برای چه کارهایی مناسب نیست؟ پروژه‌های با build system پیچیده (Bazel، Gradle با plugin‌های سفارشی)، نیاز به determinism بالا (kernel، embedded، firmware)، فایل‌های باینری و پروژه‌هایی که token budget محدود دارند — در این موارد یک autocomplete ساده یا ابزار سنتی بهتر جواب می‌دهد. اصرار بر استفاده‌ی همه‌جا‌به‌جا از Claude Code، هزینه‌ی پنهان دارد.

شرایط شکست و جایگزین‌های مناسب#

اگر پروژه‌ی شما 500 فایل TypeScript با 30 الگوی معماری مختلف دارد، context window حتی با /compact هم پر می‌شود. در این حالت، یک IDE با indexing محلی (مثل Cursor با codebase indexing) مناسب‌تر است. اگر تسک شما «این خط را اصلاح کن» است، Copilot سریع‌تر تمام‌تان می‌دهد.

اشتباه رایج: استفاده از Claude Code برای هر پروژه بدون ارزیابی fit#

توسعه‌دهنده‌ها معمولاً یا «همه‌چیز را در Claude Code می‌کنند» یا «اصلاً سراغش نمی‌روند». هر دو افراط است. قبل از شروع، بپرسید: آیا تسک چندفایلی است؟ آیا test باید پاس شود؟ آیا context پروژه مهم است؟ اگر پاسخ به هر سه بله است، Claude Code ابزار درست است. اگر فقط اولی بله است، autocomplete کافی است.

ساخت ایجنت کدنویسی با Claude API و tool use#

ساخت ایجنت کدنویسی با Claude API یعنی خودتان function calling و tool use schema را تعریف کنید و حلقه‌ی ایجنت را از صفر بسازید. این همان مکانیزمی است که Claude Code در ترمینال استفاده می‌کند، اما با کنترل کامل روی ابزارها، محدودیت‌های دسترسی و هزینه‌ی هر token.

تفاوت استفاده از Claude Code (جعبه‌ی آماده) با ساخت ایجنت سفارشی (API)#

Claude Code یک محصول آماده است: نصب می‌کنید، اجرا می‌کنید، کار می‌کند. ایجنت سفارشی با API یعنی شما خودتان loop را می‌سازید، ابزارها را تعریف می‌کنید، policy دسترسی را تعیین می‌کنید و UI را می‌سازید. Claude Code برای بخش عمده‌ای از توسعه‌دهنده‌ها کافی است. ایجنت سفارشی وقتی لازم است که نیاز به integration خاص، محدودیت دسترسی granular یا deploy در محیط ایزوله دارید.

الگوی agentic loop در API: plan → execute → observe → iterate#

ساختار کد یک ایجنت ساده:

  1. به مدل تسک بدهید و بخواهید plan تولید کند.
  2. Plan را به tool call‌های مشخص ترجمه کنید.
  3. هر tool call را اجرا کنید و نتیجه را به مدل برگردانید.
  4. مدل نتیجه را می‌خواند و گام بعدی را تعیین می‌کند.
  5. تا زمانی که مدل بگوید تسک تمام شده، loop ادامه دارد.

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

جمع‌بندی عملی#

Claude Code یک autocomplete نیست؛ یک ایجنت ترمینالی است که خودش plan می‌کند، اجرا می‌کند و نتیجه را بازخوانی می‌کند. مهم‌ترین اهرم کیفیت خروجی، نوشتن CLAUDE.md دقیق است، نه پرامپت بهتر. وقتی context پر شود، /compact و تقسیم تسک نجات‌دهنده‌اند. و وقتی پروژه‌ی شما پیچیده‌تر از یک فایل است، این ابزار تفاوت واقعی ایجاد می‌کند.

اگر می‌خواهید این مسیر را از صفر و بدون کدنویسی طی کنید — از نصب Claude Code تا ساخت ایجنت و Vibe Coding — دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» در کامیونیتی اسکول را ببینید. 53 جلسه است و مسیر را مرحله‌به‌مرحله پوشش می‌دهد.