بیشتر دوره‌های «آموزش Claude» با نوشتن پرامپت شروع می‌شوند و همین نقطه‌ی شروع، کل مسیر را منحرف می‌کند. Claude Code یک چت‌بات نیست؛ ایجنت (Agent)‌ای است که به فایل‌سیستم، git و ابزارهای خارجی دسترسی دارد. مهارت تعیین‌کننده، طراحی معماری دسترسی ایجنت به context، ابزارها و حافظه‌ی پروژه است، نه صیقل دادن جملات تزیینی در یک پرامپت.

پرامپت‌های ChatGPT-style روی Claude کار نمی‌کنند#

پرامپت‌نویسی ChatGPT روی Claude جواب نمی‌دهد چون معماری مدل‌های Anthropic بر پایه‌ی tagged sections بنا شده و مدل یاد گرفته از XML tags برای تفکیک instructions از context استفاده کند. پرامپت‌های نقش‌محور «تو یک متخصص X هستی» که روی ChatGPT مؤثرند، روی Claude اثر کمتری دارند و گاهی پاسخ را آشفته‌تر می‌کنند.

در کلاس‌ها و گفتگوهای اعضای کامیونیت فارسی‌زبان، رایج‌ترین اشتباه این است که پرامپت‌های ChatGPT-style بدون تغییر ساختار به Claude منتقل می‌شوند. نتیجه: پاسخ‌های سطحی، توهم (hallucination) بیشتر و بی‌اعتمادی به مدل. این چرخه‌ی معیوب هزینه‌اش بیشتر از آن است که به‌نظر می‌رسد — چون کاربر به‌جای اصلاح پرامپت، مدل را رها می‌کند.

مثال قبل و بعد:

  • ChatGPT-style (روی Claude ضعیف): «تو یک senior backend developer هستی. یک API بنویس.»
  • Claude-style (بهینه): «<instructions>یک REST API با Node.js بنویس</instructions> <context>پروژه از Express استفاده می‌کند، database PostgreSQL است</context> <output_format>فقط کد، بدون توضیح</output_format>»

تفاوت کلیدی: در نسخه‌ی دوم، مدل دقیقاً می‌داند کجا instructions تمام می‌شود و context شروع می‌شود. این تفکیک ساختاری، دقت خروجی را به‌طور محسوسی بالا می‌برد.

یک نکته‌ی عملی که کمتر گفته می‌شود: بسیاری از proxyهای ایرانی context را truncate می‌کنند یا system prompt را دستکاری می‌کنند. اگر از طریق proxy به Claude دسترسی دارید و کیفیت پاسخ پایین است، مشکل به احتمال زیاد از مدل نیست. مستقیم از app، Claude Code یا API استفاده کنید.

Claude Code چطور نصب می‌شه و اولین پروژه رو چطور بهش بدیم؟#

Claude Code یک ابزار CLI ترمینال‌محور است که با npm نصب می‌شود و در دایرکتوری پروژه اجرا می‌گردد. اولین قدم: ساخت فایل CLAUDE.md و اجرای دستور claude در ریشه‌ی پروژه. برخلاف app دسکتاپ، اینجا با یک پروسه‌ی زنده در terminal کار می‌کنید که به فایل‌سیستم شما دسترسی دارد.

پیش‌نیازها و نصب با npm#

Node.js نسخه‌ی LTS (پشتیبانی‌شده) و npm باید روی سیستم نصب باشند. سپس:

  1. دستور npm install -g @anthropic-ai/claude-code را اجرا کنید.
  2. با claude --version نصب را تأیید کنید.
  3. وارد دایرکتوری ریشه‌ی پروژه‌ی خود شوید (cd ~/my-project).
  4. دستور claude را اجرا کنید تا session شروع شود.
  5. در اولین اجرا، از شما خواسته می‌شود که permissions را grant کنید — اینکه ایجنت اجازه دارد کدام فایل‌ها را بخواند و بنویسد.
  6. فایل CLAUDE.md را در ریشه‌ی پروژه بسازید (حتی خالی باشد).
  7. اولین task را بدهید: مثلاً «README.md را بخوان و ساختار پروژه را خلاصه کن».

سیستم permissions و فایل .claude/settings.json#

Claude Code یک فایل تنظیمات در .claude/settings.json نگه می‌دارد که مشخص می‌کند ایجنت به چه ابزارهایی دسترسی دارد. در حالت پیش‌فرض، نوشتن در فایل‌ها نیاز به تأیید دستی دارد. برای محیط‌های trusted می‌توانید auto-approve تنظیم کنید، اما در پروژه‌های production این کار را نکنید.

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

CLAUDE.md: حافظه‌ی پروژه‌ای که .cursorrules نیست#

CLAUDE.md یک memory file در ریشه‌ی پروژه است که قوانین، ساختار و ترجیحات پروژه را به ایجنت منتقل می‌کند. تفاوتش با .cursorrules در الگوی read-then-act و scope‌بندی monorepo است. Claude Code این فایل را در ابتدای هر session می‌خواند و بر اساس آن تصمیم می‌گیرد.

ساختار پیشنهادی CLAUDE.md (چه بگذاریم، چه نگذاریم)#

این فایل باید کوتاه و عملیاتی باشد. نه tutorial بنویسید، نه توضیح درباره‌ی زبان برنامه‌نویسی. فقط چیزهایی که ایجنت بدون آن‌ها تصمیم اشتباه می‌گیرد:

  • ساختار پوشه‌ها و نقش هر بخش
  • فریمورک‌ها و کتابخانه‌های اصلی
  • قوانین code style (مثلاً «از named export استفاده کن، نه default»)
  • دستورات build/test که ایجنت باید اجرا کند
  • ممنوعیت‌ها (مثلاً «فایل‌های داخل node_modules را ویرایش نکن»)

چه نگذاریم: توضیح مفاهیم عمومی، آموزش‌های مقدماتی، یا چیزهایی که ایجنت خودش می‌داند. یک CLAUDE.md که نصفش آموزش TypeScript است، عملاً context را بی‌دلیل پر می‌کند.

CLAUDE.md در monorepo: root + per-package#

در monorepo، یک CLAUDE.md در root برای قوانین global بگذارید (مثلاً «همه‌ی packages از TypeScript strict mode استفاده می‌کنند»). سپس در هر package یک CLAUDE.md محلی برای قوانین خاص آن بخش. الگوی on-demand file reading ایجنت اجازه می‌دهد بدون context stuffing، قوانین محلی را بخواند.

تفاوت با .cursorrules: فایل .cursorrules معمولاً یک متن یکپارچه است که به‌عنوان system prompt تزریق می‌شود. CLAUDE.md در Claude Code با الگوی read-then-act کار می‌کند — یعنی ایجنت خودش تصمیم می‌گیرد چه زمانی فایل را بخواند و چه زمانی عمل کند. این تفاوت ظریف اما مهم است.

مدیریت context window در پروژه‌های بزرگ: الگوی read-then-act#

مدیریت context window در پروژه‌های بزرگ با الگوی read-then-act انجام می‌شود، نه کپی‌پیست کل codebase. Claude با context window 200,000 توکن ظرفیت بالایی دارد؛ اما هرچه context پرتر، هزینه و تأخیر بیشتر و کیفیت نه‌لزوم بالاتر.

چرا کپی‌پیست کل codebase در یک پیام اشتباه است#

سه مشکل عملی دارد. اول، هزینه‌ی توکن‌های input بالا می‌رود. دوم، مدل در میان حجم زیاد، توجهش پخش می‌شود و ممکن است بخش‌های نامربوط را با موارد مرتبط قاطی کند. سوم، در session‌های طولانی، context پر می‌شود و پاسخ‌های بعدی truncate می‌شوند.

بزرگ بودن context window به معنای پر کردنش نیست — دقیقاً برعکس. ظرفیت 200,000 توکن یک سقف است، نه یک هدف.

استراتژی chunking و file scoping#

به‌جای یک پیام بزرگ، task را به مراحل کوچک‌تر بشکنید. مثلاً «فایل src/auth/login.ts را بخوان و validate token را بررسی کن» به‌جای «کل پروژه را تحلیل کن». Claude Code خودش فایل‌ها را می‌خواند و فقط آنچه لازم دارد در context قرار می‌گیرد.

در API، مدیریت context دستی است. باید خودتان مشخص کنید کدام فایل‌ها در هر پیام ارسال شوند. الگوی رایج: system prompt ثابت + user message با ارجاع به فایل‌های خاص + tool results به‌صورت incremental اضافه می‌شوند.

Extended Thinking کِی روشن کنیم و کِی خاموش؟#

Extended Thinking در Claude 3.7 Sonnet برای debugging چندلایه و تصمیمات معماری مفید است؛ برای task‌های ساده مثل rename، format یا تغییر یک خط کد فقط تأخیر و هزینه‌ی اضافی ایجاد می‌کند. این قابلیت مدل را در حالت «thinking mode» قرار می‌دهد که قبل از پاسخ، reasoning chain طولانی‌تری تولید می‌کند.

الگوی تصمیم‌گیری: چه task‌هایی نیاز به thinking دارند#

روشن کنید وقتی:

  • debugging یک race condition یا باگ چندلایه
  • تصمیم معماری (مثلاً انتخاب بین microservice و monolith)
  • refactor کردن کد با وابستگی‌های پیچیده

خاموش کنید وقتی:

  • rename کردن متغیرها
  • format کردن کد
  • نوشتن یک utility function ساده
  • توضیح دادن کد موجود

قاعده‌ی سرانگشتی: اگر task را در سه خط توضیح می‌دهید و خروجی‌اش قطعی است، Extended Thinking فقط پول و زمان می‌سوزاند.

نحوه‌ی فعال‌سازی در API و Claude Code#

در API، Extended Thinking با پارامتر thinking در request body فعال می‌شود. مقدار budget tokens را مشخص می‌کنید که مدل چقدر «فکر» کند. در Claude Code، Extended Thinking را می‌توان به‌صورت دستی فعال یا غیرفعال کرد. برای جزئیات دقیق، مستندات رسمی Anthropic را بررسی کنید چون API ممکن است تغییر کند.

اتصال MCP به Claude Code: معماری client-server#

Model Context Protocol (MCP) یک پروتکل متن‌باز است که ابزارهای خارجی (database، API، filesystem) را به‌صورت tool در اختیار Claude Code قرار می‌دهد. اتصال از طریق یک server محلی انجام می‌شود. MCP یک پروتکل مستقل است و فقط به Claude محدود نیست.

معماری MCP: client-server با protocol استاندارد#

معماری ساده است: یک MCP server محلی اجرا می‌شود که ابزارهای مورد نظر را expose می‌کند. Claude Code به‌عنوان client به این server وصل می‌شود و در طول session، ایجنت می‌تواند tool‌های آن server را صدا بزند. مثلاً یک database MCP server به ایجنت اجازه می‌دهد query بزند بدون اینکه شما SQL بنویسید.

راه‌اندازی MCP server برای database و filesystem#

برای filesystem، معمولاً با یک command ساده شروع می‌شود. برای database، باید connection string و permissions را در config server مشخص کنید. در .claude/settings.json مسیر server و نام آن را تعریف می‌کنید. پس از restart کردن Claude Code، ایجنت ابزارهای جدید را در اختیار دارد.

مزیت اصلی: بدون نوشتن کد اضافی، ایجنت به داده‌های زنده دسترسی پیدا می‌کند. برای API، فعلاً خودتان tool definitions بنویسید. پشتیبانی MCP در API مستقیم محدودتر است و برای کیفیت واقعی، Claude Code یا app دسکتاپ گزینه‌های بهتری هستند.

Claude 3.5 Sonnet یا Opus: کدام برای کدنویسی انتخاب کنم؟#

Claude 3.5 Sonnet برای اکثر task‌های کدنویسی تعادل بهینه‌ی سرعت، کیفیت و هزینه دارد؛ Claude 3.7 Sonnet Extended Thinking را اضافه کرده و برای reasoning پیچیده بهتر است؛ Opus برای task‌های تحلیلی عمیق با بودجه‌ی بالاتر مناسب است. انتخاب مدل به پیچیدگی task بستگی دارد، نه به اینکه «قوی‌تر بهتر است».

مقایسه‌ی مدل‌ها: context، سرعت، هزینه، مناسب برای#

مدلContext Windowسرعت و هزینهمناسب برای
Claude 3.5 Sonnet200K توکنسریع‌تر، ارزان‌تراکثر task‌های کدنویسی، code review، refactor معمولی
Claude 3.7 Sonnet200K توکنبا Extended Thinking کندتر و گران‌ترdebugging پیچیده، تصمیمات معماری، reasoning چندلایه
Claude Opus200K توکنکندترین و گران‌ترینتحلیل عمیق، research، task‌هایی که دقت حیاتی دارند

چه task‌هایی Sonnet را می‌خواهند و چه task‌هایی Opus را#

الگویی که در پروژه‌های واقعی اعضای کامیونیت تکرار می‌شود: برای نوشتن یک API endpoint، نوشتن test، یا refactor یک component، 3.5 Sonnet کافی است. وقتی با باگی مواجه می‌شوید که علتش در تعامل سه فایل مختلف پنهان است، 3.7 Sonnet با Extended Thinking تفاوت ایجاد می‌کند. Opus را برای task‌هایی نگه دارید که اشتباه‌شان هزینه‌ی بالایی دارد — مثلاً تحلیل امنیتی یک codebase.

پیشنهاد شروع: Claude 3.5 Sonnet به‌عنوان پیش‌فرض. اگر debugging پیچیده دارید یا به reasoning عمیق نیاز دارید، 3.7 Sonnet با Extended Thinking را امتحان کنید. Opus را از ابتدا انتخاب نکنید — اکثر کدنویس‌ها به آن نیاز پیدا نمی‌کنند.

ساخت ایجنت: از API استفاده کنیم یا Claude Code؟#

ساخت ایجنت با Claude Code برای workflow ترمینال‌محور و دسترسی فایل‌محور طراحی شده؛ برای ایجنت خودکار با tool use و function calling، Claude API مناسب‌تر است. این دو مکمل‌اند نه جایگزین. اشتباه رایج، تلاش برای ساخت ایجنت production در بطن Claude Code است.

الگوی tool use و function calling در Claude API#

در API، شما tool definitions را در request تعریف می‌کنید. مدل تصمیم می‌گیرد کدام tool را صدا بزند، شما آن را execute می‌کنید و نتیجه را برمی‌گردانید. این الگوی standard agent loop است: model → tool call → execute → result → model → پاسخ نهایی.

چه‌وقت Claude Code کافی است و چه‌وقت به API نیاز دارید#

Claude Code وقتی کافی است که شما پشت terminal نشسته‌اید و می‌خواهید با پروژه‌ی فعلی‌تان کار کنید. API وقتی لازم است که می‌خواهید ایجنتی بسازید که بدون حضور شما کار کند — مثلاً یک code-review bot روی PRها، یا یک chatbot برای کاربران نهایی.

ترکیب رایج: Claude Code برای development (ساخت، تست، debug کردن ایجنت)، API برای production (deploy کردن ایجنت). این الگو در پروژه‌های واقعی کامیونیتی بارها تکرار شده است.

ترکیب Claude Code با git و CI/CD در جریان کار روزانه#

Claude Code مستقیماً با git کار می‌کند: commit، branch، diff و resolve conflict. در CI/CD می‌تواند به‌عنوان reviewer خودکار یا generator در pipeline قرار بگیرد. ایجنت خودش git commands اجرا می‌کند و نیازی نیست شما manual commit بزنید.

جریان کار روزانه: branch → Claude Code → commit → PR#

  1. یک branch جدید بسازید (git checkout -b feature/auth-refactor).
  2. Claude Code را در ریشه‌ی پروژه اجرا کنید.
  3. task را بدهید: «در فایل src/auth.ts، توکن refresh logic را refactor کن».
  4. ایجنت فایل‌ها را می‌خواند، تغییرات را اعمال می‌کند و از شما تأیید می‌خواهد.
  5. تغییرات را review کنید (git diff).
  6. commit بزنید و PR باز کنید.

محدودیت‌ها: چرا Claude Code جایگزین IDE نیست#

Claude Code ابزار ترمینال‌محور است و برای کدنویسی تعاملی IDE (autocomplete، multi-cursor، debug visual) هنوز جایگزین کامل نیست. مکمل‌اند. شما در VS Code یا Cursor کد می‌زنید، و Claude Code را برای task‌های بزرگ‌تر — refactor، نوشتن test، debug — استفاده می‌کنید.

نکته‌ی امنیتی: در محیط production، permissions و sandboxing را جدی بگیرید. ایجنتی که access به فایل‌های حساس دارد باید محدود باشد. هرگز auto-approve را در محیط‌های غیرtrusted فعال نکنید.

هزینه‌ی واقعی: Pro، Max یا API؟#

هزینه‌ی واقعی Claude بستگی به الگوی استفاده دارد، نه صرفاً بودجه. Claude Pro برای استفاده‌ی شخصی از app و Claude Code کافی است؛ Claude Max برای حجم بالای کدنویسی و دسترسی بیشتر به Claude Code طراحی شده؛ API برای ایجنت‌های خودکار و production مناسب است.

مقایسه‌ی پلن‌ها: کدام برای چه ماده‌ی کاری#

پلنمناسب برایمحدودیت اصلی
Claude Proاستفاده‌ی شخصی از app و Claude Code با حجم متوسطusage limit در ساعات اوج
Claude Maxکدنویس حرفه‌ای با حجم بالای sessionهزینه‌ی بالاتر
API (pay-as-you-go)ایجنت خودکار، production، ابزارهای teamنیاز به مدیریت توکن و بودجه

اشتباه رایج: خرید Max بدون نیاز#

خرید Max بدون نیاز، رایج‌ترین هدررفت بودجه در کامیونیت فارسی‌زبان است. خیلی‌ها با دیدن محدودیت Pro فوراً Max می‌خرند. اما اگر روزی دو سه ساعت کد می‌زنید، Pro کافی است. Max را بخرید وقتی واقعاً به session‌های طولانی و مکرر نیاز دارید.

برای API، هزینه‌ی توکن در input و output متفاوت است. الگوی on-demand file reading در Claude Code باعث می‌شود توکن‌های کمتری مصرف شود نسبت به کپی‌پیست دستی context.

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