Claude Code را نمیشود با ذهنیت چت‌باکس یا autocomplete استفاده کرد. ارزش واقعی‌اش در workflow ایجنتی چندمرحله‌ای و ساختاردهی پروژه با فایل CLAUDE.md نهفته است، نه در ترفندهای پرامپتنویسی. این آموزش، اشتباهات پرهزینه‌ای را توضیح میدهد که در آموزش‌های عمومی پیدا نمی‌کنید: بازآرایی کد بدون پوشش تست، context آلوده، و sessionهای بی‌پایان که خروجی را غیرقابل‌اعتماد می‌کنند.
Claude Code یک چت‌باکس نیست: تفاوت ایجنت ترمینالی با رابط چت#
Claude Code یک ایجنت ترمینالی (Terminal Agent) است که در هر turn می‌تواند فایل بخواند، دستور bash اجرا کند، کد بنویسد و ابزارهای خارجی را فراخوانی کند. برخلاف چت‌باکس Claude که صرفاً متن تولید میکند، اینجا یک عامل اجرایی دارید که مستقیماً در محیط پروژه‌ی شما کار میکند.
در حالت interactive، چرخه‌ی کار به این شکل است: پرامپت شما را می‌خواند، تصمیم می‌گیرد کدام ابزار لازم است، آن را اجرا میکند، نتیجه را می‌بیند، و گام بعدی را بر اساس همان نتیجه طراحی میکند. این چند-ابزاری‌بودن در یک turn، تفاوت بنیادین با هر رابط چتی است. شما با یک دستیار متنی طرف نیستید؛ با یک عاملی طرفید که تصمیمهای اجرایی می‌گیرد.
حالت غیرتعاملی (Non-Interactive) با پرچم -p رفتار کاملاً متفاوتی دارد. ابزارهای ویرایش فایل و اجرای bash به‌صورت پیش‌فرض غیرفعال‌اند مگر با flagهای خاص. این حالت برای اسکریپت‌نویسی و CI/CD ساخته شده، نه برای کار روزمره‌ی توسعه. اگر بدون flagهای لازم در حالت non-interactive task بدهید، Claude Code فقط متن تولید میکند و هیچ فایلی تغییر نمیکند — و شما فکر می‌کنید کار انجام شده.
چرا این تفاوت مهم است؟#
اگر Claude Code را یک چت‌باکس داخل CLI بدانید، پرامپتهای توصیفی و persona setting می‌نویسید. خروجی ظاهراً درست است اما اجرا نمیشود. در مقابل، اگر ذهنیت ایجنتی داشته باشید، taskهای مشخص تعریف می‌کنید، CLAUDE.md را به‌عنوان زمینه‌ی پروژه می‌سازید، و از Claude Code می‌خواهید خودش فایل بخواند و تغییر بدهد. این تفاوت، کیفیت خروجی را چند برابر میکند.
Node.js پیش‌نیاز اجرای ابزار است. برای نسخه‌ی دقیق پشتیبانیشده، مستندات رسمی Anthropic را بررسی کنید؛ این جزئیات در نسخههای مختلف تغییر میکند.
از نصب تا اولین task واقعی در ترمینال#
Claude Code از طریق npm نصب میشود، به Node.js نیاز دارد و با اشتراک Claude Pro یا Max قابل استفاده است. اولین task باید یک پرس‌وجوی ساده‌ی ساختار پروژه باشد، نه یک بازآرایی (Refactoring) بزرگ. شروع با task کوچک، هم context را سالم نگه می‌دارد و هم به شما نشان میدهد ابزار واقعاً چه فایل‌هایی می‌خواند.
گام‌های نصب:
- Node.js را نصب یا به‌روزرسانی کنید.
- دستور
npm install -g @anthropic-ai/claude-codeرا اجرا کنید. - با دستور
claudeوارد شوید و با اشتراک Pro یا Max احراز هویت کنید. - در پوشه‌ی پروژه‌ی خود دستور
claudeرا اجرا کنید.
انتخاب پلن: Claude Pro سهمیهی کمتری از توکن و درخواست دارد. Claude Max برای استفاده‌ی سنگین‌تر طراحی شده. تفاوت دقیق سهمیه‌ها را از صفحه‌ی اشتراک‌ها بررسی کنید چون ممکن است تغییر کرده باشد.
اولین task پیشنهادی: در پوشه‌ی پروژه بنویسید «ساختار این پوشه را توضیح بده و فایل‌های اصلی را شناسایی کن». دو فایده دارد. اول، Claude Code را مجبور نمی‌کنید کد بنویسد. دوم، می‌بینید چه فایل‌هایی را واقعاً می‌خواند و context را چطور مصرف میکند. این اطلاعات، مبنای تنظیم excludeها در CLAUDE.md میشود.
اولین ویرایش: یک تغییر کوچک بخواهید — مثلاً اصلاح یک نام متغیر یا افزودن یک comment. diff را قبل از commit بازبینی کنید. اگر diff را نخوانید، در taskهای بعدی با باگ‌هایی مواجه می‌شوید که منبع‌شان همین ویرایش‌های کوچک بازبینی‌نشده است. الگویی که در پروژههای اعضای کامیونیتی مکرر تکرار میشود: سه‌هفته بعد، یک bug report می‌آید، git blame می‌کنید، و به یک ویرایش‌ی Claude Code برمی‌خورید که کسی diffاش را نخوانده بود.
استفاده در CI/CD با حالت غیرتعاملی#
پرچم -p خروجی را به‌صورت text چاپ میکند. برای اسکریپت‌نویسی مناسب است اما محدودیت‌های جدی دارد: ابزارهای ویرایش فایل و bash به‌صورت پیش‌فرض اجرا نمی‌شوند. برای taskهای خودکار در pipeline، باید flagهای مربوطه را فعال کنید. مستندات رسمی را برای فهرست دقیق flagها بررسی کنید.
فایل CLAUDE.md: مغز پروژه یا زباله‌دان دستورات؟#
فایل CLAUDE.md زمینه‌ساز رفتار Claude Code در هر پروژه است. محتوای آن باید محدود به اطلاعاتی باشد که مدل بدون آن‌ها نمی‌تواند درست تصمیم بگیرد، نه تکرار README. هر خط اضافی، توکن مصرف میکند و context آلوده میکند. این فایل، مؤثرترین نقطهی تنظیم ابزار است — مهمتر از هر ترفند پرامپتنویسی.
ساختار بهینه شامل چهار بخش است: قوانین کدنویسی پروژه، معماری سطح بالا، excludeها (پوشه‌هایی که نباید خوانده شوند)، و دستورالعمل‌های تست. این چهار بخش، رفتار Claude Code را بیشتر از هر چیز دیگری تنظیم می‌کنند.
در مونورپو، الگوی CLAUDE.md تودرتو (Nested) کاربرد دارد: هر زیرپوشه فایل CLAUDE.md خودش را دارد. Claude Code نزدیک‌ترین فایل CLAUDE.md را نسبت به پوشه‌ی فعلی می‌خواند. یعنی قوانین هر بخش از پروژه، مستقل از بخش‌های دیگر اعمال می‌شوند. این برای پروژه‌هایی که هر ماژول فریمورک یا الگوی معماری متفاوتی دارد، حیاتی است.
اشتباه رایج: ریختن تمام README و مستندات API داخل CLAUDE.md. نتیجه: context آلوده، پاسخ‌های ناقص، و هزینه‌ی توکن بالا. CLAUDE.md جایگزین مستندات نیست؛ فقط اطلاعاتی را بگذارید که برای تصمیم‌گیری کدنویسی لازم است.
چه چیزی در CLAUDE.md بنویسیم و چه چیزی ننویسیم؟#
بنویسید: نام فریمورک و نسخه، الگوی معماری (مثلاً MVC یا component-based)، قوانین linting، مسیر فایل‌های تست، و excludeها. ننویسید: توضیح هر endpoint API، تاریخچه‌ی پروژه، یا راهنمای نصب dependencyها.
تجربه‌ی میدانی: exclude در پروژههای بزرگ#
در پروژه‌هایی با صدها فایل، بدون exclude مشخص، Claude Code پوشه‌هایی مثل node_modules، build و dist را هم می‌خواند. این رفتار، context را بی‌فایده پُر میکند و پاسخ‌ها را بی‌ربط می‌سازد. الگوی exclude را از همان ابتدا در CLAUDE.md تعریف کنید، نه بعد از اولین مشکل. در کلاس‌های عملی، تقریباً همه‌ی شرکت‌کنندگان در اولین session بزرگ، همین اشتباه را مرتکب می‌شوند و بعد متوجه می‌شوند نصف context صرف خواندن فایل‌های build شده است.
چطور context window را در پروژههای بزرگ مدیریت کنیم؟#
پنجره‌ی بافت (Context Window) در مدلهای Claude 3.x برابر 200,000 توکن است. در پروژههای بزرگ، این ظرفیت به‌سرعت پر میشود. راه‌حل، تقسیم کار به taskهای کوچک و استفاده از exclude است، نه خرید پلن گران‌تر.
نشانه‌های context overflow: پاسخ‌های ناقص، فراموش کردن فایل‌هایی که قبلاً خوانده شده، تکرار کد، و تولید خروجی‌های بی‌ربط به task اصلی. اگر این نشانه‌ها را دیدید، session فعلی دیگر قابل‌اعتماد نیست. ادامه دادن فقط هزینه‌ی توکن را بالا میبرد و خروجی بدتر میشود.
راه‌حل اول: task بزرگ را به زیرtaskهای مستقل بشکنید. هر زیرtask پرامپت جداگانه‌ی خودش را دارد و Claude Code فقط فایل‌های مرتبط را می‌خواند.
راه‌حل دوم: exclude در CLAUDE.md. هر پوشه‌ای که به task فعلی ربطی ندارد را مشخص کنید.
راه‌حل سوم: برای هر feature یک session جدید باز کنید. ادامه‌ی sessionهای طولانی، احتمال فراموشی context را بالا میبرد.
چه زمانی session جدید باز کنیم؟#
قاعده‌ی ساده: اگر Claude Code فایلی را فراموش کرد که در همان session خوانده بود، یا پاسخ‌هایش بی‌ربط به task فعلی شد، session جدید باز کنید. صبر کردن برای «بهتر شدن» بی‌فایده است؛ context پر شده و هر turn اضافه فقط هزینه‌ی توکن را بالا میبرد.
Claude Code در برابر Cursor، Copilot و Aider: کدام ابزار برای کدام task؟#
این ابزارها در لایه‌های متفاوت کار می‌کنند و جایگزین یکدیگر نیستند. Copilot برای autocomplete خطی، Cursor برای ویرایش در IDE، Claude Code برای workflow ایجنتی چندمرحله‌ای در ترمینال، و Aider برای تغییرات diff-based مناسب‌اند. مقایسه‌ی این‌ها به‌عنوان رقیب، یک اشتباه مفهومی رایج است.
| ابزار | لایه‌ی عملکرد | نوع تعامل | مناسب برای | نامناسب برای |
|---|---|---|---|---|
| Claude Code | ایجنت ترمینالی | چند ابزار در یک turn | taskهای چندمرحله‌ای، ساخت فایل جدید، workflow کامل | تغییرات تک‌خطی، پروژههای legacy بدون تست |
| Cursor | IDE هوشمند | ویرایش تعاملی | ویرایش روزانه، debug سریع | taskهای خودکار در pipeline |
| GitHub Copilot | تکمیل خودکار (Autocomplete) | پیشنهاد خطی | تکمیل کد در حین تایپ | تغییرات چندفایلی، refactor |
| Aider | CLI diff-based | درخواست تغییر + review | تغییرات کوچک با diff واضح | workflow ایجنتی چندمرحله‌ای |
توصیه‌ی عملی: ترکیب Cursor برای ویرایش روزانه + Claude Code برای taskهای چندمرحله‌ای مؤثرتر از استفاده‌ی انحصاری از هر کدام است. این دو ابزار مکمل‌اند، نه رقیب. در عمل، بسیاری از توسعه‌دهندگان حرفه‌ای هر دو را همزمان استفاده می‌کنند: Cursor برای تایپ روزانه و Claude Code برای کارهایی که نیاز به خواندن چند فایل و تصمیم چندمرحله‌ای دارند.
الگوی explore-then-execute: اول بفهم، بعد تغییر بده#
رایج‌ترین الگوی موفق در پروژههای واقعی: قبل از هر ویرایش، از Claude Code بخواهید فایل‌های مرتبط را بخواند و ساختار را توضیح دهد. سپس task ویرایش را جداگانه بدهید. این الگو، احتمال تولید کد ناسازگار را به‌طور محسوس کاهش میدهد. آموزش‌های عمومی معمولاً این گام را حذف می‌کنند و مستقیم سراغ «کد بنویس» می‌روند — و بعد با خروجی‌هایی مواجه می‌شوند که فایل‌های import شده را نمی‌شناسند.
MCP: اتصال ابزارهای خارجی به Claude Code#
پروتکل MCP (Model Context Protocol) توسط Anthropic معرفی شده و به Claude Code اجازه میدهد ابزارهای خارجی مثل دیتابیس، API و فایل‌سیستم‌های خاص را در یک turn فراخوانی کند. این پروتکل، استانداردسازی ارتباط ایجنت با ابزار است و محدودیت‌های فایل‌سیستم محلی را دور می‌زند.
نصب یک MCP server ساده: در فایل تنظیمات Claude Code، server موردنظر را تعریف می‌کنید. پس از فعال‌سازی، Claude Code در هر turn می‌تواند ابزارهای آن server را مثل فایل‌خوانی و bash اجرا کند.
مثال‌های کاربردی: اتصال به PostgreSQL برای پرس‌وجوی داده، خواندن از Figma API برای تبدیل design به کد، و جستجو در vector database برای retrieval. هر کدام از این‌ها، taskهای چندمرحله‌ای را در یک turn قابل‌انجام می‌کنند.
چه زمانی MCP واقعاً لازم است و چه زمانی نه؟#
اگر task شما فقط خواندن و نوشتن فایل در پروژه است، MCP لازم نیست. Claude Code خودش این کار را میکند. MCP زمانی ارزش دارد که به داده‌ای نیاز دارید که بیرون از فایل‌سیستم پروژه است: دیتابیس، API خارجی، یا سرویس خاص سازمانی. اضافه کردن MCP server بدون نیاز واقعی، فقط پیچیدگی و سطح حمله‌ی ابزار را بالا میبرد.
اشتباهات پرهزینه‌ای که توسعه‌دهندگان در کار با Claude Code مرتکب می‌شوند#
پرهزینه‌ترین اشتباه، استفاده از Claude Code برای بازآرایی کد legacy بدون پوشش تست است. خروجی ظاهراً درست به نظر می‌رسد، diff تمیز است، اما باگهای پنهان ایجاد میکند که شناسایی‌شان در production چند روز طول می‌کشد. این اشتباه، به‌اندازه‌ی یک sprint عقب‌گرد هزینه دارد.
اشتباه اول: اعتماد کورکورانه به خروجی بدون بازبینی diff. human-in-the-loop الزامی است. حتی اگر Claude Code یک خط تغییر بدهد، آن خط را بخوانید.
اشتباه دوم: یک پرامپت بزرگ برای کل refactor. context آلوده میشود و خروجی غیرقابل‌اعتماد. task را بشکنید.
اشتباه سوم: نادیده‌گرفتن CLAUDE.md و تکیه بر persona setting. ساختار پروژه مؤثرتر از لحن پرامپت است. اگر CLAUDE.md درست بنویسید، حتی با پرامپتهای ساده، خروجی بهتری می‌گیرید.
اشتباه چهارم: استفاده در پروژههای بدون test suite. بدون تست، نمی‌فهمید چه چیزی شکسته. Claude Code در این محیط‌ها با اعتماد‌به‌نفس بالا، کد نادرست تولید میکند.
اشتباه پنجم: ادامه‌ی sessionهای بسیار طولانی بدون reset. context فراموش میشود و پاسخ‌ها بی‌ربط می‌شوند.
Checklist قبل از هر task#
- CLAUDE.md به‌روز است و excludeها تعریف شده‌اند؟
- task به زیرtaskهای مستقل شکسته شده؟
- پوشش تست برای بخش‌های درگیر وجود دارد؟
- session فعلی context کافی دارد یا باید جدید باز شود؟
- بعد از اجرا، diff بازبینی میشود؟
چه زمانی Claude Code ابزار مناسبی نیست؟#
Claude Code در پروژههای بسیار بزرگ با وابستگی‌های پیچیده، کد legacy بدون تست، و taskهایی که نیاز به درک همزمان چندین هزار فایل دارند، خروجی قابل‌اعتمادی تولید نمیکند. شناختن این مرز، به‌اندازه‌ی یادگیری خود ابزار مهم است. ابزاری که همیشه «بهترین» باشد وجود ندارد.
پروژههای با وابستگی‌های عمیق و غیرمستقیم (Transitive Dependencies): context اشباع میشود و Claude Code تصمیمهای ناسازگار می‌گیرد. در این موارد، IDE سنتی + autocomplete سریع‌تر و قابل‌اعتمادتر است.
کد legacy بدون test suite: خروجی Claude Code نیاز به بازنویسی دارد. هزینه‌ی بازنویسی بیشتر از نوشتن دستی است.
taskهای تک‌خطی: استفاده از Claude Code برای تغییر نام یک متغیر، هزینه‌ی session را بی‌دلیل بالا می‌برید. برای این کارها، خودتان سریع‌تر هستید.
مرز بین کمک و آسیب#
سؤال ساده: آیا بعد از اجرای task، میتوانید صحت خروجی را با تست یا بازبینی دستی تأیید کنید؟ اگر بله، Claude Code کمک میکند. اگر نه — چون تست ندارید یا تغییر آن‌قدر بزرگ است که بازبینی دستی ممکن نیست — Claude Code آسیب می‌زند. این معیار، تمام بحث‌های ابزارشناسی را خلاصه میکند.
نتیجه‌ی عملی: Claude Code ابزاری قدرتمند است، اما فقط با ذهنیت ایجنتی، فایل CLAUDE.md درست‌ساخته‌شده، و الگوی explore-then-execute. اگر این سه را رعایت کنید، workflow شما از «چت با AI» به «اجرای task با AI» تغییر میکند و تفاوت خروجی محسوس است.
اگر می‌خواهید این workflow را در پروژه‌ی واقعی تمرین کنید و با ساختار CLAUDE.md و الگوهای ایجنتی از صفر شروع کنید، دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» در کامیونیتی اسکول دقیقاً همین مسیر را پوشش میدهد. برای ثبت‌نام و مشاهده‌ی سرفصل‌ها، صفحه‌ی دوره در کامیونیتی Claude را ببینید.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته می‌شوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.