بزرگ‌ترین مدل، بهترین نتیجه را نمی‌سازد. این باور، هزینه‌ی بسیاری از تیم‌های فارسی‌زبان را بی‌دلیل بالا برده و کیفیت خروجی را پایین آورده است. آموزش Claude Code واقعی، معماری workflow است: مدل‌-routing، فایل حافظه‌ی CLAUDE.md، permission modes و اتصال MCP servers. الگوهایی که در محتوای فارسی کمتر دیده می‌شوند ولی در پروژه‌های تیمی، تفاوت محسوس ایجاد می‌کنند.

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

Claude Code یک ایجنت کدنویسی ترمینالی (terminal-based coding agent) است که فایل‌های پروژه را مستقیم می‌خواند، ویرایش می‌کند و دستور اجرا می‌دهد. برخلاف چت معمولی Claude که فقط متن تولید می‌کند، این ابزار در filesystem شما کار می‌کند، خروجی‌اش قابل اجراست و خودش نتیجه را بازبینی می‌کند.

تفاوت عملیاتی ساده است. در چت، کد را کپی می‌کنید، در IDE پیست می‌کنید، اجرا می‌کنید، خطا را دوباره به چت می‌برید. در Claude Code، ایجنت خودش فایل را باز می‌کند، تغییر می‌دهد، دستور build را اجرا می‌کند و نتیجه را می‌بیند. این چرخه‌ی بازخورد (feedback loop) است که workflow را اساساً عوض می‌کند.

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

Permission modes: لایه‌ی امنیتی که اکثر آموزش‌ها نادیده می‌گیرند#

Permission modes سه سطح دسترسی Claude Code تعریف می‌کنند: Plan mode فقط پیشنهاد می‌دهد و هیچ فایلی را تغییر نمی‌دهد، Auto-accept edits اجازه‌ی ویرایش فایل می‌دهد ولی اجرای دستور را می‌خواهد، و Full auto همه‌چیز را خودکار انجام می‌دهد. انتخاب سطح، مستقیماً ریسک پروژه را تعیین می‌کند.

در تیم‌های واقعی با CI/CD، اکثر ما از auto-accept edits استفاده می‌کنیم و full auto را فقط در محیط‌های ایزوله فعال می‌کنیم. دلیلش ساده است: یک دستور مخرب در full auto، بدون git، جبران‌ناپذیر است.

این را جدی بگیرید: هرگز Claude Code را در پروژه‌ای بدون git اجرا نکنید. بدون version control، تغییرات مخرب قابل بازگشت نیستند و ریسک از‌دست‌رفتن کد واقعی است. این هشدار در نتایج فارسی تقریباً وجود ندارد.

چطور Claude Code را نصب و راه‌اندازی کنم؟#

نصب Claude Code با یک دستور npm انجام می‌شود. پس از احراز هویت با API key یا subscription، ابزار به‌عنوان CLI در ترمینال در دسترس است. پیکربندی اولیه شامل انتخاب permission mode و اتصال MCP servers است.

پیش‌نیازهای دانشی قبل از نصب: آشنایی با terminal، Node.js و git. بدون git، هیچ راه بازگشتی ندارید. بدون Node.js، خودِ نصب انجام نمی‌شود.

  1. نصب: npm install -g @anthropic-ai/claude-code
  2. احراز هویت: اجرای claude در ترمینال و ورود با API key یا subscription
  3. انتخاب permission mode: متناسب با سطح ریسک پروژه
  4. اجرای اولین session در یک پروژه‌ی واقعی
  5. اولین commit با کمک Claude Code و بررسی diff

برای استفاده‌ی گرافیکی، Claude Code به‌عنوان VS Code extension هم قابل نصب است. اما terminal-native version برای پروژه‌های بزرگ‌تر و workflow‌های خودکار مناسب‌تر است. این را نه از مستندات، بلکه از مقایسه‌ی مستقیم دو نسخه در یک پروژه‌ی monorepo می‌توان دید.

CLAUDE.md و استراتژی مدل‌-routing: الگوی واقعی تیم‌های حرفه‌ای#

CLAUDE.md یک فایل حافظه‌ی پروژه‌ای (file-based memory) است که Claude Code در هر session می‌خواند. ترکیب آن با مدل‌-routing — یعنی orchestrator روی Sonnet و sub-tasks روی Haiku — هزینه را کاهش می‌دهد و کیفیت را حفظ می‌کند. این دو، ستون‌های معماری workflow هستند.

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

در CLAUDE.md فقط سه چیز بنویسید: conventions (قواعد کدنویسی پروژه)، architecture decisions (تصمیم‌های معماریی با دلیلشان) و forbidden patterns (الگوهای ممنوع). کد کامل، README تکراری و توضیحات عمومی را ننویسید.

Anti-pattern رایج: فایل بیش از حد بزرگ. CLAUDE.md بزرگ context window را می‌بلعد و نتیجه را بدتر می‌کند، نه بهتر. معمولاً چند صد خط کافی است. اگر فایل شما هزار خطی شده، دارید اشتباه می‌کنید.

مدل‌-routing: الگویی که Anthropic خودش به‌کار می‌برد#

مدل‌-routing یعنی وظایف را بین مدل‌های مختلف تقسیم کنید. Anthropic در سیستم تحقیقاتی چندایجنتی (multi-agent research system) خودش از همین الگو استفاده کرده: orchestrator روی Sonnet برای تصمیم‌گیری، sub-agents روی Haiku برای وظایف ساده‌تر.

Claude 3.5 Sonnet در benchmark SWE-bench امتیاز 49.0 درصد کسب کرد (June 2024) که در زمان انتشار بالاترین نمره‌ی گزارش‌شده بود. Claude Sonnet 4 بهبود محسوسی در همین benchmark نشان داده؛ برای ارقام دقیق، به مستندات Anthropic مراجعه کنید.

در عمل: یک وظیفه‌ی «refactor این module» را به Sonnet بدهید. وظیفه‌ی «rename این variable در 20 فایل» را به Haiku. هزینه‌ی دومین کار چند برابر کمتر از اولی است، با کیفیت قابل‌قبول.

Extended thinking چه زمانی ارزش هزینه‌ی اضافه دارد؟#

Extended thinking (بودجه‌ی تفکر تکمیلی) فقط برای وظایف تحلیلی، ریاضی و debugging پیچیده توجیه اقتصادی دارد. برای کدنویسی روتین مثل CRUD و boilerplate صرفاً هزینه‌ی اضافه است. تصمیم‌گیری بر اساس نوع وظیفه، نه وسواس.

تفکیک وظیفه ساده است: اگر خروجی نیاز به استدلال چندمرحله‌ای دارد، thinking budget فعال کنید. اگر الگویی را تکرار می‌کند، نه. نوشتن یک component React با props ساده، نیاز به thinking ندارد. پیدا کردن race condition در سیستم distributed، دارد.

نکته‌ی عملی مهم: حتی با context window استاندارد 200K توکن، مدل در پروژه‌های بزرگ دچار degradation می‌شود. تقسیم‌بندی وظیفه ضروری است، نه اختیاری. استراتژی‌های truncation و summarization را برای پروژه‌های بزرگ‌تر در نظر بگیرید.

MCP servers و ساخت ایجنت چندمرحله‌ای با Claude API#

MCP (Model Context Protocol) پروتکلی است که ابزارهای خارجی را به Claude متصل می‌کند. برای ساخت ایجنت چندمرحله‌ای، الگوی agent loop با tool use و structured output پایه‌ی کار است. بدون این الگو، MCP server فقط یک plugin گران‌قیمت است.

سه گره نورانی متصل به هم در فضای تاریک که جریان چندمرحله‌ای ایجنت‌ها را با خطوط درخشان داده‌ای نشان می‌دهد
هر گره یک مرحله‌ی مستقل است؛ نورهای بین آن‌ها همان پروتکل MCP است

تفکیک واقع‌بینانه: MCP servers filesystem، database و browser واقعاً workflow را تغییر می‌دهند. بقیه — آن‌هایی که در demoها می‌بینید — اغلب صرفاً نمایشی‌اند. قبل از اتصال هر server، بپرسید: آیا بدون این ابزار، وظیفه‌ی فعلی قابل انجام نیست؟ اگر جواب مثبت است، اتصال آن ارزش ندارد.

الگوی agent loop: orchestrator تصمیم می‌گیرد → tool call اجرا می‌کند → observation را می‌خواند → next step را مشخص می‌کند → در صورت خطا retry logic فعال می‌شود. این الگو را با structured output ترکیب کنید: JSON schema به‌جای free text، چون قابل parse و قابل اتوماسیون است.

اتصال MCP server به Claude Code در تنظیمات CLI انجام می‌شود. پیکربندی ساده است ولی تست در محیط ایزوله را فراموش نکنید — مخصوصاً اگر server دسترسی write به filesystem یا database دارد.

Claude Code در برابر Cursor، Windsurf و GitHub Copilot: کدام برای چه‌کاری؟#

Claude Code ایجنت ترمینالی است، Cursor IDE مبتنی بر AI و Copilot extension درون‌خطی. این‌ها مکمل‌اند نه جایگزین یکدیگر. انتخاب بستگی به workflow فعلی تیم دارد، نه به تبلیغات سازندگان.

ابزارنوع تعاملمقیاس‌پذیریمناسب برای
Claude Codeایجنت ترمینالی (multi-file)پروژه‌ی کاملrefactoring، debugging، automation
CursorIDE با AI درون‌خطیفایل فعال + contextکدنویسی روزمره، navigation
GitHub Copilotautocomplete درون‌خطیخط فعلیتکمیل سریع، boilerplate
Aiderایجنت CLI (open-source)پروژه‌ی متوسطتیم‌هایی که مدل‌های مختلف می‌خواهند

تصمیم واقعی در تیم‌های ایرانی: محدودیت شبکه و بودجه، انتخاب را تغییر می‌دهد. Claude Code به‌خاطر terminal-native بودن و نیاز نداشتن به GUI سنگین، در محیط‌های با منابع محدود عملی‌تر است. Aider به‌عنوان گزینه‌ی open-source، آزادی انتخاب مدل را می‌دهد ولی community کوچک‌تری دارد.

یک حقیقت که در مقایسه‌های عمومی نمی‌گویند: Claude Code مکمل IDE است نه جایگزین. debugging تعاملی، navigation کد و code review همچنان به IDE نیاز دارند. استفاده‌ی هم‌زمان Claude Code + Cursor، الگوی رایج در پروژه‌های واقعی است.

هزینه‌ی واقعی و نقطه‌ی شکست اقتصادی#

برای تیم‌های کوچک و پروژه‌های متوسط، subscription Claude Pro یا Max کافی است. از حجم مشخصی استفاده‌ی API، قیمت‌گذاری token-based مستقیم ارزان‌تر تمام می‌شود. نقطه‌ی شکست اقتصادی بستگی به الگوی استفاده دارد، نه فقط تعداد درخواست.

محاسبه‌ی عملی: چند session در روز × میانگین توکن هر session × 30 روز = هزینه‌ی ماهانه. اگر این عدد از قیمت subscription بیشتر شد، API مستقیم منطقی‌تر است. اگر کمتر بود، subscription ساده‌تر و قابل‌پیش‌بینی‌تر.

نقش مدل‌-routing در کاهش هزینه: Haiku برای sub-tasks، Sonnet برای orchestration. این ترکیب، هزینه را به‌شدت کاهش می‌دهد بدون افت محسوس کیفیت. اشتباه پرهزینه‌تر از آن است که به‌نظر می‌رسد: استفاده از بزرگ‌ترین مدل (Opus) برای همه‌چیز. هزینه‌ی بی‌دلیل، بدون بازدهی.

قیمت‌ها ممکن است تغییر کنند؛ برای ارقام دقیق به صفحه‌ی pricing Anthropic مراجعه کنید. اما الگوی تصمیم‌گیری ثابت می‌ماند: حجم استفاده × پیچیدگی وظیفه = انتخاب مدل و روش پرداخت.

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

پرامپت‌های بدون ساختار، یک‌بار‌نویسی بدون تکرار، عدم تقسیم وظیفه و اجرای خودکار بدون git، رایج‌ترین اشتباهاتی‌اند که نتیجه را خراب می‌کنند. پروژه‌های monorepo بزرگ و محیط‌های حساس امنیتی نقاط ضعف Claude Code‌اند.

Anti-pattern‌هایی که نتیجه را بدتر می‌کنند#

پرامپت طولانی‌تر = نتیجه‌ی بهتر، باور غلطی است. ساختار (نقش + محدودیت + مثال کوتاه) از پرامپت 500 کلمه‌ای بهتر عمل می‌کند. مدل‌ها در context شلوغ، الگوهای مهم را گم می‌کنند.

یک‌بار پرامپت بنویس و استفاده کن، اشتباه دوم است. prompt engineering فرآیند تکراری است. اولین نسخه‌ی پرامپت شما تقریباً همیشه نیاز به iteration دارد. session‌های کوتاه با feedback سریع، بهتر از یک session طولانی با پرامپت بزرگ است.

محدودیت‌های واقعی: چه‌زمانی سراغ ابزار دیگر بروید#

پروژه‌های monorepo بسیار بزرگ: latency بالا و degradation کیفیت خروجی. محیط‌های حساس امنیتی که اجرای خودکار کد ریسک دارد. workflow‌هایی که فقط به autocomplete نیاز دارند و ایجنت‌های چندمرحله‌ای اضافه‌اند.

در این موارد، Cursor یا Copilot مناسب‌ترند. Claude Code ابزار قدرتمندی است ولی ابزار همه‌کاره نیست. شناخت مرزهایش، بخشی از آموزش Claude Code حرفه‌ای است.

قدرت Claude Code در انتخاب بزرگ‌ترین مدل نیست، در معماری workflow است. مدل‌-routing، CLAUDE.md بهینه، permission modes هوشمند و تقسیم وظیفه، الگوهایی‌اند که هزینه را کم و کیفیت را بالا نگه می‌دارند. این‌ها را یاد بگیرید، بقیه ابزارها بهانه‌اند.

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