آموزش Claude Code بدون درک معماری ایجنتی آن، یعنی کپی‌کردن عادت‌های چت‌محور به ابزاری که مستقیم shell و filesystem شما را دستکاری می‌کند. اگر permissions تنظیم نشده باشد و پرامپت question-oriented باشد، نتایج مخرب می‌گیرید — نه فقط خروجی بد، بلکه فایل‌های تغییر‌یافته و commitهای ناخواسته در repo شما.

Claude Code یک چت نیست: معماری ایجنتی و agentic loop#

Claude Code یک ایجنت هوش مصنوعی (AI Agent) است که در چرخه‌ی ایجنتی (agentic loop) با خواندن context، تصمیم‌گیری برای صدا زدن ابزار، اجرای آن در shell و filesystem، و مشاهده‌ی نتیجه کار می‌کند. تفاوت بنیادینش با رابط چت وب این است که خروجی‌اش متن نیست؛ تغییر مستقیم در فایل‌ها و commitهای repo شماست.

مدل Claude 3.7 Sonnet به‌عنوان backbone با extended thinking و context window 200K توکن، این تصمیم‌گیری‌ها را انجام می‌دهد. ایجنت می‌تواند bash اجرا کند، فایل بنویسد، test بزند و git commit بزند بدون اینکه شما IDE را باز کنید.

در هر دور از loop، سه مرحله طی می‌شود: ابتدا context خوانده می‌شود (فایل‌ها، دستور شما، نتایج دور قبلی)، سپس تصمیم گرفته می‌شود کدام ابزار صدا زده شود، و در نهایت خروجی ابزار observe می‌شود تا دور بعدی ساخته شود. این چرخه تا اتمام task یا interrupt شما ادامه دارد.

حالت interactive در مقابل حالت headless#

در حالت interactive، هر دستور قبل از اجرا به شما نمایش داده می‌شود و باید approve کنید. این حالت برای کارهای حساس و یادگیری اولیه ضروری است.

در حالت headless با flag --print، ایجنت loop کامل را بدون تأیید انسانی اجرا می‌کند و خروجی یک‌باره تولید می‌شود. این حالت برای pipe در shell و pipelineهای CI/CD ساخته شده، اما بدون permissions scoped، ریسک تغییر مخرب فایل‌ها را دارد.

الگوی subagent و محدودیت‌های آن#

Claude Code می‌تواند subagent بسازد — یک ایجنت فرعی با context window جداگانه که یک subtask مشخص را انجام می‌دهد. مشکل: هر subagent توکن‌های ورودی و خروجی مستقل مصرف می‌کند. اگر task شما به ۳ subagent نیاز داشته باشد، هزینه‌ی API تقریباً سه‌برابر می‌شود.

الگوی صحیح: subagent فقط برای کارهایی که واقعاً context جداگانه لازم دارند. برای taskهای ساده، decomposition در همان session ارزان‌تر و قابل‌کنترل‌تر است.

نصب، احراز هویت و پیکربندی CLAUDE.md: اولین قدم‌ها#

نصب Claude Code با npm install -g @anthropic-ai/claude-code انجام می‌شود، احراز هویت با اجرای دستور claude و هدایت خودکار به مرورگر صورت می‌گیرد، و فایل CLAUDE.md در ریشه‌ی پروژه دستورالعمل‌های سطح پروژه را به ایجنت می‌دهد. پیش‌نیازها: Node.js نسخه‌ی LTS و npm.

بعد از نصب، دستور claude در terminal اجرا می‌شود و شما را به مرورگر برای احراز هویت Anthropic account هدایت می‌کند. اگر از API key استفاده می‌کنید، متغیر محیطی ANTHROPIC_API_KEY را set کنید.

پیکربندی سطح پروژه در مقابل سطح کاربر#

فایل CLAUDE.md در ریشه‌ی پروژه قرار دارد و فقط برای همان پروژه اعمال می‌شود. تنظیمات global معمولاً در ~/.claude/ ذخیره می‌شوند و برای همه‌ی پروژه‌ها معتبرند. اولویت با CLAUDE.md است — اگر هر دو یک rule را تعریف کنند، فایل پروژه override می‌کند.

ساختار CLAUDE.md شامل این بخش‌هاست:

  • Coding conventions: style guide، naming، import patterns
  • Forbidden files: فایل‌هایی که ایجنت نباید بخواند یا بنویسد (مثل .env، secrets)
  • Scoped permissions: کدام دستورات shell مجازند، کدام فایل‌ها writable هستند
  • Project context: معماری، dependencies، test commands

مثال واقعی CLAUDE.md برای پروژه Node.js با TypeScript#

یک نمونه‌ی عملی: در بخش permissions بنویسید «اجازه‌ی اجرای npm test و npx tsc --noEmit» و در forbidden files بنویسید «.env، .env.local، config/secrets/». در coding conventions مشخص کنید «ESLint rules پروژه را رعایت کن، از any استفاده نکن، importها را با path alias بنویس».

هرچه این فایل دقیق‌تر باشد، ایجنت کمتر تصمیم‌گیری‌های مخرب انجام می‌دهد. یک اشتباه رایج در کلاس‌ها: نوشتن CLAUDE.md به‌صورت توصیفی و مبهم. «کد تمیز بنویس» هیچ محدودیت قابل‌اجرایی به ایجنت نمی‌دهد؛ «از interface به‌جای type alias در models استفاده کن» می‌دهد.

Permissions و حالت headless: کنترل دسترسی ایجنت#

بدون تنظیم permissions، Claude Code به همه‌ی فایل‌ها و دستورات shell دسترسی دارد. الگوی allow/deny در CLAUDE.md مشخص می‌کند کدام فایل‌ها خوانده شوند و کدام دستورات مجاز باشند. حالت headless برای CI/CD مناسب است اما ریسک بالاتری دارد.

اشتباه رایج و هزینه‌ی آن: در کامیونیتی چند incident گزارش شده که ایجنت بدون تأیید user، package-lock.json را بازنویسی کرده یا migrationهای SQL را اجرا کرده. در حالت headless که تأیید انسانی وجود ندارد، این تغییرات مستقیم به filesystem نوشته می‌شوند.

کاربرد headless mode در pipelineهای CI/CD#

در GitHub Actions یا GitLab CI، می‌توانید Claude Code را در حالت headless صدا بزنید تا task مشخصی مثل «fix failing tests» یا «generate changelog» را انجام دهد. خروجی شامل trace دستورات اجراشده است که برای audit ضروری است.

الگوی پیشنهادی:

  1. permissions را در CLAUDE.md به حداقل برسانید (فقط فایل‌های موردنیاز writable)
  2. branch محافظت‌شده بسازید و ایجنت را روی branch feature کار دهید
  3. خروجی را با git diff بررسی کنید قبل از merge

Best practices permissions برای پروژه‌های production#

  • فایل‌های config و secrets را در forbidden files بگذارید
  • دستورات مخرب (rm، DROP TABLE، force push) را deny کنید
  • scope نوشتن فایل را به پوشه‌ی مشخص محدود کنید
  • در حالت interactive، حتی با permissions تنظیم‌شده، هر دستور را review کنید

پرامپت‌نویسی task-oriented: چرا الگوهای چت‌محور شکست می‌خورند#

Claude Code ایجنتی است که خودش تصمیم می‌گیرد کدام فایل را باز کند و کدام دستور را اجرا کند. پرامپت باید توصیف task باشد نه سؤال. Context stuffing بی‌رویه کیفیت را کاهش و هزینه را افزایش می‌دهد.

مثال قبل و بعد: پرامپت چت‌محور «چطور می‌توانم این bug را fix کنم؟» در مقابل پرامپت task-oriented «function getUserProfile در src/services/auth.ts خطای TypeError می‌دهد وقتی user=null. test مربوطه را fix کن و مطمئن شو npm test پاس می‌شود». دومی دقیقاً مشخص می‌کند کدام فایل، کدام خطا، و معیار موفقیت چیست.

مدیریت context window 200K توکن: «هرچه بیشتر بدهید» اشتباه است. ایجنت با context شلوغ، تمرکز تصمیم‌گیری‌اش را از دست می‌دهد و توکن‌های اضافی هزینه‌ی API را بالا می‌برند. فقط فایل‌ها و اطلاعاتی را بدهید که مستقیم به task مربوطند.

الگوی decomposition — شکستن task بزرگ به subtasks#

به‌جای یک پرامپت بزرگ، task را به مراحل قابل‌اجرا بشکنید. هر مرحله یک خروجی مشخص دارد. مثال: «مرحله ۱: schema را در models/User.ts update کن. مرحله ۲: migration بساز. مرحله ۳: API handler را adjust کن. مرحله ۴: testها را update کن و npm test اجرا کن.» ایجنت در هر مرحله فقط context لازم را می‌خواند.

استفاده از subagent برای کارهای فراتر از یک context window#

وقتی task واقعاً به context جداگانه نیاز دارد — مثلاً refactoring یک module بزرگ که فایل‌هایش با هم conflict دارند — subagent منطقی است. اما قبل از استفاده، هزینه را محاسبه کنید: هر subagent یک context window مستقل مصرف می‌کند.

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

MCP (Model Context Protocol) پروتکلی است که Anthropic در نوامبر ۲۰۲۴ معرفی کرد و به Claude Code اجازه می‌دهد با ابزارهای خارجی مثل دیتابیس، APIها و سرویس‌های فایلی ارتباط برقرار کند. ساختارش شامل transport، tools، resources و prompts است.

اتصال مرکز هوش مصنوعی به ماژول‌های ابزار خارجی از طریق فیبرهای نوری در فضای کاری تاریک
هر سرور MCP یک دست اضافه برای ایجنت است.

نصب و پیکربندی: MCP server را در فایل تنظیمات Claude Code با specify کردن transport type و path یا URL server ثبت می‌کنید. بعد از restart، ابزارهای آن server در لیست tools ایجنت ظاهر می‌شوند و ایجنت می‌تواند آن‌ها را صدا بزند.

مثال اتصال MCP server به PostgreSQL#

یک MCP server برای PostgreSQL معمولاً ابزارهایی مثل query، list_tables و describe_table را expose می‌کند. بعد از اتصال، ایجنت می‌تواند مستقیم schema را بخواند و SQL بنویسد بدون اینکه شما export بگیرید.

برای محیط‌های production، این ابزارها را read-only محدود کنید. دسترسی write به دیتابیس از طریق ایجنت، سطح حمله‌ی جدیدی اضافه می‌کند که با audit trail معمولی قابل‌ردیابی نیست.

محدودیت‌ها و security considerations#

  • MCP server با دسترسی write به دیتابیس، ریسک injection و حذف داده دارد
  • هر MCP server یک سطح حمله‌ی جدید اضافه می‌کند — فقط serverهای موردنیاز را فعال کنید
  • credentials دیتابیس را در env variable بگذارید، نه در فایل config

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

Cursor یک AI داخل IDE است که loop ایجنتی‌اش محدود به editor context است، اما Claude Code یک ایجنت کامل با دسترسی به shell است — می‌تواند npm install کند، test اجرا کند و git commit بزند بدون اینکه IDE باز شود. انتخاب ابزار بستگی به نوع task دارد.

ابزارمعماریسطح دسترسیبهترین use case
Claude CodeCLI agent با agentic loop کاملshell، filesystem، git، networkmulti-file changes، automation، CI/CD
CursorAI داخل IDE با loop محدودفایل‌های باز در editorrefactoring داخل فایل، autocomplete، context-aware editing
GitHub Copilotautocomplete + chat در IDEفقط editor contextتولید سریع snippet، completion خطی
AiderCLI agent با git integrationfilesystem، gitpair programming با terminal، repo-level changes

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

وقتی task داخل یک یا دو فایل محدود است و می‌خواهید context editor (خط‌های باز، selection) به‌صورت خودکار به AI برسد. برای refactoring یک function، اضافه کردن یک component، یا کارهای UI که نیاز به preview دارند.

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

وقتی task شامل چندین فایل، اجرای test، نصب dependency، یا کارهای shell-based است. مثلاً «upgrade همه‌ی dependencies، fix breaking changes، مطمئن شو testها پاس می‌شوند» — این در Cursor ممکن نیست چون ایجنت به terminal دسترسی ندارد.

مدل هزینه: API credit یا اشتراک Max؟#

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

مقایسه: API credit برای استفاده‌ی sporadic و پروژه‌های کوچک مناسب‌تر است — فقط آنچه مصرف می‌کنید می‌پردازید. اشتراک Max برای استفاده‌ی روزانه و سنگین به‌صرفه‌تر است. اگر از Claude Code به‌عنوان ابزار اصلی توسعه استفاده می‌کنید، subscription معمولاً ارزان‌تر تمام می‌شود.

تخمین هزینه بر اساس حجم پروژه#

یک task ساده‌ی single-file (مثلاً fix یک bug) معمولاً چند هزار توکن ورودی و خروجی مصرف می‌کند. یک task multi-file با test و migration، ده‌ها برابر بیشتر. subagent‌ها این عدد را ضرب می‌کنند.

قبل از شروع taskهای بزرگ، با حالت interactive و permissions محدود، یک dry run بزنید و توکن مصرفی را از trace بخوانید. این ساده‌ترین راه برای جلوگیری از غافلگیری در صورت‌حساب ماهانه است.

راهکارهای کاهش هزینه#

  • context را scoped نگه دارید — فقط فایل‌های مرتبط را بدهید
  • CLAUDE.md را دقیق بنویسید تا ایجنت کمتر دورهای تکراری بزند
  • subagent فقط برای کارهای واقعاً مستقل
  • در حالت headless، prompt را بهینه کنید چون هر دور بدون interrupt ادامه می‌یابد

چه زمانی نباید از Claude Code استفاده کرد؟#

پروژه‌هایی با compliance سخت‌گیرانه که اجازه‌ی ارسال کد به API خارجی نمی‌دهند، task‌هایی که determinism کامل لازم دارند، و محیط‌هایی که بازبینی انسانی الزامی است — Claude Code جایگزین توسعه‌دهنده نیست.

محدودیت‌های compliance: اگر سازمان شما HIPAA، SOC2 یا GDPR دارد و کد منبع نباید از مرز شبکه‌ی داخلی خارج شود، Claude Code به‌عنوان ابزار ابری (cloud-based) مناسب نیست. حتی با self-hosted model، compliance team باید approve کند.

عدم determinism: code generation برای embedded systems، financial systems با audit trail، یا taskهایی که خروجی باید دقیقاً قابل‌تکرار باشد — ایجنت‌ها ذاتاً probabilistic هستند و دو اجرای یک پرامپت ممکن است خروجی متفاوت بدهد.

Anti-pattern «Claude Code جایگزین توسعه‌دهنده است»#

ایجنت می‌تواند کد بنویسد، test اجرا کند، git commit بزند و deploy scriptها را اجرا کند. اما بدون scoped permissions و بازبینی انسانی، تغییرات مخرب در فایل‌سیستم و environmentهای production رخ می‌دهد.

الگوی صحیح: Claude Code به‌عنوان شریک ایجنتی با human-in-the-loop. ایجنت کارهای تکراری و خسته‌کننده را انجام می‌دهد، شما تصمیم‌های معماری و review نهایی را.

ترکیب Claude Code با human-in-the-loop#

بهترین الگوی عملی که در پروژه‌های واقعی تکرار شده:

  1. task را با پرامپت task-oriented مشخص کنید
  2. ایجنت در حالت interactive کار کند و هر دستور را approve کنید
  3. خروجی با git diff review شود
  4. testها قبل از merge پاس شوند
  5. فقط بعد از تأیید انسانی، commit و push

Claude Code ابزاری قدرتمند است، اما معماری ایجنتی‌اش یعنی اشتباهات شما مستقیم به filesystem و repo شما می‌نشینند. permissions را جدی بگیرید، پرامپت‌ها را task-oriented بنویسید، و human-in-the-loop را حذف نکنید.

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