اکثر آموزش‌های Claude Code آن را به‌عنوان یک code generator معرفی می‌کنند و روی نوشتن پرامپت تمرکز دارند. این تصویر، بخش عمده‌ی قدرت ابزار را نادیده می‌گیرد. آنچه Claude Code را از هر چت‌بات دیگری جدا می‌کند، تنظیم فایل CLAUDE.md، مدیریت context window و انتخاب هوشمندانه بین حالت interactive و autonomous است. این آموزش، همان نقاط را در یک پروژه‌ی واقعی بررسی می‌کند و اشتباهاتی را نشان می‌دهد که در پروژه‌های اعضای کامیونیتی بارها تکرار شده‌اند.

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

Claude Code یک ایجنت ترمینالی (Terminal Agent) است که مستقیماً به فایل‌سیستم و git دسترسی دارد. برخلاف چت معمولی Claude که صرفاً متن تولید می‌کند، این ابزار فایل می‌خواند، دستور bash اجرا می‌کند، تغییرات را روی پروژه اعمال می‌کند و commit می‌زند.

حلقه‌ی آژنتیک (Agentic Loop) چیست و چرا هسته‌ی Claude Code است#

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

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

دسترسی به فایل‌سیستم، git و اجرای دستور bash#

Claude Code در ترمینال اجرا می‌شود و به تمام فایل‌های پروژه دسترسی دارد. می‌تواند:

  • فایل‌ها را بخواند و محتوایشان را تحلیل کند
  • دستورات bash اجرا کند (npm install، pytest، lint و…)
  • فایل‌های جدید بسازد یا موجود را ویرایش کند
  • با git کار کند: branch بسازد، commit بزند و diff بگیرد

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

حالت interactive در برابر حالت autonomous — کدام برای کدام تسک#

در حالت interactive، Claude Code بین هر مرحله توقف می‌کند و از شما تأیید می‌خواهد. برای تسک‌های حساس — حذف فایل، تغییر schema دیتابیس، refactor بزرگ — این حالت ضروری است.

در حالت autonomous، ایجنت بدون توقف پیش می‌رود: فایل می‌خواند، تغییر می‌دهد، تست می‌زند و commit می‌کند. برای تسک‌های روتین مثل نوشتن تست یا اصلاح lint error، این حالت سرعت را چند برابر می‌کند.

مدل پیش‌فرض Claude Code، Claude 3.5 Sonnet است (در زمان نگارش این آموزش). با دستور /model می‌توانید به Opus سوئیچ کنید. Sonnet برای تسک‌های روزمره کافی و سریع‌تر است؛ Opus برای تسک‌های معماری‌محور خروجی باکیفیت‌تری می‌دهد.

آموزش Claude Code: نصب و اولین اجرای ایجنت در ترمینال#

Claude Code با npm نصب می‌شود و به Node.js نسخه‌ی LTS و یک API Key از Anthropic Console نیاز دارد. اولین تسک عملی شامل git init، نوشتن CLAUDE.md و اجرای یک refactor ساده روی پروژه‌ی واقعی است.

پیش‌نیازها: Node.js، API Key و نصب از طریق npm#

قبل از نصب، مطمئن شوید Node.js (نسخه LTS) روی سیستم نصب است. سپس یک API Key از Anthropic Console بگیرید. نصب از طریق npm انجام می‌شود؛ دستورات دقیق را در مستندات رسمی Claude Code بررسی کنید چون ممکن است تغییر کنند.

پس از نصب، در پوشه‌ی پروژه دستور claude را اجرا کنید. اگر API Key در محیط تنظیم نشده باشد، ابزار از شما می‌خواهد.

اولین تسک عملی: از init تا commit در یک پروژه‌ی واقعی#

مراحل اولین اجرا:

  1. در ترمینال به پوشه‌ی پروژه بروید: cd my-project
  2. دستور claude را اجرا کنید
  3. تسک را به‌صورت توصیفی بنویسید (نه دستور مستقیم)
  4. ایجنت فایل‌ها را می‌خواند و تغییرات را پیشنهاد می‌دهد
  5. خروجی دستورات اجراشده را بررسی کنید
  6. در حالت interactive، تأیید commit بدهید

الگوی branch-per-task — اشتباه پرهزینه‌ی کار بدون branch#

اگر ایجنت فایل‌ها را خراب کند و branch نداشته باشید، rollback دستی در پروژه‌ی چندفایلی بسیار دشوار است. الگوی صحیح: قبل از شروع هر تسک، یک branch جدید بسازید. ایجنت روی branch کار می‌کند و بعد از تأیید، merge می‌کنید.

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

فایل CLAUDE.md چگونه رفتار ایجنت را در هر پروژه تنظیم می‌کند؟#

فایل CLAUDE.md یک پیکربندی در ریشه‌ی پروژه است که به‌عنوان system prompt عمل می‌کند و رفتار ایجنت را در هر session تنظیم می‌کند. فایل‌های nested در زیرپوشه‌ها، فایل والد را override می‌کنند — این رفتار لایه‌ای، کلید اصلی کار با پروژه‌های بزرگ است.

نمای نزدیک از یک فایل پیکربندی در ادیتور که ایجنت هوشمند آن را به‌عنوان راهنمای رفتار خود می‌خواند.
فایل CLAUDE.md مثل نقشه‌ی راهی است که ایجنت پیش از هر اقدام مطالعه می‌کند.

ساختار لایه‌ای و اولویت‌بندی فایل‌های nested در زیرپوشه‌ها#

اگر در ریشه‌ی پروژه یک CLAUDE.md دارید و در پوشه‌ی src/components هم یک CLAUDE.md بگذارید، فایل nested اولویت دارد. ایجنت وقتی روی فایل‌های آن پوشه کار می‌کند، قوانین nested را اعمال می‌کند.

این لایه‌بندی برای پروژه‌های بزرگ ضروری است: قوانین عمومی در ریشه، قوانین ماژول‌محور در زیرپوشه‌ها.

الگوهای مؤثر: چه چیزی بنویسیم و چه چیزی ننویسیم#

در CLAUDE.md مؤثر بنویسید:

  • ساختار پروژه و الگوی import مورد استفاده
  • قوانین linting و formatting
  • الگوی error handling پروژه
  • دستورات تست و build
  • محدودیت‌های فنی (مثلاً «از class component استفاده نکن»)

ننویسید:

  • پرامپت‌های ChatGPT-style کوتاه و دستوری
  • توضیحات طولانی درباره‌ی خود پروژه
  • قوانینی که linting به‌صورت خودکار اعمال می‌کند

اشتباه رایج: کپی‌پیست پرامپت‌های ChatGPT-style به CLAUDE.md#

Claude به توضیح ساختار و reasoning chain بهتر پاسخ می‌دهد — برخلاف ChatGPT که پرامپت کوتاه‌تر می‌خواهد. به‌جای «این تابع را بنویس»، بگویید «این تابع را با در نظر گرفتن الگوی error handling موجود در فایل X بنویس و دلیل انتخاب این الگو را توضیح بده».

نمونه‌ی واقعی: در یک پروژه‌ی React + TypeScript، CLAUDE.md باید شامل الگوی import (path alias)، قوانین linting (eslint config)، و ساختار پوشه‌بندی باشد. ایجنت با خواندن این فایل، بدون پرامپت اضافی، کد را مطابق قوانین پروژه می‌نویسد.

MCP و اتصال ابزارهای خارجی به Claude Code#

MCP (Model Context Protocol) پروتکل متن‌باز Anthropic است که ابزارهای خارجی را به‌صورت استاندارد به Claude متصل می‌کند؛ از دیتابیس داخلی تا APIهای سفارشی. این پروتکل در نوامبر 2024 معرفی شد (نیازمند راستی‌آزمایی از مستندات رسمی).

معماری MCP: server، client و ابزارهای متصل#

معماری MCP از سه جزء تشکیل شده: server (ارائه‌دهنده‌ی ابزار)، client (Claude یا هر مدل زبانی که به MCP متصل است)، و ابزارها (توابعی که server expose می‌کند). هر server می‌تواند چندین ابزار ارائه دهد.

ساخت یک MCP server سفارشی برای دسترسی به دیتابیس پروژه#

الگوی عملی: server ساده‌ای بنویسید که schema دیتابیس را به Claude می‌دهد. ایجنت با خواندن schema، query صحیح می‌نویسد بدون اینکه شما هر بار ساختار دیتابیس را توضیح دهید.

برای شروع، مستندات رسمی MCP را بررسی کنید که لیست serverهای آماده (filesystem، database، API) را دارد.

تفاوت MCP با Tool Use معمولی (Function Calling)#

Function Calling یک قابلیت مدل است که ابزارهای از پیش تعریف‌شده را صدا بزند. MCP یک پروتکل استاندارد است که هر ابزار خارجی را به‌صورت plug-and-play به مدل متصل می‌کند. تفاوت اصلی: MCP بین‌مدل و بین‌سازمانی است؛ Function Calling معمولاً vendor-specific.

Claude Code بهتر است یا Cursor؟ مقایسه‌ی عملی در یک تسک واقعی#

Claude Code در ترمینال اجرا می‌شود و حلقه‌ی آژنتیک کامل دارد؛ Cursor در IDE است و autocomplete و chat درون‌متنی ارائه می‌دهد. این دو ابزار جایگزین هم نیستند، مکمل‌اند. بسیاری از توسعه‌دهندگان حرفه‌ای هر دو را هم‌زمان استفاده می‌کنند.

تفاوت ماهیت: ایجنت ترمینالی در برابر ویرایشگر آژنتیک#

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

مقایسه‌ی عملی refactor یک ماژول React: تعداد دورها و کیفیت خروجی#

برای refactor یک ماژول چندفایلی React، Claude Code معمولاً در یک session کامل کار می‌کند: فایل‌ها را می‌خواند، تغییرات را اعمال می‌کند، تست می‌زند و commit می‌کند. Cursor برای همین تسک نیاز به دخالت دستی بیشتر دارد چون حلقه‌ی آژنتیک کامل ندارد.

معیار Claude Code Cursor Copilot
محیط اجرا ترمینال IDE (VS Code fork) افزونه‌ی IDE
حلقه‌ی آژنتیک کامل (خواندن، اجرا، تست، commit) محدود (chat درون‌متنی) ندارد
دسترسی به git مستقیم غیرمستقیم ندارد
تسک تک‌فایلی overhead دارد سریع‌تر سریع‌تر
تسک چندفایلی ارجح نیاز به دخالت دستی نامناسب

نقش Aider و GitHub Copilot در این طیف#

Copilot تمرکزش بر autocomplete و پیشنهاد درون‌خطی است؛ نسخه‌های جدیدتر chat هم دارند اما حلقه‌ی آژنتیک کامل ارائه نمی‌دهد. Aider مثل Claude Code در ترمینال اجرا می‌شود و حلقه‌ی آژنتیک دارد، اما مدل‌های متنوع‌تری پشتیبانی می‌کند. مقایسه‌ی Copilot با Claude Code اشتباه رایج است؛ این دو در دو طیف کاملاً متفاوت قرار دارند.

نتیجه‌ی عملی: برای تسک‌های تک‌فایلی و autocomplete درون‌متنی، Cursor سریع‌تر است. برای تسک‌های چندفایلی، حلقه‌ی آژنتیک کامل و کار با git، Claude Code ارجح است.

مدیریت Context Window در پروژه‌های بزرگ: چالش شماره‌یک Claude Code#

Claude 3.5 Sonnet از پنجره‌ی بافت (Context Window) با ظرفیت 200 هزار توکن پشتیبانی می‌کند (به مستندات رسمی Anthropic مراجعه کنید). در پروژه‌های چندفایلی این ظرفیت سریع پر می‌شود و الگوی context budgeting با /compact و trim دستی ضروری است.

چه زمانی Context Window پر می‌شود و چه نشانه‌هایی دارد#

نشانه‌های پر شدن context: ایجنت شروع به فراموشی قوانین CLAUDE.md می‌کند، فایل‌های قبلاً خوانده‌شده را دوباره می‌خواند، و خروجی بی‌کیفیت بدون خطای واضح تولید می‌کند. این خطرناک‌ترین حالت است چون خطایی نمایش داده نمی‌شود و ممکن است ساعت‌ها با خروجی بی‌کیفیت کار کنید.

الگوی context budgeting: /compact، trim دستی و استراتژی‌های multi-session#

ابزار /compact خلاصه‌سازی خودکار context است. اما تنها ابزار نیست. استراتژی‌های عملی:

  • تسک را به sessionهای مجزا تقسیم کنید
  • هر session را با /compact شروع کنید
  • فایل‌های غیرمرتبط را از context خارج کنید
  • در پروژه‌های بالای 50 فایل، تسک را به subtaskهای کوچکتر بشکنید

این الگو در پروژه‌های اعضای کامیونیتی مکرر دیده شده: تقسیم تسک بزرگ به sessionهای کوچکتر، هر کدام با context تازه.

چرا پروژه‌های بزرگ با CLAUDE.md طولانی بدتر کار می‌کنند#

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

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

Claude Code برای تسک‌های تک‌خطی، پروژه‌های بدون git، و کارهایی که نیاز به بازخورد لحظه‌ای در IDE دارند مناسب نیست. در این موارد Cursor یا Copilot ارجح‌اند.

محدودیت‌های عملی: سرعت، هزینه و پیچیدگی تنظیمات اولیه#

overhead حلقه‌ی آژنتیک برای تسک‌های ساده‌ی یک‌خطی بی‌مورد است. اگر فقط یک خط کد نیاز دارید، autocomplete در IDE سریع‌تر است. هزینه‌ی هر session با Claude Code (مخصوصاً با Opus) برای تسک‌های کوچک توجیه اقتصادی ندارد.

جایگزین‌ها: چه ابزاری برای چه نوع تسکی#

  • Autocomplete درون‌فایلی: Copilot یا Cursor
  • تسک تک‌خطی: هر چت‌بات ساده
  • تسک چندفایلی با git: Claude Code
  • پروژه‌ی بدون version control: هیچ‌کدام — اول git init کنید

اشتباه رایج: استفاده از Projects در Claude.ai برای کدنویسی به‌جای Claude Code#

Projects در Claude.ai فقط context ثابت دارد و دسترسی به فایل‌سیستم یا اجرای دستور ندارد. برای کدنویسی واقعی، Claude Code ابزار درست است. استفاده از Projects برای تسک‌های کدنویسی چندفایلی، خروجی متنی تولید می‌کند که باید دستی copy-paste کنید.

هزینه‌ی استفاده: اشتراک Pro در برابر پرداخت بر اساس توکن API#

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

ساختار قیمت‌گذاری اشتراک Pro و Max#

اشتراک Pro برای استفاده‌ی سبک و گاه‌به‌گاه کافی است. Claude Max برای توسعه‌دهنده‌ای که روزانه چند ساعت با Claude Code کار می‌کند طراحی شده و limit بالاتری دارد. جزئیات سطوح و limitها را از صفحه‌ی قیمت‌گذاری رسمی Anthropic بررسی کنید.

محاسبه‌ی هزینه‌ی API بر اساس توکن: چه زمانی ارزان‌تر است#

اگر استفاده‌تان نامنظم است (مثلاً هفته‌ای یک‌بار پروژه‌ی بزرگ)، پرداخت API بر اساس توکن ارزان‌تر تمام می‌شود. اگر روزانه استفاده می‌کنید، اشتراک معمولاً به‌صرفه‌تر است.

انتخاب مدل (Sonnet در برابر Opus) و تأثیر مستقیم بر هزینه#

سوئیچ از Sonnet به Opus هزینه را افزایش می‌دهد اما تعداد دورهای لازم برای تسک‌های معماری‌محور را کاهش می‌دهد. نکته‌ی عملی: برای تسک‌های معماری‌محور (طراحی ساختار پروژه، انتخاب الگوی design pattern، تحلیل trade-off)، Opus با وجود هزینه‌ی بیشتر، در مجموع ارزان‌تر تمام می‌شود چون دورهای کمتری لازم است.

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

Claude Code ابزاری است که اگر درست تنظیم شود، جایگزین ساعت‌ها کار دستی می‌شود. سه تصمیم کلیدی که تفاوت ایجاد می‌کنند: اول، الگوی branch-per-task را از روز اول رعایت کنید. دوم، CLAUDE.md را کوتاه و ساختاریافته بنویسید، نه به‌عنوان پرامپت. سوم، context budgeting را جدی بگیرید — پر شدن context بدون خطای واضح، خطرناک‌ترین حالت است.

اگر می‌خواهید Claude Code را در پروژه‌های واقعی تمرین کنید و از تجربیات سایر توسعه‌دهندگان استفاده کنید، کامیونیتی پرداختی Claude در اسکول با دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» (53 جلسه، 6 فصل) دقیقاً همین کار را می‌کند — از تنظیم CLAUDE.md تا مدیریت context و ساخت ایجنت چندمرحله‌ای.