آموزش Claude Code اگر به نصب و اجرای اولین دستور خلاصه شود، بزرگ‌ترین بخش ماجرا از دست رفته است. این ابزار یک چت‌بات ترمینالی نیست؛ معماری agentic آن — یعنی توانایی برنامه‌ریزی، اجرا و خودبررسی — همان چیزی است که یاد گرفتنش، فاصله‌ی بین استفادهی سطحی و کار حرفه‌ای را تعیین میکند. بدون فهم این معماری، هر آموزشی ناقص است.
معماری agentic Claude Code: چرا آن را با Cursor یا Copilot مقایسه نکنیم#
Claude Code را نباید با Cursor یا Copilot مقایسه کرد، چون این سه ابزار سه مدل ذهنی کاملاً متفاوت دارند. Claude Code یک ایجنت چندمرحله‌ای (multi-step agent) است که خودش برنامه می‌چیند، اجرا میکند و نتیجه را بررسی میکند؛ Cursor و Copilot در این سطح از استقلال عملیاتی قرار ندارند و مقایسهی مستقیم، انتظار نادرست می‌سازد.
مشکل اصلی بیشتر آموزش‌های فارسی‌زبان این است که Claude Code را به‌عنوان یک چت‌بات ترمینالی معرفی می‌کنند. در واقع، وقتی شما یک task به Claude Code می‌دهید، او ابتدا فایلهای مرتبط را اسکن میکند، یک plan داخلی می‌سازد، تغییرات را اعمال میکند و سپس نتیجه را با اجرای تست یا lint بررسی میکند. این چرخه‌ی plan→execute→verify (برنامه‌ریزی→اجرا→بررسی) هسته‌ی معماری agentic آن است.
سه مدل workflow: agentic در برابر inline editing در برابر autocomplete#
در مدل agentic (Claude Code)، شما یک task توصیف می‌کنید و ابزار خودش تصمیم می‌گیرد کدام فایل‌ها را بخواند، چه تغییراتی بدهد و چطور نتیجه را اعتبارسنجی کند. در مدل inline editing (Cursor)، شما روی یک خط خاص تمرکز دارید و ابزار پیشنهاد ویرایش میدهد. در مدل autocomplete (Copilot)، ابزار بر اساس context فعلی خط بعدی را پیش‌بینی میکند.
تفاوت عملی اینجاست: اگر task شما «این endpoint را بازنویسی کن و تست‌ها را آپدیت کن» باشد، Claude Code خودش هر دو کار را انجام میدهد. Cursor و Copilot در این سطح از استقلال عملیاتی نیستند — نه به‌خاطر ضعف، بلکه به‌خاطر طراحی.
جدول مقایسه‌ای: نوع task، تعامل، context management و best use case#
| معیار | Claude Code | Cursor | Copilot |
|---|---|---|---|
| نوع تعامل | task-based (توصیف کامل) | line-based (ویرایش نقطه‌ای) | completion-based (پیش‌بینی) |
| مدیریت context | اسکن خودکار فایل‌ها + CLAUDE.md | context پنجره باز + @-mention | context فایل باز |
| بهترین use case | refactor، bugfix، feature با چند فایل | ویرایش سریع داخل فایل | تکمیل خط‌های تکراری |
| توانایی multi-file | بله — ذاتی | محدود | خیر |
| اعتبارسنجی خروجی | اجرای test و lint | خیر | خیر |
چه زمانی Claude Code انتخاب اشتباه است؟#
سه حالت وجود دارد که استفاده از Claude Code توجیه اقتصادی و عملیاتی ندارد:
- پروژههای بسیار کوچک که در چند دقیقه قابل‌خوانش و درک‌اند — overhead تنظیم CLAUDE.md و یادگیری workflow بیشتر از صرفهی آن است.
- taskهایی که نیاز به پیشنهاد لحظهای (real-time inline suggestion) دارند — در این حالت Cursor یا Copilot سریع‌ترند.
- تیمهایی که comfort با workflow ترمینالی ندارند — Claude Code ذاتاً CLI-based است و اگر تیم با terminal آشنا نباشد، اصطکاک ورودی بالا می‌رود.
الگوی مشاهده‌شده در پروژههای اعضای کامیونیتی: کاربرانی که Claude Code را جایگزین Cursor کرده‌اند و از عدم‌توانایی در inline editing شکایت دارند، معمولاً model mental اشتباهی دارند. آن‌ها ابزار را با معیار ابزار دیگر ارزیابی می‌کنند. این اشتباه، پرهزینه‌تر از آن است که به‌نظر می‌رسد — چون نه‌تنها وقت هدر می‌رود، بلکه اعتماد به ابزار هم از بین می‌رود.
Claude Code را چطور نصب کنیم و اولین task را به آن بدهیم؟#
نصب Claude Code از طریق npm و با Node.js نسخه‌ی 18 یا بالاتر انجام میشود و به یک حساب Anthropic با دسترسی API نیاز دارد. اولین task باید یک تغییر کوچک و قابل‌بررسی باشد تا الگوی agentic را در عمل تجربه کنید، نه یک feature بزرگ.
چرا اولین task باید کوچک باشد؟ چون می‌خواهید ببینید Claude واقعاً plan میکند یا فقط کد تولید. اگر task بزرگ بدهید، تشخیص این تفاوت عملاً غیرممکن میشود.
پیش‌نیازها#
قبل از نصب، این موارد را چک کنید:
- Node.js نسخه‌ی 18 یا بالاتر روی سیستم نصب باشد.
- حساب Anthropic فعال داشته باشید و به API دسترسی داشته باشید.
- یک پروژه‌ی واقعی (نه خالی) روی سیستم باز باشد تا Claude Code context داشته باشد.
مستندات رسمی Anthropic پیش‌نیازهای دقیق را در صفحهی documentation منتشر میکند. اگر در نصب به مشکل خوردید، ابتدا نسخه‌ی Node.js را با node --version چک کنید.
گام‌های نصب و اولین مکالمه در ترمینال#
نصب از طریق npm انجام میشود. پس از نصب، در پوشه‌ی پروژه دستور راه‌اندازی را اجرا می‌کنید. Claude Code در ترمینال باز میشود و منتظر task شماست. اولین مکالمه باید کوتاه و مشخص باشد — مثلاً «تابع X در فایل Y یک bug دارد، اصلاحش کن و تست بزن».
اولین task ایده‌آل#
بهترین اولین task یک bugfix یا refactor کوچک است که فقط یک یا دو فایل را درگیر کند. دلیلش ساده است: می‌خواهید ببینید Claude واقعاً plan میکند یا فقط کد تولید میکند. اگر task بزرگ بدهید، تشخیص این تفاوت سخت میشود.
یک مثال عملی: «در فایل auth.service.ts، متد validateToken یک edge case دارد که اگر token منقضی باشد null برمی‌گرداند به‌جای throw کردن خطا. اصلاحش کن و مطمئن شو تست‌های مربوطه پاس می‌شوند.»
بررسی خروجی — چطور بفهمیم Claude واقعاً plan کرده؟#
Claude Code معمولاً قبل از اجرای تغییرات، یک خلاصه از برنامه‌اش نمایش میدهد: «اول فایل X را می‌خوانم، سپس متد Y را اصلاح می‌کنم، بعد تست Z را اجرا می‌کنم.» اگر این خلاصه را دیدید، ابزار در حالت agentic کار کرده. اگر مستقیم کد نوشت و تمام، احتمالاً context کافی نداشته و به حالت «تولید متن» برگشته.
CLAUDE.md چطور نوشته شود که Claude واقعاً به آن پایبند بماند؟#
CLAUDE.md یک فایل ساختاریافته در ریشه‌ی پروژه است که قوانین پروژه، conventions کدنویسی، لیست do/don't و notes معماری را مشخص میکند. فایل ساختاریافته با بخش‌های مجزا نتیجهی بهتری از promptهای طولانی و کلی میدهد، چون Claude Code آن را به‌صورت system-level instruction بارگذاری میکند.
این تفاوت را دست‌کم نگیرید: با CLAUDE.md ساختاریافته، Claude در چندین session متوالی رفتار منسجم دارد؛ بدون آن، هر session ممکن است conventions متفاوتی را پیشنهاد دهد.
ساختار پیشنهادی CLAUDE.md#
یک CLAUDE.md مؤثر چهار بخش اصلی دارد:
- Project Overview: یک پاراگراف کوتاه درباره‌ی هدف پروژه، stack و معماری کلی.
- Coding Conventions: قوانین مشخص — نام‌گذاری، الگوهای import، ساختار پوشه‌ها.
- Do / Don't List: لیست صریح کارهایی که مجاز و غیرمجاز است.
- Architecture Notes: توضیح درباره‌ی الگوهای معماری خاص پروژه که از روی کد قابل‌استنباط نیستند.
نمونه‌ی یک بخش Do/Don't:
Do: از functional components استفاده کن. Don't: کلاس component جدید اضافه نکن. Do: state management را فقط در store.ts انجام بده. Don't: useState محلی برای داده‌ی مشترک بین چند component استفاده نکن.
اشتباهات رایج#
دو اشتباه اصلی در نوشتن CLAUDE.md:
- نوشتن توضیحات عمومی به‌جای قوانین قابل‌اجرا. «پروژه ما یک اپلیکیشن وب است» هیچ ارزشی ندارد. «پروژه ما از pattern Repository برای دسترسی به دیتابیس استفاده میکند و هرگز نباید مستقیم در controller query نوشت» یک قانون قابل‌اجراست.
- نداشتن do/don't list. بدون این بخش، Claude در تصمیم‌گیری‌های معماری آزاد عمل میکند و ممکن است الگویی بسازد که با conventions پروژه در تضاد است.
تنظیم nested CLAUDE.md برای monorepo#
در monorepo باید یک CLAUDE.md سطح ریشه برای قوانین مشترک داشته باشید و فایلهای CLAUDE.md جداگانه در هر package برای conventions اختصاصی آن پکیج. بدون این ساختار، Claude Code در context packageهای مختلف گیج میشود — مثلاً قوانین TypeScript یک package را روی package جاوااسکریپتی اعمال میکند.
CLAUDE.md به‌عنوان router#
یک الگوی پیشرفته: در CLAUDE.md ریشه بنویسید که برای taskهای مربوط به backend، قوانین در packages/backend/CLAUDE.md و برای frontend در packages/frontend/CLAUDE.md هستند. این کار باعث میشود Claude Code به‌جای بارگذاری کل context، فقط بخش مرتبط را بخواند.
الگوی تکرارشونده در پروژههای اعضای کامیونیتی: کاربرانی که CLAUDE.md ساختاریافته نوشته‌اند، پایبندی بالاتری از Claude نسبت به کاربران با prompt کلی مشاهده کرده‌اند. تفاوت عملی این است که با فایل ساختاریافته، Claude در چندین session متوالی رفتار منسجم دارد؛ بدون آن، هر session ممکن است conventions متفاوتی را پیشنهاد دهد.
الگوی plan→execute→verify: ساخت ایجنت چندمرحله‌ای با Claude API#
الگوی plan→execute→verify یعنی taskهای بزرگ را به چرخه‌های کوچک تقسیم کنید؛ هر چرخه یک خروجی قابل‌بررسی دارد. Claude Code در هر مرحله فقط یک تصمیم می‌گیرد نه یک پاسخ کامل. این الگو هسته‌ی کار حرفه‌ای با Claude Code است.
سؤال اصلی اینجاست: چرا یک prompt بزرگ و کلی نتیجهی بدتری از سه چرخه‌ی کوچک دارد؟
چرا یک prompt بزرگ و کلی نتیجهی بدتری از سه چرخه‌ی کوچک دارد؟#
وقتی یک task بزرگ را در یک prompt توصیف می‌کنید، Claude باید هم‌زمان همه‌ی تصمیمات را بگیرد: معماری، نام‌گذاری، ترتیب اجرا، و اعتبارسنجی. این بار شناختی (cognitive load) باعث میشود کیفیت تصمیمات میانی افت کند. در مقابل، تقسیم به چرخه‌های plan→execute→verify هر بار یک تصمیم مشخص می‌سازد و خروجی قابل‌بررسی تولید میکند.
مثال عملی: به‌جای «سیستم احراز هویت کامل بساز» بنویسید: «فقط schema کاربر و مدل توکن را طراحی کن.» سپس در چرخه‌ی بعد: «با توجه به schema قبلی، middleware احراز هویت را پیاده‌سازی کن.» و در چرخه‌ی سوم: «تست‌های integration برای این دو فایل بنویس.»
پیاده‌سازی الگو در Claude Code#
در Claude Code، این الگو ذاتی است. ابزار خودش plan می‌سازد و از شما تأیید می‌خواهد. اما اگر plan اولیه را نپسندیدید، می‌توانید بگویید «plan را تغییر بده، اول تست بنویس بعد کد» و ابزار چرخه را بازتعریف میکند. نکته‌ی عملی: هر بار که plan جدیدی می‌خواهید، task قبلی را کامل کرده باشید تا context تمیز بماند.
پیاده‌سازی الگو با Claude API#
اگر از Claude API (نه Claude Code) استفاده می‌کنید، می‌توانید همین الگو را با system prompt و function calling بسازید. system prompt مشخص میکند که مدل اول plan بدهد، سپس با هر فراخوانی تابع، یک مرحله execute شود، و در انتها verify انجام شود.
مستندات Anthropic در مورد structured output و system prompt برای این الگو مناسب‌اند.
Anti-pattern مخصوص Claude: excessive chain-of-thought instruction#
روی مدلهایی مثل GPT-4، دستورات «فکر کن مرحله به مرحله» و «هر تصمیمت را توضیح بده» نتیجهی بهتری میدهد. روی Claude، این الگو گاهی نتیجهی معکوس دارد. دلیلش معماری متفاوت training است. Claude ذاتاً structured reasoning دارد و افزودن instructionهای chain-of-thought اضافی، context را آلوده میکند و مدل را به سمت verbose شدن میبَرَد بدون بهبود کیفیت.
به‌جای این کار، از CLAUDE.md و taskهای مشخص استفاده کنید. ساختار را بیرون از prompt بگذارید، نه داخل آن.
MCP و Hooks: نقاط اتصال Claude Code به اکوسیستم توسعه#
Model Context Protocol (MCP) ابزارهای خارجی را به Claude Code وصل میکند و Hooks workflow را خودکار می‌کنند. این دو ویژگی هسته‌ی قدرت Claude Code هستند، نه افزونه‌های ثانویه. بدون آن‌ها، Claude Code فقط یک code generator است؛ با آن‌ها یک ایجنت یکپارچه در محیط توسعه‌ی شما میشود.
این را صریح بگویم: اگر فقط Claude Code نصب کرده‌اید و هنوز MCP server ننوشته‌اید، از ظرفیت واقعی ابزار استفاده نمی‌کنید.
MCP چیست و چطور server بنویسیم#
MCP یک پروتکل باز است که توسط Anthropic معرفی شده و امکان اتصال ابزارهای خارجی به Claude Code را فراهم میکند. با نوشتن یک MCP server، می‌توانید database، linter، test runner یا هر ابزار دیگری را به‌عنوان tool در دسترس Claude Code قرار دهید.
مثال عملی: یک MCP server بنویسید که به PostgreSQL وصل شود. حالا Claude Code میتواند مستقیم schema دیتابیس را بخواند، query بنویسد و نتیجه را بررسی کند — بدون اینکه شما context را دستی کپی کنید.
Hooks در Claude Code#
Hooks نقاطی در workflow هستند که می‌توانید اسکریپت‌های خود را در آن‌ها اجرا کنید. مثلاً pre-commit hook که قبل از هر commit، lint و type-check را اجرا کند. اگر خطا داشت، commit انجام نشود و Claude Code خودش خطا را ببیند و اصلاح کند.
ترکیب MCP + Hooks: یک workflow واقعی#
سناریوی عملی: Claude Code یک feature جدید می‌نویسد → post-write hook اجرا میشود و testها را می‌زند → اگر fail کرد، Claude خودش خطا را می‌خواند و اصلاح میکند → pre-commit hook lint و type-check را اجرا میکند → اگر پاس شد، commit انجام میشود.
این چرخه‌ی کامل بدون دخالت دستی شما اجرا میشود. MCP server دیتابیس هم در این workflow نقش دارد: Claude میتواند schema را چک کند و مطمئن شود migration با ساختار فعلی سازگار است.
نکته‌ی مهم: MCP در مستندات رسمی Anthropic توضیح داده شده. برای جزئیات پیاده‌سازی، به documentation رسمی مراجعه کنید.
مدیریت context window و کاهش هزینه با prompt caching#
مدل Claude 3.5 Sonnet context window حدود 200,000 توکن دارد. در پروژههای بزرگ، مدیریت این context و کاهش هزینه با prompt caching ضروری است. استراتژی‌های عملی شامل chunking، selective file loading، و استفاده از CLAUDE.md به‌عنوان router هستند.
بی‌خیال هزینهی API شوید اگر context را مدیریت نکنید؛ یک session بی‌هدف در پروژه‌ی بزرگ، چند دلار را بی‌آنکه متوجه شوید می‌بلعد.
استراتژی‌های عملی مدیریت context#
- Chunking: کد را به بخش‌های منطقی تقسیم کنید و فقط بخش مرتبط را در context بگذارید.
- Selective loading: با CLAUDE.md مشخص کنید که برای taskهای خاص، کدام فایل‌ها لازم‌اند.
- Router pattern: در monorepo، هر package قوانین خودش را دارد و Claude فقط package مرتبط را می‌خواند.
Prompt caching در Anthropic API#
Prompt caching امکان‌ای است که Anthropic در API خود ارائه میدهد. اگر بخش بزرگی از prompt ثابت است (مثلاً CLAUDE.md یا system prompt)، cache میشود و در requestهای بعدی هزینهی کمتری دارد. این ویژگی برای مکالمات طولانی و taskهای تکراری مؤثر است.
قیمتگذاری دقیق per-token در صفحهی pricing سایت Anthropic منتشر میشود و ممکن است تغییر کند.
انتخاب مدل بر اساس use case#
برای کدنویسی روزمره، Claude 3.5 Sonnet بهترین تعادل بین سرعت و کیفیت را دارد. Claude 3.5 Haiku برای taskهای سبک و سریع مناسب است. Claude 3 Opus برای تحلیل‌های معماری پیچیده و taskهایی که نیاز به reasoning عمیق دارند استفاده میشود. انتخاب نهایی به نوع task و budget بستگی دارد.
لیست گام‌به‌گام بهینه‌سازی هزینه در پروژه‌ی واقعی#
- CLAUDE.md را به‌عنوان router تنظیم کنید تا فقط context لازم بارگذاری شود.
- prompt caching را برای بخش‌های ثابت فعال کنید.
- برای taskهای سبک از Haiku استفاده کنید و فقط taskهای پیچیده را به Sonnet یا Opus بسپارید.
- sessionهای طولانی را با taskهای جدید reset کنید تا context متورم نشود.
الگوی مشاهده‌شده در پروژههای واقعی: کاربرانی که این چهار گام را رعایت می‌کنند، مصرف توکن‌شان در مقایسه با استفادهی خام از Claude Code به‌طور محسوسی کاهش می‌یابد. جزئیات قیمتگذاری و نحوه‌ی فعال‌سازی caching را از مستندات رسمی Anthropic چک کنید.
جمع‌بندی عملی#
Claude Code یک ابزار autocomplete نیست. یک ایجنت چندمرحله‌ای است که اگر معماری agentic آن را بفهمید، الگوی plan→execute→verify را درست پیاده کنید، CLAUDE.md ساختاریافته بنویسید و از MCP و Hooks استفاده کنید، یک همکار برنامه‌نویس در ترمینال دارید. اگر این‌ها را نادیده بگیرید، یک چت‌بات گران‌قیمت دارید.
اگر می‌خواهید این الگوها را در عمل تمرین کنید و با بقیه‌ی کاربرانی که دارند حرفه‌ای با Claude کار می‌کنند، کامیونیتی Claude در اسکول و دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» دقیقاً همین مسیر را پوشش میدهد — از نصب تا ساخت ایجنت واقعی با Vibe Coding.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته می‌شوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.