اگر آموزش Claude Code را چت‌بات‌وار پیش ببرید — یک پرامپت بدهید، خروجی را کپی کنید و بروید — ظاهراً همه‌چیز درست است. ولی دقیقاً در حالت‌های لبه‌ای (edge case) همان کد می‌شکند. مهارت واقعی با Claude Code، تفکر معماری است نه انتخاب مدل قوی‌تر.

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

Claude Code یک ایجنت کدنویسی مبتنی بر ترمینال است که با دستورهای CLI، فایل‌های پروژه و ابزارهای خارجی تعامل می‌کند. جایگزین کامل IDE نیست؛ در وظایف تک‌مرحله‌ای ساده، ابزارهای سبک‌تر مثل autocomplete در Cursor سریع‌تر و ارزان‌ترند.

تفاوت بنیادین با چت‌بات معمولی در «عاملیت» است. چت‌بات متن تولید می‌کند و تمام. Claude Code فایل می‌خواند، دستور سیستمی اجرا می‌کند، خروجی را می‌بیند و بر اساس آن تصمیم بعدی می‌گیرد. یک حلقه‌ی بازخورد واقعی، نه یک پاسخ یک‌طرفه. اما همین قدرت عاملیت، دام‌های خاص خودش را دارد. وقتی پروژه‌ای ساختار مشخصی ندارد و CLAUDE.md نوشته نشده، Claude Code هر بار از صفر حدس می‌زند. نتیجه: کدهایی که در بیشتر مسیرهای معمول کار می‌کنند و در همان‌جایی که به‌شان نیاز دارید — edge case‌ها — می‌شکنند.

معماری ایجنت‌محور در مقابل چت‌بات معمولی#

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

چه زمانی سراغ ابزار دیگری برویم؟#

  • ویرایش تک‌خطی در یک فایل کوچک: autocomplete در Cursor سریع‌تر است.
  • پروتوتایپ‌سازی بصری با UI: ابزارهای visual-first مناسب‌ترند.
  • وظایف بدون نیاز به اجرای کد: چت‌بات معمولی Claude کافی است.
  • پروژه‌ی بدون ساختار و بدون CLAUDE.md: ابتدا ساختار را تعریف کنید، بعد سراغ Claude Code بروید.

اشتباه رایج در کلاس‌ها و گفتگوهای اعضا: معرفی Claude Code به‌عنوان «جایگزین کامل IDE». این ابزار مکمل ویرایشگر است، نه رقیبش. بدون درک ساختار پروژه و بدون CLAUDE.md، خروجی‌هایش ضعیف و ناپایدار می‌شوند.

نصب و راه‌اندازی Claude Code در پروژه‌ی واقعی#

Claude Code از طریق npm با بسته‌ی @anthropic-ai/claude-code نصب می‌شود و به Node.js و اشتراک فعال Anthropic نیاز دارد. اولین اجرای پروژه بدون CLAUDE.md، خروجی ضعیف‌تری نسبت به اجرای همان دستور در پروژه‌ی آماده‌شده می‌دهد — چون مدل مجبور است خودش ساختار را حدس بزند.

پیش‌نیازها#

  • Node.js نسخه‌ی LTS به بالا
  • اشتراک فعال Claude Pro یا Max از Anthropic
  • دسترسی به ترمینال (Terminal) در سیستم‌عامل
  • پروژه‌ای با ساختار مشخص — حتی اگر ساده باشد

گام‌های نصب و اولین اجرا#

  1. نصب بسته با دستور npm install -g @anthropic-ai/claude-code
  2. احراز هویت با اجرای دستور claude و ورود به حساب Anthropic از طریق مرورگر
  3. رفتن به ریشه‌ی پروژه و اجرای دستور claude
  4. ایجاد اولین CLAUDE.md با ساختار معماری و قراردادها
  5. اجرای اولین وظیفه و مقایسه‌ی خروجی با حالت بدون CLAUDE.md
نکته‌ی عملی که در جلسات آموزشی مکرر تکرار می‌شود: اگر اولین دستور را در پروژه‌ای بزنید که CLAUDE.md ندارد، Claude Code باید خودش فایل‌ها را کاوش کند. این کاوش توکن مصرف می‌کند و گاهی نتیجه‌اش ساختار اشتباهی است که بعداً باید اصلاح شود. پنج دقیقه نوشتن CLAUDE.md، در هر نشست کاری (session) چندین دقیقه کاوش بیهوده را حذف می‌کند.

CLAUDE.md: ساختار حافظه‌ی پروژه را چطور بنویسیم؟#

فایل CLAUDE.md یک فایل Markdown در ریشه‌ی پروژه است که Claude Code در شروع هر session آن را می‌خواند و به‌عنوان بافت دائمی (Persistent Context) استفاده می‌کند. بدون این فایل، مدل هر بار از صفر ساختار پروژه را حدس می‌زند و خروجی‌ها پراکنده و ناپایدار می‌شوند.

این فایل فرعی نیست؛ ستون فقرات یادگیری پروژه است. هر بار که Claude Code را اجرا می‌کنید، اولین کارش خواندن CLAUDE.md است. هرچه این فایل دقیق‌تر باشد، خروجی‌ها منسجم‌تر و مصرف توکن کمتر.

بخش‌های ضروری#

  • Architectural Decisions: چرا این ساختار انتخاب شده، نه آن یکی. مثلاً «مدیریت state با Zustand انجام می‌شود چون Redux برای این مقیاس سنگین است».
  • Coding Conventions: قراردادها — نام‌گذاری، ساختار پوشه‌ها، الگوی import.
  • Known Pitfalls: اشتباهات شناخته‌شده — مثلاً «فایل utils/helpers.ts را ویرایش نکنید، فقط utils/core.ts را تغییر دهید».
  • Test Strategy: چطور تست بنویسید و کجا اجرا شود.

الگوی عملی با نمونه‌ی واقعی#

یک CLAUDE.md مؤثر، حداکثر ۲۰۰ تا ۳۰۰ خط است. نه بیشتر. الگوی مشاهده‌شده در پروژه‌های اعضای کامیونیتی: فایل‌های بلندتر از ۴۰۰ خط عملاً غیرقابل‌استفاده‌اند چون مدل فقط ابتدای فایل را به‌خاطر می‌سپارد و بخش‌های میانی و انتهایی را نادیده می‌گیرد.

اشتباه رایج: نادیده‌گرفتن CLAUDE.md و سپس شکایت از اینکه «Claude پروژه‌ام را نمی‌شناسد». این بافت را شما باید بسازید، نه مدل. مدل نمی‌تواند ذهن‌خوانی کند. برای درک عمیق‌تر مدیریت حافظه‌ی ایجنت، مقاله‌ی مرتبط در اسکول را ببینید.

مدیریت بافت و ساخت ایجنت چندمرحله‌ای#

پنجره‌ی بافت (Context Window) مدل‌های Claude حدود ۲۰۰ هزار توکن است، اما پر کردن آن با کل کدبیس نتیجه‌ی عکس می‌دهد. استراتژی صحیح، انتخاب هوشمند فایل‌های مرتبط و خلاصه‌سازی دوره‌ای مکالمه است — نه انباشت بی‌ساختار.

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

استراتژی Context Compression و دستور /compact#

وقتی مکالمه طولانی می‌شود و توکن‌ها نزدیک پر شدن پنجره می‌رسند، Claude Code دستور /compact را ارائه می‌دهد. این دستور خلاصه‌ای از مکالمه‌ی قبلی می‌سازد و بافت را فشرده می‌کند. اما خلاصه‌سازی همیشه بی‌ضرر نیست؛ جزئیات فنی دقیق ممکن است از بین بروند.

استراتژی بهتر: قبل از /compact، تصمیمات کلیدی را در CLAUDE.md بنویسید تا در session بعدی هم موجود باشند. /compact برای مکالمه است، CLAUDE.md برای دانش دائمی.

چرخه‌ی Plan → Act → Verify#

الگوی ایجنت‌محور واقعی سه مرحله دارد:

  1. Plan: Claude Code خودش مراحل را تعریف می‌کند. شما هدف را می‌دهید، نه دستورالعمل.
  2. Act: اجرا — نوشتن کد، اجرای دستور، خواندن خروجی.
  3. Verify: بازبینی — اجرای تست، مقایسه‌ی خروجی با انتظار.
Claude Code خودش مستقیماً کد می‌نویسد و دستور اجرا می‌کند؛ در وظایف موازی می‌تواند ایجنت‌های فرعی (sub-agents) یا ابزارهای خارجی را هم فراخوانی کند. اگر این چرخه را به‌عنوان یک پرامپت یک‌خطی ساده‌سازی کنید، خروجی‌ها ظاهراً درست ولی شکست‌خور می‌شوند. اشتباه رایج: چسباندن کل کدبیس به بافت. مدل با ۲۰۰ هزار توکن ظرفیت، لزوماً ۲۰۰ هزار توکن را به‌خوبی پردازش نمی‌کند. فایل‌های نامرتبط، نویز تولید می‌کنند و دقت را پایین می‌آورند.

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

Claude Code در refactoring چندفایلی، کار با فایل‌های بزرگ و ایجنت‌سازی چندمرحله‌ای برتری دارد. Cursor در autocomplete حین تایپ و ویرایش‌های سریع تک‌فایلی مناسب‌تر است. این دو مکمل‌اند نه رقیب — انتخاب بینشان به نوع وظیفه بستگی دارد، نه به «بهتر بودن» مطلق.

سناریوهای برتری Claude Code#

  • Refactoring که چند فایل و چند لایه را درگیر می‌کند
  • اجرای تست و بازبینی خودکار نتیجه
  • تعامل با ابزارهای خارجی از طریق MCP
  • کار با فایل‌های بزرگ که در IDE ویرایششان کند است

سناریوهای برتری Cursor و GitHub Copilot#

  • Autocomplete حین تایپ در ویرایشگر
  • ویرایش سریع یک خط یا یک تابع
  • پروژه‌های کوچک که نیاز به orchestration ندارند
معیار Claude Code Cursor GitHub Copilot
جریان کاری ترمینال‌محور، ایجنت‌محور IDEمحور، تعاملی IDEمحور، autocomplete
مدل‌های پشتیبانی‌شده مدل‌های Anthropic چندین مدل (OpenAI، Anthropic و…) مدل‌های OpenAI
مدیریت بافت CLAUDE.md + /compact Context در IDE Context محدود به فایل باز
مناسب برای Refactoring چندفایلی، ایجنت‌سازی ویرایش سریع، autocomplete تکمیل کد، پیشنهاد خط بعدی
هزینه اشتراک Anthropic + مصرف توکن اشتراک ماهانه اشتراک GitHub Copilot
مقایسه‌ی کامل ابزارهای AI کدنویسی در اسکول توضیح داده شده است.

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

پروتکل Model Context Protocol (MCP) توسط Anthropic در نوامبر ۲۰۲۴ معرفی شد و به‌عنوان استاندارد باز برای اتصال مدل‌های زبانی به ابزارها و منابع داده طراحی گردیده است. Claude Code به‌صورت بومی از این پروتکل پشتیبانی می‌کند و بدون آن، هر اتصال خارجی باید دستی در بافت تعریف شود.

MCP چیست و چه مسئله‌ای را حل می‌کند؟#

بدون MCP، هر بار که می‌خواهید Claude Code به دیتابیس، API داخلی یا سرویس خاصی دسترسی پیدا کند، باید آن دسترسی را دستی در بافت تعریف کنید. این روش مقیاس‌پذیر نیست. MCP یک لایه‌ی استاندارد بین مدل و ابزار می‌سازد: ابزار یک MCP Server می‌نویسد، مدل از طریق پروتکل با آن تعامل می‌کند.

یکپارچه‌سازی ابزارهای خارجی#

الگوی مشاهده‌شده در پروژه‌های واقعی: اتصال MCP server به دیتابیس پروژه، تا Claude Code بدون بافت‌نویسی دستی، schema را بفهمد. نتیجه: پرس‌وجوهای دقیق‌تر، migration‌های امن‌تر و کاهش خطای انسانی در نوشتن کوئری.

نکته‌ی مهم: MCP هنوز در حال تکامل است. قبل از استفاده در محیط production، مستندات رسمی Anthropic را بررسی کنید و از نسخه‌های پایدار MCP Server استفاده نمایید. آموزش ساخت MCP server در اسکول پوشش داده شده است.

هزینه‌ی واقعی و اشتباهات پرهزینه‌ی کاربران#

هزینه‌ی یک session کاری چندتورنی با Claude Code، چند برابر یک مکالمه‌ی چت‌باتی ساده است. مهم‌ترین اشتباهات پرهزینه: استفاده‌ی بی‌دلیل از Opus برای وظایف سبک، و تکرار پرامپت بدون اصلاح بافت — هر دو مستقیماً توکن‌های اضافی مصرف می‌کنند.

هزینه‌ی تجمعی session در مقابل هزینه‌ی چت‌باتی#

در چت‌بات، شما یک پرامپت می‌دهید و یک پاسخ می‌گیرید. در Claude Code، هر «تور» شامل خواندن فایل، نوشتن کد، اجرای دستور و بازبینی خروجی است. هر تور، توکن مصرف می‌کند. یک وظیفه‌ی ساده که در چت‌بات با یک پرامپت حل می‌شود، در Claude Code ممکن است ۵ تا ۱۰ تور نیاز داشته باشد.

مدیریت بافت، مدیریت هزینه است. هرچه بافت دقیق‌تر و کوچک‌تر باشد، تورهای کمتری لازم است و هزینه‌ی تجمعی پایین‌تر می‌آید.

اشتباه «over-trusting»#

خروجی‌هایی که ظاهراً درست‌اند ولی در edge case می‌شکنند. این مشکل ریشه‌اش در همین است که کاربر Claude Code را چت‌بات‌وار استفاده می‌کند: یک پرامپت می‌دهد، خروجی را می‌خواند و بدون اجرا و تست، آن را قبول می‌کند.

الگوی دو مرحله‌ای verification که در پروژه‌های اعضای کامیونیتی بارها تکرار شده:
  1. خروجی را در محیط ایزوله اجرا کنید، نه فقط خواندن.
  2. نتیجه‌ی اجرا را با انتظار مقایسه کنید. اگر تست شکست، بافت را اصلاح کنید نه پرامپت را تکرار.

اشتباه «همیشه از قوی‌ترین مدل استفاده کن»#

Claude Sonnet در بسیاری از وظایف کدنویسی کیفیت مشابه Opus با هزینه و سرعت بهتر ارائه می‌دهد. انتخاب مدل باید بر اساس وظیفه باشد نه قدرت خام. وظایف تحلیلی پیچیده و معماری چندلایه: Opus. ویرایش، refactoring ساده و نوشتن تابع: Sonnet کافی است.

راهنمای مدیریت هزینه‌ی API در اسکول توضیح داده شده است.

جمع‌بندی: از چت‌بات‌وار فکر کردن دست بکشید#

آموزش Claude Code یعنی یاد گرفتن تفکر معماری. سه اصل عملی: اول، CLAUDE.md را بنویسید و به‌روز نگه دارید. دوم، چرخه‌ی Plan → Act → Verify را رعایت کنید، نه پرامپت یک‌خطی. سوم، مدل را بر اساس وظیفه انتخاب کنید، نه بر اساس قدرت خام.

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