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

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

Claude Code یک ایجنت خط فرمان (CLI coding agent) محصول Anthropic است که در ترمینال اجرا می‌شود، به فایل‌سیستم و git دسترسی مستقیم دارد و تغییرات چندفایلی اعمال می‌کند. برخلاف چت Claude که فقط متن تولید می‌کند و Copilot که یک خط autocomplete می‌کند، این ابزار یک وظیفه‌ی کامل می‌گیرد و خودش فایل‌های موردنظر را ویرایش می‌کند.

تفاوت بنیادین در نوع وظیفه‌ای است که به ابزار می‌سپارید. در Copilot، شما یک خط کد می‌نویسید و ابزار پیشنهاد تکمیل می‌دهد. در Claude Code، شما یک «وظیفه» تعریف می‌کنید — مثلاً «ماژول احراز هویت را به JWT مهاجرت بده» — و ابزار خودش فایل‌ها را می‌خواند، تصمیم می‌گیرد کدام فایل‌ها را ویرایش کند و تغییرات را اعمال می‌کند.

این یعنی workflow شما از «پرامپت‌نویسی خطی» به «task decomposition ساختارمند» تغییر می‌کند. اگر این تغییر ذهنی را نکنید، Claude Code را مثل یک چت‌بات گران‌قیمت استفاده می‌کنید و بهترین بازده را از دست می‌دهید.

چرا این تفاوت معماری روی workflow شما اثر می‌گذارد#

در چت، مدل فقط متن تولید می‌کند و شما باید context را دستی بچسبانید، خروجی را کپی کنید و فایل‌ها را دستی ویرایش کنید. در Claude Code، ابزار خودش file read/write و bash execution دارد. پس هر بار که context را در پرامپت تکرار می‌کنید، عملاً کاری را انجام می‌دهید که ابزار خودش بهتر انجام می‌دهد — و هزینه‌ی توکن اضافی می‌پردازید.

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

جدول مقایسه‌ی Claude Code، Copilot، Cursor، Windsurf و Aider#

ابزارنوع تعاملدسترسی به فایل‌سیستممدل زبانیمدل هزینه
Claude CodeTask execution در CLIمستقیم (read/write/bash)ClaudeAPI credits یا اشتراک Pro/Max
GitHub CopilotAutocomplete خط‌به‌خطمحدود (context IDE)مدل‌های مختلفSubscription ثابت
CursorChat + inline edit داخل IDEمحدود (workspace)مدل‌های مختلفSubscription ثابت
WindsurfAgentic flow داخل IDEمحدود (workspace)مدل‌های مختلفSubscription ثابت
AiderTask execution در CLIمستقیم (read/write)مدل‌های مختلف (متن‌باز)API credits

نصب و راه‌اندازی Claude Code در ترمینال#

Claude Code با یک دستور npm نصب می‌شود و برای اجرا به یک API key از Anthropic نیاز دارد. پیش‌نیازها شامل Node.js نسخه‌ی LTS، دسترسی به terminal و یک پروژه‌ی git با حداقل یک commit است.

مراحل نصب:

  1. Node.js نسخه‌ی LTS را نصب کنید (از nodejs.org).
  2. حساب Anthropic بسازید و از console.anthropic.com یک API key بگیرید.
  3. در ترمینال دستور npm install -g @anthropic-ai/claude-code را اجرا کنید.
  4. به ریشه‌ی پروژه‌ی git خود بروید و claude را تایپ کنید.
  5. در اولین اجرا، ابزار از شما API key می‌خواهد. آن را paste کنید.

نکته: اگر API key معتبر نباشد یا credits نداشته باشید، ابزار پیام خطای مبهمی می‌دهد که ربطی به git ندارد. اول key را چک کنید، بعد git.

مشکل رایج: نبود git init و پیام خطای مبهم#

Claude Code به یک repository git نیاز دارد. اگر در پوشه‌ای بدون .git اجراش کنید، ابزار ممکن است خطای نامفهمی بدهد یا رفتار غیرمنتظره‌ای داشته باشد. قبل از اولین اجرا، مطمئن شوید git init و حداقل یک commit انجام شده. این خطا آن‌قدر مبهم است که بسیاری از کاربران فکر می‌کنند مشکل از API key است و وقتشان را صرف بازبینی آن می‌کنند.

تنظیم permission mode برای جلوگیری از اجرای خودسرانه‌ی دستورات#

در حالت پیش‌فرض، Claude Code برای هر دستور shell که می‌خواهد اجرا کند از شما اجازه می‌گیرد. اما اگر permission mode را روی حالت خودکار بگذارید، ابزار می‌تواند rm -rf یا git push را بدون تأیید شما اجرا کند. در پروژه‌های production، این حالت را حتماً باز نگه دارید. هزینه‌ی یک حذف اشتباه فایل‌های production، بی‌مقایسه بیشتر از صرفه‌جویی در چند ثانیه تأیید است.

CLAUDE.md: حافظه‌ی پروژه که اکثر آموزش‌ها نادیده می‌گیرند#

فایل CLAUDE.md یک markdown در ریشه‌ی پروژه است که Claude Code در ابتدای هر session آن را می‌خواند و به‌عنوان ground truth برای تصمیماتش استفاده می‌کند. بدون این فایل، هر بار باید همه‌چیز را از اول توضیح دهید و ابزار هم هر بار از صفر شروع می‌کند.

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

مثال عملی برای یک پروژه‌ی Next.js:

  • Architecture: «State management با Zustand. از Redux استفاده نکن.»
  • Conventions: «نام کامپوننت‌ها PascalCase. فایل‌های utility در /lib. هیچ import مستقیم از /components به /pages.»
  • Forbidden patterns: «useEffect برای fetch داده ممنوع. از React Query استفاده کن.»
  • File structure: «API routes در /app/api. هر route یک فایل. حداکثر 150 خط.»

اشتباه رایج: نوشتن توضیحات عمومی به‌جای تصمیمات فنی مشخص#

اگر در CLAUDE.md بنویسید «این یک پروژه‌ی React است»، ابزار چیزی یاد نمی‌گیرد. تصمیم فنی مشخص بنویسید: «State management با Zustand»، «از Tailwind استفاده کن»، «فایل‌های بیش از 200 خط را split کن». تفاوت این دو سبک را می‌توان در یک جمله خلاصه کرد: توصیف به ابزار نمی‌گوید چه کند، محدودیت می‌گوید چه نکند.

نقش CLAUDE.md در پروژه‌های monorepo: جلوگیری از خواندن فایل‌های نامرتبط#

در monorepo، بدون CLAUDE.md ابزار ممکن است تمام workspaceها را بخواند و context را پر کند. در CLAUDE.md مشخص کنید: «فقط در packages/web کار کن. packages/shared را فقط بخوان، ویرایش نکن.» این یک خط، هزینه‌ی session شما را کاهش می‌دهد و کیفیت خروجی را بالا می‌برد چون ابزار با اطلاعات نامرتبط گیج نمی‌شود.

آیا task decomposition واقعاً جایگزین پرامپت‌نویسی سنتی است؟#

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

الگوی iterative command برای refactoring یک ماژول:

  1. «فایل auth.ts را بخوان و لیست تمام exportهایش را بده.»
  2. «تابع validateToken را به فایل auth/jwt.ts منتقل کن. importهای consumer را آپدیت کن.»
  3. «در فایل auth.ts، از validateToken فقط re-export کن. هیچ منطق دیگری اضافه نکن.»
  4. «تمام تست‌ها را اجرا کن. اگر fail شد، بگو کدام import شکسته.»

هر مرحله یک خروجی مشخص دارد. اگر مرحله‌ی ۲ اشتباه برود، فقط همان را undo می‌کنید. با یک پرامپت 500 کلمه‌ای، اگر خروجی غلط باشد، باید همه‌چیز را از اول شروع کنید.

چه زمانی Extended Thinking را فعال کنید و چه زمانی خاموش بگذارید#

Extended Thinking (حالت تفکر عمیق) هزینه‌ی توکن را افزایش می‌دهد اما برای وظایف پیچیده‌ی چندمرحله‌ای مؤثر است. برای تغییرات ساده مثل rename یا import fix، آن را خاموش نگه دارید. برای refactoring ساختاری یا debugging خطاهای غیرمنتظره، فعالش کنید. الگوی مشاهده‌شده در پروژه‌های اعضای کامیونیتی: فعال کردن Extended Thinking برای کارهای ساده، یکی از رایج‌ترین دلایل هزینه‌ی بالاتر از حد انتظار است.

مدیریت context window در پروژه‌های بزرگ: استراتژی‌های token-efficient#

context window مدل Claude 200,000 توکن است. در پروژه‌های بزرگ، اگر ابزار فایل‌های نامرتبط بخواند، context پر می‌شود و کیفیت خروجی افت می‌کند. استراتژی‌ها:

  • در CLAUDE.md مشخص کنید کدام فایل‌ها مجازند و کدام ممنوع.
  • به‌جای «پروژه را review کن»، بگویید «فقط فایل X و Y را بخوان».
  • sessionهای طولانی را به sessionهای کوتاه‌تر با scope مشخص بشکنید.

هزینه‌ی واقعی Claude Code و مدل قیمت‌گذاری#

Claude Code از سیستم API credits Anthropic استفاده می‌کند؛ اشتراک Claude Pro به‌تنهایی دسترسی به Claude Code را تأمین نمی‌کند و هزینه‌ی واقعی وابسته به تعداد tool calls و حجم context مصرفی است. این تفاوت با subscriptionهای ثابت Copilot و Cursor، یکی از دلایل اصلی نارضایتی کاربران تازه‌وارد است.

ساختار هزینه: هر بار که ابزار یک فایل می‌خواند، یک توکن مصرفی ثبت می‌شود. هر بار که یک دستور bash اجرا می‌کند، خروجی آن هم توکن مصرفی دارد. sessionهای طولانی با فایل‌های متعدد، هزینه‌ی بالاتری دارند.

مقایسه‌ی کیفی: Cursor و Copilot subscription ثابت دارند — مبلغ ماهانه مشخص، مصرف نامحدود (با fair use). Claude Code pay-per-use است. اگر روزی یک ساعت کار کنید، هزینه‌ی Claude Code می‌تواند از subscription ثابت بیشتر باشد. اگر هفته‌ای یک بار استفاده کنید، کمتر.

چرا هزینه‌ی Claude Code در monorepoها بالاتر است#

در monorepo، ابزار ممکن است برای درک یک dependency، فایل‌های چند workspace را بخواند. هر فایل خوانده‌شده، توکن مصرفی اضافه دارد. بدون CLAUDE.md محدودکننده، یک session ساده می‌تواند ده‌ها فایل بی‌ربط بخواند. این دقیقاً همان جایی است که CLAUDE.md نه یک انتخاب، بلکه یک ضرورت اقتصادی می‌شود.

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

  • CLAUDE.md دقیق بنویسید تا ابزار فایل‌های نامرتبط نخواند.
  • sessionها را کوتاه نگه دارید. هر وظیفه = یک session.
  • برای تغییرات ساده، Extended Thinking را خاموش بگذارید.
  • به‌جای «review کل پروژه»، scope مشخص بدهید.

ساخت ایجنت با Claude Code و tool use#

Claude Code خودش یک ایجنت است، اما می‌توانید از آن برای ساخت ایجنت‌های سفارشی استفاده کنید: تعریف tool‌ها، زنجیره‌ی تصمیم‌گیری و اتصال به APIهای خارجی. مفهوم Tool Use (Function Calling) در اینجا کلیدی است: مدل زبانی یک schema از توابع در دسترس را می‌گیرد و خودش تصمیم می‌گیرد کدام تابع را با چه ورودی‌ای صدا بزند.

گره مرکزی نورانی که با شاخه‌های متعدد به ابزارهای مختلف متصل می‌شود و مفهوم ارکستراسیون ایجنت را نشان می‌دهد
هر شاخه‌ی نورانی نمایانگر یک tool call است که ایجنت به‌صورت خودکار هماهنگ می‌کند

Claude Code از همین الگو استفاده می‌کند — file read، file write، bash execution، همه tool‌هایی هستند که مدل خودش فراخوانی‌شان می‌کند.

مراحل ساخت یک ایجنت ساده با Claude API:

  1. Schema توابع را تعریف کنید (نام، توضیح، پارامترها).
  2. در هر request، schema را به مدل بدهید.
  3. اگر مدل یک tool call برگرداند، آن را execute کنید و نتیجه را در message بعدی بفرستید.
  4. این حلقه را تکرار کنید تا مدل دیگر tool call ندهد.

تفاوت ایجنت ساخته‌شده با Claude Code و ایجنت ساخته‌شده با API مستقیم#

Claude Code یک ایجنت آماده با toolهای مشخص است. شما نمی‌توانید toolهای جدید به آن اضافه کنید (حداقل در نسخه‌های فعلی). اگر به ایجنتی نیاز دارید که به API سفارشی شما وصل شود، باید با API مستقیم Anthropic بسازید. این محدودیت، Claude Code را از یک «فریمورک ایجنت‌سازی» به یک «ابزار توسعه» تقلیل می‌دهد.

الگوی agent-as-a-service: زمانی که باید از Claude Code خارج شوید و API بنویسید#

اگر ایجنت شما باید در production اجرا شود، latency حساس باشد، یا به داده‌های خصوصی userها دسترسی داشته باشد، Claude Code ابزار مناسبی نیست. این ابزار برای development است، نه deployment. برای ایجنت‌های سرویس‌محور، API مستقیم بنویسید.

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

سه اشتباه اصلی که در پروژه‌های واقعی تکرار می‌شود: استفاده از Claude Code برای autocomplete خط‌به‌خط، فراموش کردن permission mode در پروژه‌ی production، و نادیده گرفتن هزینه‌ی واقعی. در این موارد ابزارهای دیگر یا API مستقیم انتخاب بهتری هستند.

اشتباه ۱: اگر فقط می‌خواهید یک تابع تک‌خطی بنویسید، Claude Code overhead خواندن context و tool calls بی‌مورد ایجاد می‌کند. برای این کار، Copilot یا Cursor بهترند.

اشتباه ۲: در پروژه‌ی production، اگر permission mode را باز بگذارید، ابزار ممکن است دستورات destructive اجرا کند. همیشه تأیید دستی داشته باشید.

اشتباه ۳: پرامپت‌نویسی چتی به‌جای task decomposition. اگر هر بار 500 کلمه context بنویسید، هم هزینه‌ی اضافی می‌پردازید و هم ابزار گیج می‌شود.

چه زمانی API مستقیم بهتر است: latency-sensitive، batch processing، integration در CI/CD#

Claude Code یک ابزار interactive است. اگر نیاز دارید در CI/CD pipeline، batch processing یا سرویس real-time استفاده کنید، API مستقیم Anthropic انتخاب درست است. Claude Code برای این سناریوها ساخته نشده و تلاش برای استفاده‌ی آن در این موارد، فقط پیچیدگی اضافه می‌کند.

چه زمانی Cursor یا Windsurf انتخاب بهتری‌اند: نیاز به inline completion و UI داخل IDE#

اگر workflow شما داخل IDE است و به inline completion نیاز دارید، Cursor یا Windsurf تجربه‌ی روان‌تری می‌دهند. Claude Code برای کسانی مناسب است که terminal-centric کار می‌کنند و به task execution چندفایلی نیاز دارند.

Claude Code ابزار قدرتمندی است اگر معماری agentic آن را بفهمید و workflow خود را با آن تنظیم کنید. اگر آن را مثل چت استفاده کنید، بهترین بازده را از دست می‌دهید. CLAUDE.md بنویسید، task decomposition کار کنید، و هزینه را مدیریت کنید.

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