Claude Code را مثل چت استفاده می‌کنید و نتیجه‌ی ضعیف می‌گیرید؟ مشکل از پرامپت شما نیست. مشکل از ساختار فایلهای پروژه است. این آموزش Claude به‌صورت عملیاتی نشان میدهد که CLAUDE.md، permission model و نحوه‌ی سازمان‌دهی context، تعیین‌کننده‌ی اصلی کیفیت خروجی ایجنت هستند — نه طول و دقت پرامپت.
Claude Code چیست و چه فرقی با چت معمولی Claude دارد؟#
Claude Code یک ابزار agentic CLI (Command-Line Interface) است که به‌جای تولید متن، مستقیماً فایل‌ها را می‌خواند، می‌نویسد، دستورات shell اجرا میکند و در یک حلقه‌ی تکراری تسک را تا رسیدن به وضعیت پایدار پیش می‌برد. تفاوت بنیادین با چت معمولی در همین نقطه است: ایجنت عمل میکند، نه فقط پاسخ میدهد.
وقتی در چت معمولی Claude کد می‌خواهید، خروجی یک بلوک متنی است که باید خودتان copy-paste کنید. در Claude Code، ایجنت فایل را باز میکند، تغییر میدهد، تست می‌گیرد و اگر تست fail شد، دوباره اصلاح میکند. این چرخه بدون دخالت شما تکرار می‌شود تا تسک بسته شود. کسی که این تفاوت را درک نکند، Claude Code را مثل یک IDE گران‌قیمت استفاده میکند و هیچ‌وقت به ظرفیت واقعی آن نمی‌رسد.
معماری agentic loop#
هر تسک در Claude Code از این مراحل عبور میکند: خواندن فایلهای مرتبط → تصمیم‌گیری درباره‌ی تغییر → نوشتن کد → اجرای test یا lint → بررسی نتیجه → تکرار در صورت خطا. نکته‌ای که اکثر کاربران نادیده می‌گیرند: ایجنت در هر دور، context جدیدی از فایل‌سیستم می‌خواند. پس اگر ساختار پروژه‌ی شما آشفته باشد، ایجنت هم آشفته عمل میکند. این یک قانون فیزیکی است، نه یک توصیه‌ی سلیقه‌ای.
نقش مدل‌های Claude در انتخاب سرعت و عمق استدلال#
Anthropic چند مدل ارائه میدهد: Haiku (سریع و ارزان)، Sonnet (متعادل) و Opus (عمیق‌ترین استدلال). در Claude Code، انتخاب مدل مستقیماً روی رفتار ایجنت اثر می‌گذارد. Sonnet برای اکثر تسکهای کدنویسی روزمره کافی است. Opus زمانی لازم می‌شود که تسک نیازمند استدلال چندمرحله‌ای روی معماری یا refactoring گسترده باشد. جزئیات دسترسی و نرخ هر مدل را در مستندات رسمی Anthropic بررسی کنید.
نصب Claude Code: پیش‌نیازها و گام‌های عملی#
نصب Claude Code نیازمند Node.js نسخه‌ی 18 یا بالاتر، یک API key از Anthropic و دسترسی به terminal است. فرآیند راه‌اندازی کوتاه است، اما تنظیمات اولیه‌ی permission و context، کیفیت استفاده‌ی شما را از روز اول مشخص میکند. نصب را با تنظیمات اشتباه نگیرید؛ نصب ۲ دقیقه‌ای است، اما تنظیمات درست ممکن است یک بعدازظهر کامل وقت ببرد.
پیش‌نیازهای سیستم‌عامل#
Claude Code به‌طور مستقیم روی macOS و Linux اجرا می‌شود. برای Windows، استفاده از WSL (Windows Subsystem for Linux) مسیر توصیه‌شده است. Node.js و npm باید نصب باشند. اگر از VS Code استفاده می‌کنید، اتصال به terminal داخلی IDE بدون تغییر workflow ممکن است.
گام‌به‌گام نصب#
- نصب با npm:
npm install -g @anthropic-ai/claude-code - تنظیم احراز هویت: متغیر محیطی
ANTHROPIC_API_KEYرا تنظیم کنید یا در اولین اجرایclaudeمراحل تعاملی را دنبال کنید - ورود به پوشه‌ی پروژه:
cd your-project && claude - ایجاد CLAUDE.md اولیه: ایجنت در اولین اجرا از شما می‌خواهد context پروژه را تعریف کنید
- اجرای اولین تسک: یک refactor ساده روی یک ماژول کوچک به‌عنوان smoke test
نکته‌ی عملی: اولین تسک را عمداً ساده انتخاب کنید. مثلاً rename کردن یک متغیر در چند فایل. هدف این است که رفتار ایجنت، سرعت پاسخ و کیفیت diff را بسنجید قبل از اینکه تسک پیچیده‌ای بسپارید. در کلاس‌های Claude Code، تقریباً همه‌ی تازه‌واردها این مرحله را رد میکنند و مستقیم سراغ تسکهای بزرگ می‌روند — و بعد شکایت میکنند که ایجنت «خروجی بیربط» میدهد.
CLAUDE.md: حافظه‌ی پروژه‌ی شما را چطور بنویسید؟#
CLAUDE.md فایلی است که به Claude Code بافت (context) دائمی پروژه میدهد. مؤثرترین نسخه‌ی آن کوتاه، scoped به یک subdirectory و حاوی قوانین خاص همان ماژول است — نه یک راهنمای generic در ریشه. این فایل، قلب context engineering (مهندسی بافت) شماست و بدون آن، ایجنت هر بار از صفر شروع میکند.
بسیاری از کاربران تازه‌کار یک CLAUDE.md بزرگ در ریشه‌ی پروژه می‌نویسند و انتظار معجزه دارند. این اشتباه رایج است. ایجنت در هر تسک، تمام context را بارگذاری نمیکند؛ بلکه بر اساس فایلهایی که لمس میکند، CLAUDE.md مربوطه را می‌خواند. پس اگر فایل ریشه‌ی شما 200 خط توضیحات عمومی دارد، عملاً هیچ‌کدام به کار ایجنت نمی‌آید.
الگوی scoped context#
در یک monorepo یا پروژه‌ی چند-ماژولی، هر ماژول باید CLAUDE.md مستقل خودش را داشته باشد. این فایل فقط conventions، ساختار پوشه‌ها و دستورات build/test همان ماژول را توصیف میکند. نتیجه: ایجنت هنگام کار روی ماژول A، فقط context ماژول A را می‌بیند — نه توضیحات ماژول B. این الگو در پروژه‌های اعضای کامیونیتی بارها تکرار شده و هر بار با افزایش محسوس دقت خروجی همراه بوده است.
چه چیزی بنویسیم#
- Conventions کدنویسی: نام‌گذاری، import style، الگوهای رایج
- ساختار پوشه‌ها و وظیفه‌ی هر پوشه
- دستورات build، test و lint
- قوانین خاص: «هرگز فایل config را مستقیم edit نکن، از script استفاده کن»
- مرزهای dependency: کدام ماژول‌ها مجاز به import یکدیگر هستند
چه چیزی ننویسیم#
- توضیحات عمومی درباره‌ی زبان برنامه‌نویسی
- Duplicate از README
- لیست تمام APIها و endpointها
- فلسفه‌ی پروژه یا تاریخچه‌ی تصمیمات
این تفکیک، تفاوت بین یک CLAUDE.md مؤثر و یک فایل بی‌استفاده را مشخص میکند. ایجنت به اطلاعات عملیاتی نیاز دارد، نه به مستندات آموزشی. اگر چیزی را از README کپی کرده‌اید، احتمالاً جایش در CLAUDE.md نیست.
Context engineering در برابر prompt engineering#
Prompt engineering روی «چطور بگوییم» تمرکز دارد. Context engineering روی «چه اطلاعاتی در دسترس ایجنت باشد» تمرکز دارد. در Claude Code، دومی برنده است. یک پرامپت 500 کلمه‌ای بدون ساختار فایلهای درست، نتیجه‌ی ضعیف میدهد. یک پرامپت 20 کلمه‌ای با CLAUDE.md scoped و permission model تنظیم‌شده، خروجی قابل‌اتکا تولید میکند. این گلوگاه واقعی است که اکثر آموزش‌های فارسی‌زبان نادیده می‌گیرند.
Permission model: نقطه‌ی کور امنیتی که اکثر آموزش‌ها نادیده می‌گیرند#
مدل مجوزهای Claude Code تعیین میکند ایجنت به کدام فایل‌ها بنویسد و کدام دستورات shell را اجرا کند. تنظیم نادرست آن میتواند به حذف داده، تغییر config حساس یا اجرای کد مخرب منجر شود. این بخش در اکثر آموزش‌های Claude Code به‌صورت جدی پوشش داده نمی‌شود، درحالی‌که پتانسیل آسیب آن از هر تنظیم دیگری در این ابزار بالاتر است.
Claude Code از default permission model استفاده میکند که برای شروع امن است، اما بسیاری از کاربران برای سرعت، auto-approve را فعال میکنند. این تصمیم در پروژه‌های production یا پروژه‌هایی که secrets دارند، ریسک جدی ایجاد میکند.
سطوح دسترسی#
- Read-only: ایجنت فقط فایل می‌خواند و پیشنهاد میدهد. بدون نوشتن.
- Write scoped: ایجنت فقط در مسیرهای مشخص (مثلاً
src/) می‌نویسد. - Command execution: ایجنت میتواند دستورات shell اجرا کند. این سطح خطرناک‌ترین است.
چه زمانی auto-approve خطرناک است#
در پروژه‌هایی که شامل database migration، CI/CD config، فایلهای secret یا deploy script هستند، auto-approve را غیرفعال نگه دارید. یک اشتباه در این مسیرها میتواند production را خراب کند. ایجنت با حسن نیت عمل میکند، اما درک آن از «این فایل حساس است» به context شما وابسته است — و اگر context ننوشته باشید، ایجنت هم نمی‌فهمد.
استراتژی hybrid#
تجربه‌ی میدانی از پروژه‌های واقعی نشان میدهد مؤثرترین رویکرد، تقسیم‌بندی تسک‌هاست:
- به ایجنت بسپارید: refactoring، نوشتن test، formatting، migration ساده، اضافه‌کردن type annotation
- دستی نگه دارید: تغییر schema database، edit configهای deploy، نوشتن auth logic، تغییر permission model
این مرزبندی را در CLAUDE.md هم ثبت کنید تا ایجنت خودش بداند کجا باید از شما اجازه بگیرد. بدون این ثبت، ایجنت در تسکهای ترکیبی — مثلاً «این endpoint را refactor کن و migration هم بنویس» — ممکن است بخش migration را هم خودکار انجام دهد.
Claude Code بهتر است یا Cursor؟ مقایسه‌ی عملیاتی در workflow واقعی#
Claude Code و Cursor در طیف متفاوتی کار میکنند. Cursor یک IDE با autocomplete و chat داخلی است. Claude Code یک ایجنت CLI است که تسکهای چندفایلی و multi-step را خودکار میکند. انتخاب بین آن‌ها به نوع تسک شما بستگی دارد، نه به «بهتر بودن» مطلق یکی.
مقایسه‌ی «Claude Code یا Cursor» مثل مقایسه‌ی «جرثقیل یا آچار» است — هر دو ابزار هستند، اما برای کارهای متفاوت. Claude Code در Skills (قابلیتهای تعریفشدهی قابلاستفادهی مجدد) و Subagent (ایجنت‌های فرعی که تسکهای موازی را انجام میدهند) قابلیت‌هایی دارد که در ابزارهای IDE-centric کمتر دیده می‌شود. اما اگر کار شما بیشتر در یک فایل متمرکز است، Cursor با autocomplete سریع‌تر جواب میدهد.
جدول مقایسه‌ای#
| ابزار | نوع | بهترین برای | پشتیبانی multi-file |
|---|---|---|---|
| Claude Code | Agentic CLI | Refactoring چندفایلی، migration، نوشتن test suite | بومی و قوی |
| Cursor | AI IDE | ویرایش درون‌فایلی، autocomplete، chat با context | محدود (chat-based) |
| GitHub Copilot | Autocomplete plugin | تکمیل خطی، نوشتن سریع boilerplate | نخیر |
| Aider | Agentic CLI (open-source) | تسکهای ساده با مدل‌های مختلف | بله |
معیار انتخاب بر اساس نوع تسک#
اگر تسک شما شامل تغییر همزمان 5 فایل به بالا است — مثلاً rename یک interface در کل پروژه، یا اضافه‌کردن یک field به model و migration و API handler — Claude Code مسیر طبیعی‌تر است. اگر تسک در یک فایل متمرکز است و به بازخورد لحظه‌ای نیاز دارید، Cursor یا Copilot مناسب‌ترند.
الگوی ترکیبی#
بسیاری از توسعه‌دهندگان حرفه‌ای هر دو را همزمان استفاده میکنند: Claude Code در terminal برای تسکهای بزرگ و multi-step، و یک editor مثل VS Code یا Cursor برای ویرایش‌های ریز و review diff. این الگو، بهترین‌های هر دو را ترکیب میکند. در گفتگوهای مکرر اعضای کامیونیتی، این الگوی ترکیبی به‌عنوان پایدارترین workflow گزارش شده است.
مدیریت هزینه و انتخاب مدل مناسب برای هر تسک#
هزینه‌ی Claude Code مستقیماً به انتخاب مدل و حجم context وابسته است. برای اکثر تسکهای کدنویسی روزمره، Sonnet کافی است و Opus هزینه‌ی غیرضروری تحمیل میکند. مدیریت context window — یعنی چه فایلهایی در دسترس ایجنت باشند — بزرگ‌ترین اهرم هزینه‌ی شماست.
Sonnet در برابر Opus#
Sonnet برای نوشتن test، refactoring، bug fix و کارهای معمولی کدنویسی تعادل بهتری بین سرعت و کیفیت دارد. Opus زمانی توجیه دارد که تسک نیازمند استدلال عمیق روی معماری باشد — مثلاً طراحی یک سیستم جدید، تحلیل trade-off بین الگوهای design pattern، یا debug یک race condition پیچیده. برای تسکهای ساده، Opus سرعت را کم و هزینه را زیاد میکند بدون بهبود محسوس کیفیت. استفاده از Opus برای نوشتن یک test ساده، مثل استفاده از تانک برای خرید نانوایی است.
بهینه‌سازی context window#
هر فایلی که در context ایجنت باشد، token مصرف میکند. CLAUDE.md بزرگ و generic در ریشه، فایلهای بیربط که ایجنت آن‌ها را می‌خواند، و node_modules اگر exclude نشده باشد — همه هزینه‌ی غیرضروری ایجاد میکنند. راه‌حل: scoped CLAUDE.md، .claudeignore برای حذف فایلهای بیربط، و exclude کردن build artifacts.
استراتژی مدل‌های ترکیبی#
- Haiku: ساده‌سازی کد، formatting، توضیح خط به خط
- Sonnet: coding، refactoring، نوشتن test
- Opus: architecture decisions، complex debugging، multi-step reasoning
این تقسیم‌بندی در پروژه‌های واقعی مکرر دیده شده است. ایجنت‌هایی مثل Claude Code اجازه میدهند برای هر تسک مدل متفاوتی انتخاب کنید — یا با Subagent، یک تسک را با مدل ارزان‌تر و تسک دیگر را با مدل گران‌تر حل کنید.
رایج‌ترین اشتباهات در استفاده از Claude Code#
تقریباً تمام کاربران تازه‌کار، Claude Code را مثل یک چت‌بات استفاده میکنند. پرامپت طولانی می‌نویسند، جواب می‌گیرند و منتظر هستند. در حالی که ارزش اصلی Claude Code در حلقه‌ی agentic و تعامل خودکار با فایل‌سیستم است. این آموزش Claude روی همین نقطه تأکید دارد.
اشتباه «prompt بنویس، جواب بگیر»#
اگر پرامپت شما 300 کلمه است و ایجنت فقط یک فایل را تغییر میدهد، دارید Claude Code را مثل چت استفاده می‌کنید. الگوی صحیح: تسک را به‌صورت هدف تعریف کنید («interface جدید را در تمام فایلهایی که از آن استفاده میکنند update کن»)، نه به‌صورت دستورالعمل مرحله‌به‌مرحله. ایجنت خودش مسیر را پیدا میکند. هرچه پرامپت شما شبیه دستورالعمل باشد، رفتار ایجنت شبیه چت‌بات می‌شود.
CLAUDE.md بزرگ و generic#
یک فایل 200 خطی در ریشه با توضیحات عمومی درباره‌ی Python و TypeScript، نه context مفیدی میدهد نه هزینه‌ی token را کم میکند. ایجنت از این فایل‌ها گیج می‌شود. الگوی مؤثر: فایلهای کوتاه، scoped، عملیاتی.
اعتماد مطلق در کدهای حساس#
Claude Code در security-sensitive code — auth logic، crypto، input validation — بدون review انسانی قابل‌اتکا نیست. ایجنت ممکن است الگویی تولید کند که syntactically درست باشد اما security flaw داشته باشد. همیشه diff را قبل از merge بازنگری کنید. این یک محدودیت ذاتی مدل‌های زبانی است، نه یک باگ قابل‌رفع.
مقایسه با autocomplete#
بسیاری Claude Code را با Copilot مقایسه میکنند و می‌گویند «Copilot سریع‌تر است». این مقایسه نادرست است چون معماری متفاوت است. Copilot یک خط کد پیشنهاد میدهد. Claude Code یک تسک کامل را اجرا میکند. این‌ها جایگزین یکدیگر نیستند.
چه زمانی Claude Code مناسب نیست؟#
Claude Code برای debugهای نیازمند بازنگری انسانی (race conditions، logic bugs پیچیده)، کدهای حساس به امنیت، و تسک‌هایی که context آن‌ها در یک فایل متمرکز است، ابزار مناسبی نیست. شناخت مرزهای ابزار، بخشی از استفاده‌ی مؤثر از آن است.
تسک‌هایی که روش سنتی بهتر جواب میدهد#
وقتی bug شما نیازمند breakpoint، step-through debugging و بررسی stack trace در runtime است، Claude Code کمکی نمیکند. این ابزار فایل‌سیستم را می‌بیند، نه اجرای برنامه را. برای race conditions، timing bugs و memory leaks، debugger سنتی همچنان ابزار اصلی است.
محدودیت‌های فعلی#
Claude Code در ساخت ایجنت‌های سفارشی (custom agent) و automation پیچیده محدودیت دارد. اگر نیازمند workflowهای شرطی چندمرحله‌ای هستید — مثلاً «اگر تست fail شد، مدل را عوض کن و دوباره امتحان کن» — باید از ابزارهایی مثل n8n یا frameworkهای ایجنت‌محور استفاده کنید.
نقش MCP در گسترش قابلیت‌ها#
MCP (Model Context Protocol) یک پروتکل استاندارد برای اتصال مدل‌های زبانی به ابزارهای خارجی است. Claude Code با MCP servers میتواند به database، API یا deployment pipeline دسترسی پیدا کند. این قابلیت، ایجنت را از «ابزار فایل‌سیستم» به «ابزار متصل به اکوسیستم توسعه» تبدیل میکند. اما اکوسیستم MCP هنوز در حال رشد است و تمام integrations مورد نیاز در دسترس نیستند.
جمع‌بندی عملی: Claude Code ابزاری قدرتمند است، اما قدرتش از پرامپت خوب نمی‌آید — از ساختاردهی فایل‌ها، CLAUDE.md scoped و permission model درست می‌آید. اگر این سه را تنظیم کنید، حتی با پرامپت‌های ساده، خروجی قابل‌اتکا می‌گیرید.
اگر می‌خواهید Claude Code و ابزارهای مشابه را در یک workflow عملیاتی یاد بگیرید، دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» در کامیونیتی Claude اسکول دقیقاً همین مسیر را پوشش میدهد — از context engineering تا ساخت ایجنت بدون کدنویسی.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته میشوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.