اکثر توسعه‌دهنده‌ها Claude Code را مثل یک چت‌بات قدرتمند در ترمینال می‌بینند: سوال می‌پرسند، کد می‌گیرند، copy می‌کنند. این دیدگاه، ایجنت را به یک autocomplete گران‌قیمت تقلیل می‌دهد. bottleneck واقعی نه در کیفیت مدل، بلکه در درک نادرست حلقه‌ی ایجنتی (agentic loop) است؛ و پیامدش، خروجی‌ای بدتر از حالت بدون ایجنت است — چون بودجه‌بندی context (context budgeting) و CLAUDE.md نادیده گرفته می‌شوند.

Claude Code یک ایجنت است، نه چت‌بات — تفاوت معماری را بفهمید#

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

تفاوت بنیادین chat completion و حلقه‌ی ایجنتی#

در تکمیل گفتاری (chat completion)، مدل یک ورودی متنی می‌گیرد و یک خروجی متنی تولید می‌کند. چرخه تمام است. در حلقه‌ی ایجنتی، مدل به ابزارهایی مثل خواندن فایل، نوشتن فایل، اجرای shell command و جستجو در پایگاه کد (codebase) دسترسی دارد. خروجی مدل دیگر «متن پاسخ» نیست، بلکه «دستور بعدی» است. ایجنت دستور را اجرا می‌کند، نتیجه را می‌خواند و بر اساس آن تصمیم بعدی را می‌گیرد.

یک prompt ساده‌ی «این bug را fix کن» در Claude Code می‌تواند ده‌ها فایل را بخواند، چندین بار test اجرا کند و تا پاس شدن test ادامه دهد. در چت‌بات، همان prompt یک پاسخ متنی تولید می‌کند که ممکن است اصلاً قابل‌اجرا نباشد. تفاوت اینجاست: چت‌بات حدس می‌زند، ایجنت بررسی می‌کند.

استفاده از ابزار (tool use) در Claude Code: فایل‌سیستم، git و shell#

Claude Code به‌صورت built-in به سه دسته ابزار دسترسی دارد:

  • فایل‌سیستم: خواندن، نوشتن و ویرایش فایل‌ها با عملیات granular مثل search و replace.
  • Git: اجرای دستورهای git برای commit، diff و branch management.
  • Shell: اجرای هر command که در terminal قابل‌اجراست — از npm install تا docker build.

این ابزارها از زمان معرفی Claude Code به‌صورت built-in در دسترس هستند (Anthropic، فوریه 2025 به‌عنوان research preview). تفاوت اصلی با ابزارهای چت‌باتی این است که ایجنت خودش تصمیم می‌گیرد کدام ابزار را کی و با چه پارامتری فراخوانی کند — نه اینکه شما مراحل را یکی‌یکی بگویید.

چرا این تفاوت، نحوه‌ی prompt نوشتن را عوض می‌کند#

در چت‌بات، prompt باید self-contained باشد: تمام context لازم در خودِ پیام هست. در حلقه‌ی ایجنتی، ایجنت خودش context جمع می‌کند. پس prompt باید «هدف» را بگوید، نه «مراحل».

نوشتن «فایل X را بخوان، سپس تابع Y را تغییر بده، سپس test را اجرا کن» در Claude Code redundant است. ایجنت خودش این مراحل را طی می‌کند. prompt مؤثرتر: «تابع Y در فایل X باگ دارد، علت را پیدا کن و fix کن، سپس test را پاس کن.»

نصب و راه‌اندازی اولیه: از Homebrew تا اولین session#

Claude Code یک CLI است که با npm نصب می‌شود و برای اجرای اولیه به اشتراک Anthropic (Pro، Max یا API key) نیاز دارد؛ روی macOS و Linux به‌صورت native و روی Windows از طریق WSL کار می‌کند.

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

برای نصب، Node.js نسخه‌ی LTS لازم است. نسخه‌ی دقیق موردنیاز را در مستندات رسمی Anthropic بررسی کنید. علاوه بر Node.js، یک حساب فعال در platform.anthropic.com ضروری است. اشتراک Pro یا Max ساده‌ترین مسیر است؛ API key هم کار می‌کند اما هزینه بر اساس token مصرفی محاسبه می‌شود — که در پروژه‌های بزرگ، به‌سرعت از قیمت اشتراک عبور می‌کند.

دستور نصب و اولین session در پروژه#

  1. Node.js LTS را نصب و فعال کنید.
  2. دستور نصب Claude Code را از مستندات Anthropic اجرا کنید (معمولاً یک npm install global است).
  3. به پوشه‌ی پروژه‌ی خود بروید و دستور راه‌اندازی را اجرا کنید.
  4. احتمالاً از شما خواسته می‌شود که login کنید یا API key وارد نمایید.
  5. اولین prompt را بنویسید و ببینید ایجنت چه فایل‌هایی می‌خواند.

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

تفاوت رفتاری macOS و Linux (نکته‌ای که در docs نیست)#

روی macOS، Claude Code به‌صورت native در terminal کار می‌کند و دسترسی کامل به فایل‌سیستم دارد. روی Linux، بسته به distro و permissionهای فایل‌سیستم، برخی عملیات ممکن است نیاز به sudo داشته باشند یا با SELinux/AppArmor محدود شوند. روی Windows، WSL الزامی است و رفتار فایل‌سیستم بین Windows و Linux متفاوت می‌ماند.

اگر پروژه‌تان در Windows native است، WSL را به‌عنوان environment اصلی در نظر بگیرید. الگوی مشاهده‌شده در پروژه‌های اعضای کامیونیتی: توسعه‌دهنده‌های Windows که بدون WSL شروع می‌کنند، در اولین session با خطاهای permission مواجه می‌شوند و وقت زیادی صرف رفع مشکلات محیطی می‌کنند.

CLAUDE.md و مدیریت context: دو لایه‌ای که اکثر آموزش‌ها نادیده می‌گیرند#

CLAUDE.md فایل دستورالعمل پروژه است که به‌عنوان context دائمی در هر session بارگذاری می‌شود؛ مدیریت context window یعنی بودجه‌بندی token بین این فایل، کد خوانده‌شده و تاریخچه‌ی مکالمه. بدون این دو لایه، ایجنت در هر session از صفر شروع می‌کند.

ساختار بهینه‌ی CLAUDE.md: چه چیزی بنویسیم و چه چیزی ننویسیم#

CLAUDE.md باید شامل موارد زیر باشد:

  • معماری پروژه: ساختار پوشه‌ها، معماری ماژول‌ها، الگوهای طراحی (design pattern) اجباری.
  • قوانین کدنویسی: نام‌گذاری، formatting، الگوهای اجباری.
  • دستورات کلیدی: نحوه‌ی build، test، lint.
  • محدودیت‌ها: فایل‌هایی که نباید دست‌خورند، dependencies که نباید تغییر کنند.

ننویسید: توضیحات طولانی API، لیست تمام فایل‌ها (ایجنت خودش می‌خواند)، تاریخچه‌ی تصمیمات قدیمی. هر خط اضافه در CLAUDE.md در هر session مصرف token را بالا می‌برد. این یک اشتباه پرهزینه‌تر از آن است که به‌نظر می‌رسد: یک CLAUDE.md 500 خطی، در 20 session روزانه، 10,000 خط context بی‌فایده تزریق می‌کند.

چرا CLAUDE.md به‌جای system prompt ساده — معماری memory layer#

system prompt در چت‌بات‌ها یک‌بار در ابتدای مکالمه تزریق می‌شود. CLAUDE.md یک لایه‌ی حافظه‌ی دائمی است: در هر session، قبل از اولین prompt، بارگذاری می‌شود. ایجنت در طول session هم فایل‌ها را می‌خواند و هم CLAUDE.md را در memory نگه می‌دارد. یعنی اگر session جدیدی باز کنید، ایجنت بدون توضیح مجدد می‌داند پروژه چطور ساختار دارد.

الگوی context budgeting در پروژه‌های بزرگ#

پنجره‌ی context (context window) محدود است. در پروژه‌های بزرگ، اگر تمام کد را یکجا بخوانید، window پر می‌شود و ایجنت «فراموش» می‌کند — نه فراموشی واقعی، بلکه کاهش کیفیت پاسخ چون مدل tokenهای ابتدایی را در اولویت کمتری قرار می‌دهد.

الگوی مؤثر:

  1. CLAUDE.md را کوتاه و هدفمند نگه دارید (کمتر از 200 خط).
  2. ایجنت را فقط به فایل‌های مرتبط با task هدایت کنید.
  3. هر task بزرگ را به session جداگانه تقسیم کنید.
  4. بعد از هر task، session را reset کنید تا تاریخچه‌ی بی‌ربط مصرف token نکند.

اشتباه رایج: «هرچه prompt بلندتر بهتر» و هزینه‌ی token آن#

توسعه‌دهنده‌هایی که تازه با Claude Code کار می‌کنند، CLAUDE.md را با توضیحات exhaustive پر می‌کنند. نتیجه: در هر session، هزاران token صرف context ثابت می‌شود و بودجه‌ی باقی‌مانده برای کد واقعی کم است. اصل: CLAUDE.md نقشه‌ی راه است، نه کتاب مرجع.

در کلاس‌ها و پروژه‌های اعضای کامیونیتی، این اشتباه آنقدر مکرر است که به یک الگوی شناخته‌شده تبدیل شده: «اولین CLAUDE.md هر پروژه‌ای 800 خط است، دومین نسخه‌ی آن 150 خط.»

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

Claude Code در ترمینال کار می‌کند و بر حلقه‌ی ایجنتی تمرکز دارد؛ Cursor و Windsurf IDE مبتنی بر AI هستند و Copilot autocomplete درون IDE است. انتخاب ابزار به workflow فعلی تیم بستگی دارد، نه به «کدام قوی‌تر است» — و این پرسش، خودش پرسش اشتباهی است.

جدول مقایسه‌ای: محیط اجرا، مدل زبانی، نحوه‌ی تعامل، مناسب برای#

ابزار محیط اجرا نحوه‌ی تعامل مناسب برای
Claude Code Terminal (CLI) Agentic loop: ایجنت خودش فایل می‌خواند، کد می‌نویسد، test اجرا می‌کند Taskهای چندفایلی، refactoring، automation
Cursor IDE (VS Code fork) Chat درون IDE + code editing با AI توسعه‌ی روزمره با feedback سریع
GitHub Copilot Plugin در IDE Autocomplete و chat ساده تولید کد خطی، boilerplate
Windsurf IDE مبتنی بر AI Agentic flows درون IDE توسعه‌دهندگانی که IDE می‌خواهند ولی ایجنت

Claude Code vs Cursor: کی terminal بر IDE ترجیح دارد؟#

اگر task شما محدود به یک یا دو فایل است و می‌خواهید حین نوشتن feedback فوری بگیرید، Cursor سریع‌تر است. اگر task شما شامل خواندن ده‌ها فایل، اجرای test و تغییرات cross-cutting است، Claude Code مؤثرتر عمل می‌کند چون ایجنت خودش workflow را مدیریت می‌کند.

نکته‌ی عملی که کمتر جایی نوشته شده: بسیاری از توسعه‌دهنده‌های باتجربه هر دو را استفاده می‌کنند — Cursor برای coding روزانه، Claude Code برای taskهای بزرگ. این ترکیب، نه ضعف در انتخاب ابزار است نه ناکارآمدی؛ هر کدام در دامنه‌ی خودش بهترین است.

Copilot جایگزین ایجنت نیست — autocomplete با reasoning فرق دارد#

Copilot یک خط کد پیشنهاد می‌دهد. ایجنت یک task را تحلیل می‌کند، چندین فایل را می‌خواند، تصمیم می‌گیرد کجا تغییر بدهد، test اجرا می‌کند و نتیجه را بررسی می‌کند. این دو در سطوح متفاوتی از autonomy کار می‌کنند. مقایسه‌ی Copilot با Claude Code مثل مقایسه‌ی خودکار با راننده‌ی اتوماتیک است — و اگر کسی بگوید «Copilot کافی است»، احتمالاً هرگز task چندفایلی با ایجنت انجام نداده است.

MCP و اتصال به ابزارهای بیرونی#

Model Context Protocol (MCP) پروتکل متن‌بازی است که Anthropic معرفی کرد و به Linux Foundation پیوست؛ با آن می‌توان دیتابیس، APIها و ابزارهای سفارشی را به‌عنوان tool در اختیار Claude Code قرار داد.

اتصالات نورانی از هسته‌ی مرکزی به گره‌های ابزارهای بیرونی در فضای تاریک با نور حجمی
هر گره یک ابزار است و هر رشته یک پروتکل ارتباطی

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

MCP سه جزء دارد:

  • MCP Server: سرویسی که ابزارها را expose می‌کند. مثلاً یک server که به PostgreSQL وصل می‌شود و query capability می‌دهد.
  • MCP Client: سمت ایجنت (Claude Code) که serverها را کشف و فراخوانی می‌کند.
  • Tool Discovery: فرآیند dynamic که ایجنت در runtime متوجه می‌شود چه ابزارهایی در دسترس است.

این معماری یعنی Claude Code بدون تغییر کد خودش، ابزارهای جدید یاد می‌گیرد. فقط کافی است یک MCP server بنویسید یا از serverهای موجود استفاده کنید.

نمونه‌های عملی: اتصال به PostgreSQL، Notion و API داخلی#

سناریوی واقعی: یک MCP server که به دیتابیس production متصل است و فقط read-only query اجازه می‌دهد. ایجنت می‌تواند schema را بخواند، query بنویسد، نتیجه را تحلیل کند و بر اساس داده‌های واقعی تصمیم بگیرد. بدون MCP، این کار نیاز به paste کردن دستی نتایج در prompt دارد — و آن paste کردن، خودش یک context اضافه در window است.

چطور MCP server بنویسیم#

ساختار کلی یک MCP server شامل تعریف tools (نام، توضیح، schema ورودی/خروجی) و مدیریت connection است. برای شروع، مستندات رسمی MCP را در GitHub بررسی کنید. زبان‌های پشتیبانی‌شده معمولاً TypeScript و Python هستند.

یک نکته‌ی مهم که در tutorialها کمتر گفته می‌شود: هر tool‌ای که expose می‌کنید، در context window ایجنت ظاهر می‌شود. toolهای غیرضروری، token مصرف می‌کنند و ایجنت را گیج می‌کنند. اگر 15 tool دارید ولی task فعلی فقط به 2 tool نیاز دارد، آن 13 tool بقیه صرفاً نویز هستند.

حالت مجوز (permission mode)، تأیید خودکار (auto-approve) و ریسک‌های امنیتی در production#

Claude Code دستورات shell و تغییرات فایل را بر اساس permission mode تأیید می‌خواهد؛ auto-approve همه‌چیز را بدون سؤال اجرا می‌کند که در repoهای production ریسک حذف داده یا اجرای کد مخرب دارد.

سطوح permission: از read-only تا full auto-approve#

Claude Code سطوح permission دارد که از «فقط خواندن» تا «اجرای آزاد هر command» متغیر است. در حالت پیش‌فرض، ایجنت قبل از نوشتن فایل یا اجرای command تأیید می‌خواهد. auto-approve این تأییدها را حذف می‌کند.

اشتباه رایج: auto-approve در پروژه‌های production و ریسک واقعی آن#

توسعه‌دهنده‌ای که auto-approve را فعال می‌کند و سپس از ایجنت می‌خواهد «dependencyها را آپدیت کن»، ممکن است یک command مخرب اجرا شود. حتی بدون intent بد، ایجنت می‌تواند فایل‌های حساس را بازنویسی کند.

الگوی مشاهده‌شده در پروژه‌های اعضای کامیونیتی: auto-approve فقط در sandbox یا dev environment استفاده می‌شود، نه در repoهای با داده‌ی واقعی. و حتی در dev، بعد از هر session با auto-approve، git diff را بررسی کنید. یک session auto-approve در dev که فایل .env را بازنویسی کند، می‌تواند ساعت‌ها debugging بی‌نتیجه در staging به‌دنبال داشته باشد.

Best practice: auto-approve فقط در sandbox و dev environment#

  1. در پروژه‌های production، permission mode را روی «تأیید قبل از هر تغییر» نگه دارید.
  2. برای taskهای تکراری و کم‌ریسک در dev، auto-approve مجاز است.
  3. CLAUDE.md را طوری بنویسید که فایل‌های حساس (config، secrets، migration) به‌عنوان «ممنوع» علامت‌گذاری شوند.
  4. بعد از هر session با auto-approve، git diff را بررسی کنید.

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

Claude Code برای refactoring کد legacy با وابستگی‌های چرخه‌ای، پروژه‌های خیلی کوچک زیر 500 خط، و taskهایی که نیاز به reasoning چندگانه‌ی بدون context دارند، ابزار اشتباهی است و روش سنتی سریع‌تر نتیجه می‌دهد.

پروژه‌های legacy با coupling بالا — چرا ایجنت گم می‌شود#

ایجنت برای فهمیدن یک تابع، فایل‌های مرتبط را می‌خواند. در کد legacy با coupling بالا، «فایل‌های مرتبط» یعنی تقریباً کل پروژه. ایجنت در حلقه‌ی خواندن فایل گیر می‌کند، context پر می‌شود و نتیجه‌ی نهایی بی‌ربط است.

الگوی مشاهده‌شده: در این پروژه‌ها، ابتدا خودتان dependency graph را map کنید، سپس به ایجنت بگویید «فقط این 3 فایل را بخوان». این کار، ایجنت را از حلقه‌ی بی‌پایان نجات می‌دهد.

Taskهای یک‌خطی و ساده — overhead ایجنت بیشتر از صرفه‌اش است#

«این متغیر را rename کن» یک task یک‌خطی است. ایجنت برای آن یک session باز می‌کند، CLAUDE.md می‌خواند، فایل را پیدا می‌کند، تغییر را اعمال می‌کند. در IDE با find-and-replace، ده ثانیه طول می‌کشد.

Claude Code برای taskهایی مؤثر است که حداقل چند مرحله‌ی reasoning دارند. اگر task شما در ذهن خودتان یک‌خطی است، ایجنت هم آن را یک‌خطی انجام می‌دهد — ولی با 30 ثانیه overhead. ارزش ایجنت در taskهایی است که خودتان نمی‌دانید چند مرحله دارد.

Code review بدون context کافی و نتیجه‌گیری‌های نادرست (anti-pattern)#

اگر از ایجنت بخواهید «این PR را review کن» بدون اینکه فایل‌های مرتبط با تغییرات را مشخص کنید، ایجنت فقط diff را می‌بیند و ممکن است تغییراتی را که در context کلی پروژه منطقی‌اند، اشتباه علامت بزند. الگوی صحیح: فایل‌های تحت تأثیر را مشخص کنید، intent تغییر را بگویید، سپس review بخواهید.

چه taskهایی با Claude Code سریع‌ترند و چه taskهایی کندتر#

نوع task Claude Code روش سنتی
Refactoring cross-file سریع‌تر کندتر
نوشتن test suite جدید سریع‌تر کندتر
Debug با stack trace سریع‌تر (اگر context کامل بدهید) متغیر
Rename یک متغیر کندتر سریع‌تر
فهمیدن کد legacy بدون مستندات متغیر (وابسته به coupling) معمولاً سریع‌تر

الگوی workflow سه‌مرحله‌ای و بهینه‌سازی هزینه#

Workflow مؤثر Claude Code سه مرحله دارد: plan (نوشتن طرح در CLAUDE.md یا session)، execute (اجرای مرحله‌ای با تأیید)، verify (اجرای test و بازبینی خروجی). هزینه‌ی token مستقیماً به تعداد فایل‌های خوانده‌شده و طول تاریخچه‌ی session وابسته است.

مرحله‌ی plan: چرا نوشتن طرح قبل از اجرا، خروجی را قابل‌اعتمادتر می‌کند#

در مرحله‌ی plan، از ایجنت بخواهید قبل از نوشتن هر کدی، طرح بدهد: کدام فایل‌ها تغییر می‌کنند، چه توابعی اضافه یا حذف می‌شوند، ترتیب اجرا چیست. این طرح را بررسی و اصلاح کنید. سپس بگویید «حالا اجرا کن».

نتیجه‌ی عملی: ایجنت در مرحله‌ی execute منحرف نمی‌شود چون plan مشخصی دارد. الگوی مشاهده‌شده در پروژه‌های اعضای کامیونیتی: بدون plan، ایجنت در taskهای پیچیده «خلاقیت» نشان می‌دهد — یعنی مسیرهایی که شما نمی‌خواهید. و این «خلاقیت»، همان چیزی است که یک session 20 دقیقه‌ای را به یک session 2 ساعته‌ی بی‌نتیجه تبدیل می‌کند.

مرحله‌ی execute: task decomposition و استفاده از ایجنت فرعی (sub-agent)#

Task بزرگ را به sub-taskهای کوچک تقسیم کنید. هر sub-task یک session جداگانه دارد. این کار دو فایده دارد: context هر session کوچک می‌ماند (هزینه‌ی token پایین‌تر) و اگر یک sub-task شکست بخورد، بقیه sessionها آلوده نمی‌شوند.

Claude Code از sub-agentها پشتیبانی می‌کند که می‌توانند به‌صورت موازی روی بخش‌های مختلف کار کنند.

مرحله‌ی verify: اجرای test و بازگشت به plan در صورت خطا#

بعد از execute، ایجنت خودش test را اجرا کند. اگر test fail شد، به ایجنت بگویید «fail را تحلیل کن و fix کن» — نه «دوباره از اول بنویس». بازگشت به plan در صورت خطا یعنی: اگر مشکل از plan بود (نه از execute)، plan را اصلاح کنید و execute را دوباره اجرا کنید.

بهینه‌سازی مصرف token: compression، session reset و انتخاب مدل#

سه اهرم اصلی کاهش هزینه:

  • Session reset: بعد از هر task، session جدید باز کنید. تاریخچه‌ی sessionهای قبلی token مصرف می‌کند.
  • CLAUDE.md کوتاه: هر خط اضافه در هر session بارگذاری می‌شود.
  • انتخاب مدل: برای taskهای ساده، مدل سبک‌تر کافی است.

مقایسه‌ی رفتاری Claude 3.5 Sonnet و Claude 4 در taskهای coding#

در پروژه‌های اعضای کامیونیتی، الگوی مشاهده‌شده این است: Claude 4 در taskهایی که نیاز به reasoning چندمرحله‌ای دارند (مثلاً refactoring با وابستگی‌های پیچیده) عملکرد بهتری نشان می‌دهد. Claude 3.5 Sonnet در taskهای ساده‌تر، latency پایین‌تری دارد و برای iterative feedback (چند بار prompt و اصلاح) مناسب‌تر است.

انتخاب مدل به نوع task و حساسیت به latency بستگی دارد. برای taskهای coding روزمره، Claude 3.5 Sonnet معمولاً sufficient است — و این یعنی هزینه‌ی token پایین‌تر بدون افت محسوس کیفیت.

Claude Code ابزاری قدرتمند است که ارزش واقعی‌اش در درک معماری حلقه‌ی ایجنتی، مدیریت context با CLAUDE.md، و رعایت الگوی plan → execute → verify نهفته است. هرچه این سه لایه را بهتر مدیریت کنید، خروجی ایجنت قابل‌اعتمادتر و هزینه‌ی token پایین‌تر می‌شود.

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

برای دسترسی به این دوره و سایر جلسات عملی، کامیونیتی Claude را در اسکول ببینید.