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

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

Claude Code ایجنت است نه مکمل؛ خودش فایل‌ها را می‌خواند، دستورات shell را اجرا می‌کند و تصمیم می‌گیرد کدام ابزار را صدا بزند. این معماری ایجنت‌محور (Agentic Coding) الگوی تعامل را از «دستور بده و کپی کن» به «هدف بده و بازبینی کن» تغییر می‌دهد. نتیجه‌اش این است که شما برنامه‌ریزید، نه تایپیست.

معماری ایجنت‌محور در برابر مکمل‌محور — چه چیزی عوض می‌شود؟#

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

  • الگوی پرامپت: به‌جای «این تابع را بنویس»، می‌گویید «این ماژول را کامل کن و تست‌هایش را اضافه کن».
  • ساخت CLAUDE.md: به‌جای توضیح جزئیات خطی، قوانین معماری و محدودیت‌ها را می‌نویسید.
  • معیار مقایسه‌ی ابزارها: به‌جای «چند خط کد تولید کرد»، می‌پرسید «چند round-trip لازم داشت».

معیار round-trip: چرا تعداد توکن تولیدشده گمراه‌کننده است#

Round-trip یعنی یک دور کامل: ایجنت تصمیم می‌گیرد، اجرا می‌کند، نتیجه را می‌بیند و دوباره تصمیم می‌گیرد. هرچه round-trip کمتر باشد، یعنی ایجنت بهتر فهمیده و شما کمتر بازبینی کرده‌اید.

تعداد توکن تولیدشده معیار بدی است چون ممکن است ایجنت هزار خط کد بنویسد که همه‌اش باید بازنویسی شود. در پروژه‌های واقعی، ایجنت‌هایی که الگوی پرامپت‌نویسی‌شان درست است معمولاً در دورهای کم تسک را تمام می‌کنند؛ ایجنت‌هایی که فهم بافت را ندارند بارها در دور اول گیر می‌کنند و round-trip‌های تکراری تولید می‌کنند. معیار خط تولیدشده نه‌تنها گمراه‌کننده است، بلکه انتخاب ابزار را خراب می‌کند.

الگوی reverse prompt به‌جای دستور مستقیم#

به‌جای «تابع fetchUser را بنویس»، بگویید «فایل auth.ts را بخوان و بگو چه توابعی کم دارد». این الگو (Reverse Prompt) ایجنت را وادار می‌کند اول بافت پروژه را بفهمد، بعد پیشنهاد بدهد. نتیجه: کد کمتری تولید می‌شود، اما دقیق‌تر به معماری موجود چسبیده است.

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

آموزش Claude Code از صفر: نصب، پیکربندی و اولین دستور#

Claude Code یک ابزار ترمینال‌محور (CLI) است که Anthropic اوایل سال 2025 عرضه کرد؛ با npm install -g @anthropic-ai/claude-code نصب می‌شود، به Node.js نسخه‌ی 18 یا بالاتر نیاز دارد و از طریق حساب Claude Pro یا Max یا کلید API فعال می‌شود.

پیش‌نیازها: Node.js، نوع حساب (Pro / Max / API Key)#

سه راه برای دسترسی به Claude Code وجود دارد:

  • Claude Pro: اشتراک ماهانه با سقف مصرف معقول برای کار روزمره.
  • Claude Max: سقف مصرف بالاتر، مناسب پروژه‌های سنگین‌تر.
  • کلید API: برای استفاده‌ی برنامه‌نویسی‌محور (programmatic) و اسکریپت‌نویسی.

برای جزئیات دقیق سقف مصرف هر سطح، به مستندات رسمی Anthropic مراجعه کنید. این اعداد در طول زمان تغییر می‌کنند و نوشتن عدد ثابت اینجا بی‌فایده است.

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

  1. Node.js نسخه‌ی 18 یا بالاتر را نصب یا آپدیت کنید.
  2. در ترمینال دستور npm install -g @anthropic-ai/claude-code را بزنید.
  3. به پوشه‌ی پروژه‌تان بروید: cd your-project.
  4. دستور claude را اجرا کنید.
  5. در اولین اجرا، احراز هویت (authentication) انجام می‌شود — یا با مرورگر یا با کلید API.
  6. حالا در همان ترمینال، هدف خود را به زبان طبیعی بنویسید.

تفاوت Claude Pro و Claude Max در سقف مصرف#

Claude Pro برای توسعه‌دهنده‌ای که روزی چند ساعت کد می‌زند کافی است. Claude Max وقتی لازم می‌شود که ایجنت را روی پروژه‌های بزرگ‌تر با round-trip‌های بیشتر اجرا کنید و به سقف بالاتر نیاز دارید.

اگر فقط می‌خواهید Claude Code را امتحان کنید، Pro شروع مناسبی است.

CLAUDE.md مؤثر: ساختار سه‌بخشی که Context Window را هدر نمی‌دهد#

CLAUDE.md مؤثر یعنی فایلی که با ساختار سه‌بخشیِ قوانین، استثناها و نمونه‌های کد نوشته شده و اولویتش «نبایدها» است؛ اگر بیش‌ازحد پر شود، Context Window (پنجره‌ی زمینه‌ی مدل) اشباع می‌شود و کیفیت پاسخ کاهش می‌یابد. این الگو در پروژه‌های واقعی بارها تست شده و مؤثرتر از نوشتن جزئیات خطی است.

بخش اول — قوانین پروژه#

در این بخش، تصمیمات معماری (architecture decisions) و قراردادهای نام‌گذاری (naming conventions) را بنویسید. مثال: «تمام API‌ها RESTful هستند، نه GraphQL» یا «از TypeScript strict mode استفاده می‌کنیم». این‌ها به ایجنت می‌گویند چارچوب کلی چیست، بدون اینکه جزئیات خطی اضافه کند.

بخش دوم — استثناها و «نبایدها»#

این بخش مؤثرترین قسمت CLAUDE.md است. الگوی مشاهده‌شده در پروژه‌های واقعی: نوشتن «نبایدها» (anti-patterns) کیفیت خروجی را بیشتر از «بایدها» بالا می‌برد. مثال: «از import مستقیم از پوشه‌ی legacy استفاده نکن»، «هرگز در فایل‌های تست از mock استفاده نکن مگر در لایه‌ی network».

چرا؟ چون ایجنت وقتی بداند چه نکند، فضای کمتری را صرف حدس‌زدن می‌کند.

بخش سوم — نمونه‌های کد مرجع#

یک یا دو نمونه‌ی کوتاه از کدی که دقیقاً سبک موردنظر شماست. نه 50 خط، نه 100 خط. یک تابع کامل با کامنت‌های توضیحی کافی است تا ایجنت سبک را بگیرد.

اشتباه رایج: پر کردن CLAUDE.md با هر جزئیات ممکن#

هر خط اضافی در CLAUDE.md، فضای Context Window را می‌خورد. اگر فایل‌تان بیش‌ازحد بزرگ شود، ایجنت بخش بزرگی از فایل‌های پروژه را نمی‌تواند همزمان در حافظه داشته باشد. قانون عملی: CLAUDE.md را زیر 50 خط نگه دارید. اگر چیزی در این سه بخش جا نمی‌شود، احتمالاً لازم نیست.

در پروژه‌های تیمی، CLAUDE.md را در ریپو commit کنید و مثل هر فایل دیگری با PR تغییر دهید. این کار نسخه‌بندی و اشتراک‌گذاری را تضمین می‌کند.

جریان‌های کاری عملی با Claude Code: دیباگ، ریفکتور و نوشتن تست#

جریان‌های کاری عملی با Claude Code سه الگوی اصلی دارند: در دیباگ، الگوی «اجرای تدریجی» مؤثرتر از یک پرامپت بزرگ است — ایجنت را مرحله‌به‌مرحله هدایت کنید و بین هر مرحله خروجی را بازبینی کنید. در ریفکتور، به‌جای «کد را بازنویسی کن»، بگویید «این فایل را بخوان و بگو چه چیزی کم دارد». در تست، reverse prompt را با اجرای خودکار test runner ترکیب کنید.

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

الگوی اجرای تدریجی در دیباگ خطاهای چندلایه#

خطای چندلایه یعنی باگ در لایه‌ی UI نشانه‌اش از لایه‌ی database می‌آید. الگوی تدریجی:

  1. به ایجنت بگویید فقط stack trace را بخواند و لایه‌ی شروع را شناسایی کند.
  2. خروجی را بازبینی کنید. اگر لایه‌ی شروع درست است، بگویید آن فایل را بخواند.
  3. بعد از فهم بافت، بگویید فرضیه‌ی باگ را بدهد — نه فیکس را.
  4. فرضیه را چک کنید، بعد فیکس را بخواهید.

این الگو round-trip‌ها را بیشتر می‌کند اما هر round-trip دقیق‌تر است. نتیجه نهایی: باگ سریع‌تر و با کمترین تغییر جانبی حل می‌شود.

ریفکتور با معیار صحت تست نه حجم کد تولیدشده#

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

نوشتن تست: از reverse prompt تا اجرای خودکار test runner#

الگوی مؤثر: «فایل service.ts را بخوان و بگو کدام رفتارها تست ندارند». ایجنت لیست می‌دهد. بعد بگویید «برای مورد اول، تست بنویس و test runner را اجرا کن». این چرخه‌ی reverse prompt + اجرای خودکار، کیفیت پوشش تست را بدون پرامپت‌نویسی طولانی بالا می‌برد.

مدیریت Git: commit message، branch و merge conflict#

Claude Code می‌تواند commit message بنویسد، branch بسازد و merge conflict را حل کند. نکته‌ی عملی: هرگز merge conflict را بدون بازبینی به ایجنت نسپارید. بگویید «conflict را نشان بده و توضیح بده چرا دو نسخه متفاوت‌اند»، بعد خودتان تصمیم بگیرید.

مقایسه‌ی Claude Code با Cursor، Copilot و Aider بر اساس round-trip#

Claude Code و Aider ایجنت‌محورند و خودشان تصمیم می‌گیرند چه بخوانند و اجرا کنند؛ Cursor ترکیبی از IDE و چت است؛ GitHub Copilot صرفاً مکمل خط‌به‌خط پیشنهاد می‌دهد. انتخاب درست بستگی به این دارد که تسک شما چند round-trip لازم دارد.

ابزارمعماریبهترین کاربردمصرف round-trip
Claude Codeایجنت ترمینال‌محورریفکتور بزرگ، دیباگ چندلایه، پروژه‌های CLIکم (ایجنت خودش تصمیم می‌گیرد)
CursorIDE + چت ترکیبیتوسعه‌ی روزمره با بازبینی خط‌به‌خطمتوسط (شما هدایت می‌کنید)
GitHub Copilotمکمل خط‌به‌خطتوابع کوچک، autocomplete، یادگیری الگوزیاد (هر خط جدا)
Aiderایجنت ترمینال‌محور متن‌بازهمان Claude Code با مدل دلخواهکم (مشابه Claude Code)

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

اگر در IDE نشسته‌اید و می‌خواهید کد را خط‌به‌خط بازبینی کنید، Cursor جریان‌کار بهتری دارد. اگر تسک شما «این ماژول را کامل کن و تست بنویس» است و می‌خواهید ایجنت خودش فایل‌ها را پیدا کند، Claude Code مناسب‌تر است. تفاوت اصلی: Cursor شما را در IDE نگه می‌دارد، Claude Code در ترمینال کار می‌کند.

Aider به‌عنوان جایگزین متن‌باز در برابر Claude Code#

Aider متن‌باز است و می‌توانید مدل دلخواه (GPT، Gemini، Claude) را به آن وصل کنید. اما پشتیبانی داخلی بهتری از MCP و اکوسیستم Anthropic در Claude Code وجود دارد. اگر به مدل خاص یا هزینه‌ی کمتر نیاز دارید، Aider گزینه‌ی منطقی است. اگر در اکوسیستم Anthropic هستید، Claude Code یکپارچه‌تر است.

هزینه و مصرف توکن در Claude Code چطور کنترل می‌شود؟#

مصرف توکن در Claude Code مستقیماً به تعداد فایل‌هایی که ایجنت می‌خواند و round-trip‌های لازم بستگی دارد؛ مدیریت Context Window، نوشتن CLAUDE.md فشرده و استفاده از --disallowedTools برای محدود کردن دسترسی، مهم‌ترین اهرم‌های کاهش هزینه‌اند.

Token و Context Window: چه چیزی مصرف را بالا می‌برد؟#

سه عامل اصلی مصرف را بالا می‌برند: فایل‌های بزرگ که ایجنت کاملشان را می‌خواند، CLAUDE.md شلوغ که فضای Context را می‌خورد، و round-trip‌های تکراری که هر بار کل بافت را دوباره می‌فرستد.

هرچه ایجنت «باهوش‌تر» باشد — نه لزوماً مدل بزرگ‌تر، بلکه پرامپت دقیق‌تر — round-trip کمتر و مصرف پایین‌تر.

تفاوت Sonnet و Opus در سرعت و کیفیت خروجی کد#

Sonnet برای کارهای روزمره — نوشتن تابع، دیباگ ساده، ریفکتور کوچک — سرعت بالاتری دارد و مصرف کمتری. Opus برای مسائل پیچیده‌ی استدلالی — ریفکتورهای بزرگ چندفایلی، طراحی معماری، دیباگ باگ‌های چندلایه — کیفیت بالاتری می‌دهد.

الگوی عملی: شروع با Sonnet، ارتقا به Opus فقط وقتی round-trip‌ها بالا می‌روند و کیفیت پایین است.

استراتژی‌های کاهش مصرف#

  • CLAUDE.md را فشرده نگه دارید (زیر 50 خط).
  • با --disallowedTools دسترسی ایجنت به فایل‌های غیرمرتبط را ببندید.
  • تسک‌های بزرگ را به زیرتسک‌های کوچک‌تر تقسیم کنید تا هر round-trip بافت کمتری لازم داشته باشد.
  • برای کارهای ساده از Sonnet استفاده کنید، نه Opus.

برای جزئیات دقیق قیمت‌گذاری Pro و Max، به صفحه‌ی قیمت‌گذاری Anthropic مراجعه کنید.

Model Context Protocol: اتصال Claude Code به ابزارهای خارجی#

MCP (Model Context Protocol) پروتکلی است که امکان اتصال دیتابیس، API‌ها و سرویس‌های ابری را به Claude Code فراهم می‌کند؛ اما اتصال بدون محدودسازی دسترسی با --allowedTools، ریسک اجرایی دستورات مخرب را بالا می‌برد.

نصب و پیکربندی MCP Server در Claude Code#

MCP Server یک فرآیند جداست که ابزارهای خارجی را به‌صورت استاندارد به ایجنت معرفی می‌کند. نصب معمولاً شامل افزودن کانفیگ به فایل تنظیمات Claude Code است. جزئیات دقیق نصب به مستندات رسمی Anthropic و مخزن هر MCP Server مراجعه کنید.

امنیت: --allowedTools و --disallowedTools برای محدودسازی#

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

اشتباه پرهزینه: auto-approve بدون sandbox در پروژه‌های حساس#

auto-approve یعنی ایجنت بدون تأیید شما دستورات را اجرا می‌کند. اگر sandbox (محیط ایزوله‌ی اجرا) فعال نباشد، یک دستور مخرب — مثلاً rm -rf یا drop table — بدون بازبینی اجرا می‌شود. این پرهزینه‌ترین اشتباه رایج در کار با Claude Code است.

در مقاله‌ی امنیت در ایجنت‌های هوش مصنوعی اسکول، الگوهای امنیتی را با جزئیات بررسی کرده‌ایم.

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

شایع‌ترین اشتباهات در کار با Claude Code این‌ها هستند: پرامپت‌های مبهم و جزئی‌نگر، نادیده‌گرفتن دسترسی فایل، پر کردن CLAUDE.md، و فعال‌سازی auto-approve بدون sandbox؛ هر کدام هزینه‌ی مشخصی در کیفیت خروجی یا ریسک امنیتی دارند.

پرامپت طولانی و جزئی‌نگر — بی‌اثر در ایجنت#

هزینه: round-trip‌های بیشتر، مصرف توکن بالاتر، خروجی بی‌کیفیت. اگر به ایجنت بگویید «در خط 47 فایل service.ts، متغیر x را به y تغییر بده»، دارید از یک ایجنت، یک find-and-replace می‌سازید. به‌جایش بگویید «تابع fetchUser را طوری تغییر بده که timeout هم مدیریت کند».

CLAUDE.md بیش‌ازحد بزرگ — اشباع Context Window#

هزینه: ایجنت فایل‌های پروژه را نمی‌تواند همزمان در حافظه داشته باشد. نتیجه: کد ناسازگار با معماری، round-trip‌های تکراری. اگر CLAUDE.md شما بالای 100 خط است، احتمالاً بیش‌ازحد پر شده.

auto-approve بدون sandbox — پرهزینه‌ترین اشتباه#

هزینه: از دست رفتن داده، خرابی محیط، یا اجرای کد مخرب. این اشتباه یک‌بار رخ بدهد و جبران‌ناپذیر باشد. همیشه قبل از فعال‌سازی auto-approve، sandbox را چک کنید.

مقایسه‌ی ابزار بر اساس «تعداد خط تولیدشده»#

هزینه: انتخاب ابزار غلط. اگر معیار شما «چند خط کد نوشت» باشد، Copilot برنده می‌شود چون خط‌به‌خط پیشنهاد می‌دهد. اما معیار درست، round-trip تا تکمیل تسک است. ابزارهایی که ایجنت‌محورند معمولاً خط کمتری تولید می‌کنند اما تسک را در دورهای کم‌تر تمام می‌کنند.

چه زمانی Claude Code انتخاب غلط است#

Claude Code برای پروژه‌های با معماری بسیار پیچیده و چندریپو، کارهایی که نیاز به بازبینی انسانی هر خط دارند، یا محیط‌های بدون Node.js گزینه‌ی مناسب نیست؛ در این موارد Cursor یا Copilot جریان‌کار بهتری ارائه می‌دهند.

پروژه‌های چندریپو با وابستگی‌های عمیق#

اگر پروژه‌تان چند repository دارد و تغییر در یکی، دیگری را می‌شکند، Claude Code (که در یک پوشه‌ی محلی کار می‌کند) نمی‌تواند تصویر کامل را ببیند. در این موارد، ابزارهایی که به IDE متصل‌اند و شما را در بافت نگه می‌دارند (مثل Cursor) مناسب‌ترند.

محیط‌های بدون Node.js یا دسترسی محدود ترمینال#

Claude Code به Node.js و دسترسی ترمینال نیاز دارد. اگر در محیط سازمانی محدودی کار می‌کنید که نمی‌توانید npm install بزنید، این ابزار عملاً غیرقابل‌استفاده است.

کارهایی که بازبینی انسانی خط‌به‌خط ضروری است#

کدهای امنیتی، الگوریتم‌های مالی، یا هر جایی که یک خط اشتباه فاجعه‌بار است: ایجنت‌محور بودن یعنی بازبینی خط‌به‌خط سخت‌تر می‌شود چون ایجنت خودش تصمیم می‌گیرد چه بنویسد. در این موارد، مکمل‌محور (Copilot یا Cursor) کنترل بیشتری می‌دهد.

جایگزین‌ها در هر مورد#

  • پروژه‌ی چندریپو: Cursor با دسترسی به چند پوشه.
  • محیط محدود: GitHub Copilot در IDE.
  • بازبینی خط‌به‌خط ضروری: Copilot یا Cursor.
  • نیاز به مدل دلخواه: Aider.

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