Claude Code یک ایجنت ترمینالی (Terminal Agent) است که فایل‌سیستم را میخواند، کد می‌نویسد، تست اجرا میکند و اگر خطا دید، خودش بازمی‌گردد. چت‌باکس نیست؛ تفاوتش با Cursor و Copilot در اجرای command و دسترسی به کل repo است. از نصب و تنظیم CLAUDE.md تا اتصال MCP server و مدیریت هزینه‌ی توکن، همه‌چیز را با جزئیات عملی پوشش می‌دهیم.
Claude Code چیست و چه تفاوتی با چت‌باکس یا API دارد؟#
Claude Code یک ابزار CLI ایجنتی (agentic CLI tool) است که خودش فایلها را میخواند، کد می‌نویسد، تست اجرا میکند و در حلقه‌ی بازگشتی (feedback loop) خروجی را اصلاح میکند. برخلاف چت‌باکس که context را دستی paste میکنید یا API که فقط پاسخ متنی برمی‌گرداند، Claude Code به فایل‌سیستم و shell دسترسی مستقیم دارد.
سه حالت استفاده از Claude وجود دارد و هر کدام معماری متفاوتی دارند:
- چت‌باکس وب: شما context را دستی paste میکنید، مدل پاسخ متنی میدهد، و شما کد را copy-paste میکنید.
- API: برنامه‌نویس‌محور است. شما request را از کد می‌فرستید و response را پردازش میکنید.
- Claude Code: ایجنت خودش repo را scan میکند، فایلها را میخواند، command اجرا میکند و خروجی تست را می‌بیند.
مثال عملی: فرض کنید می‌خواهید یک endpoint در Express.js را refactor کنید. در چت‌باکس باید 5 فایل مرتبط را کپی و paste کنید. در Claude Code، ابزار خودش با grep و read به فایلهای لازم دسترسی پیدا میکند و بدون دخالت شما refactor را انجام میدهد.
تفاوت معماری با Cursor هم مشخص است: Cursor IDE-centric است (inline completion و chat در editor) و context محدود به فایل باز دارد. Claude Code terminal-centric است و به کل repo دسترسی دارد. اگر task شما چندفایلی است، Cursor عملاً فلج میشود چون نمیتواند فایلهای بسته را ببیند.
نصب و راه‌اندازی Claude Code#
Claude Code از طریق npm نصب میشود، به Node.js نسخه 18 یا بالاتر نیاز دارد و در ترمینال اجرا میگردد. پیش‌نیازها محدود به runtime و دسترسی به فایل‌سیستم پروژه است؛ هیچ IDE یا افزونه‌ی جانبی لازم نیست.
گام‌های نصب:
- Node.js نسخه 18 یا بالاتر را نصب کنید.
- ترمینال باز کنید (Terminal در macOS، PowerShell در Windows، یا iTerm2).
- دستور
npm install -g @anthropic-ai/claude-codeرا اجرا کنید. - با
claude --versionصحت نصب را تأیید کنید. - با
claudeوارد session شوید و احراز هویت انجام دهید.
برای احراز هویت دو مسیر دارید: اشتراک Claude Pro/Max (از طریق login) یا API key (از طریق متغیر محیطی). اگر اشتراک ندارید، باید از API pay-per-token استفاده کنید.
تنظیمات اولیه و دسترسی‌های فایل‌سیستم#
Claude Code هنگام اجرا permissions می‌خواهد. در اولین session، ابزار از شما اجازه‌ی خواندن و نوشتن فایلها را می‌پرسد. در محیط‌های حساس (production server، پروژههای با دادهی محرمانه) حتماً scope دسترسی را محدود کنید. تنظیمات permissions در فایل .claude/settings.json قابل کنترل است.
اولین task ساده برای تست workflow#
یک repo کوچک باز کنید و یک task ساده بدهید: «فایل index.js را بخوان و توضیح بده چه میکند». اگر ایجنت فایل را خواند و پاسخ منطقی داد، نصب صحیح است. حالا یک task بازنویسی کوچک بدهید و ببینید آیا خودش تست اجرا میکند یا نه.
گردش‌کار ایجنتی: read → plan → implement → test → fix#
الگوی صحیح استفاده از Claude Code حلقه‌ی تکرارشونده است: ایجنت فایل میخواند، برنامه‌ریزی میکند، کد می‌نویسد، تست اجرا میکند و در صورت خطا بازمی‌گردد. انتظار ساخت کل feature با یک پرامپت، اشتباه رایج one-shot prompting است که در پروژههای اعضای کامیونیتی بارها تکرار شده و همیشه به کد ناپایدار ختم شده است.
چرا one-shot prompting شکست می‌خورد؟ چون context window محدود است و ایجنت نمیتواند تمام repo را یکجا در حافظه بگیرد. همچنین بدون بازخورد تست، ایجنت از صحت خروجی‌اش مطمئن نیست و عملاً حدس می‌زند.
هر مرحله از حلقه:
- Read: ایجنت فایلهای مرتبط را میخواند (config، source، test).
- Plan: بر اساس خوانده‌شده، استراتژی refactor یا implementation را تعریف میکند.
- Implement: کد را می‌نویسد یا ویرایش میکند.
- Test: command تست اجرا میکند (مثلاً
npm test). - Fix: اگر تست fail شد، بازمی‌گردد و اصلاح میکند.
الگوی prompt برای refactor چندفایلی#
به‌جای «کل این فایل را بازنویسی کن»، task را تقسیم کنید:
«فایل auth/middleware.ts را بخوان. dependencyهایش را شناسایی کن. اگر هیچ‌کدام از فایلهای دیگر به exportهایش وابسته‌اند، interface را تغییر بده و testهای مرتبط را update کن.»
این prompt scope را مشخص میکند، sub-task تعریف میکند، و ایجنت را مجبور میکند قبل از تغییر، وابستگی‌ها را بررسی کند. نکته‌ی کلیدی: شرط «اگر هیچ‌کدام وابسته نیستند» جلوی ویرایش‌های مخرب را می‌گیرد.
الگوی prompt برای نوشتن test از روی implementation موجود#
ایجنت برای نوشتن test بسیار مؤثر است، چون implementation را میخواند و edge caseها را استخراج میکند:
«فایل utils/date-helpers.ts را بخوان. برای هر function export شده، test بنویس که happy path و یک edge case را پوشش دهد. از Jest استفاده کن و test را در __tests__/date-helpers.test.ts قرار بده.»
اگر test command در CLAUDE.md تعریف شده باشد، ایجنت خودش test را اجرا و اصلاح میکند و شما فقط review میکنید.
CLAUDE.md: فایلی که کیفیت خروجی را تعیین میکند#
CLAUDE.md یک فایل config در ریشه‌ی پروژه است که conventions، معماری، قوانین do/don't و دستورالعمل‌های تست را به ایجنت منتقل میکند. تأثیرش بر کیفیت خروجی آنقدر زیاد است که انتخاب مدل، در مقایسه با تنظیم این فایل، تقریباً بی‌اهمیت میشود.
ساختار پیشنهادی CLAUDE.md:
- Architecture notes: توضیح مختصر معماری پروژه (مثلاً «این پروژه monorepo است با 3 package: web، api، shared»).
- Naming conventions: قوانین نام‌گذاری (camelCase برای متغیر، PascalCase برای component).
- Do/Don't rules: «هرگز از any استفاده نکن»، «همیشه error handling داشته باش».
- Test commands: «قبل از commit حتماً npm run lint و npm test را اجرا کن».
وقتی CLAUDE.md درست تنظیم باشد، ایجنت از همان iteration اول conventions را رعایت میکند و تعداد دورهای اصلاح (fix loop) کاهش می‌یابد. این یعنی توکن کمتری مصرف میشود و هزینه پایین‌تر می‌آید. در پروژههای واقعی، تنظیم CLAUDE.md قبل از شروع کار، معمولاً iterations را به‌طور محسوسی کم میکند.
CLAUDE.md برای پروژههای monorepo#
در monorepo، می‌توانید CLAUDE.md در ریشه‌ی هر package بگذارید. ایجنت هنگام کار در یک package، فایل CLAUDE.md همان package را میخواند. الگوی رایج: یک CLAUDE.md عمومی در ریشه (برای conventions مشترک) و فایلهای اختصاصی در هر package.
اشتباه رایج: CLAUDE.md را به README تبدیل کردن#
README برای انسان است. CLAUDE.md برای ایجنت است. اگر README را کپی کنید و بهعنوان CLAUDE.md استفاده کنید، ایجنت با اطلاعات بی‌استفاده (تاریخچه‌ی پروژه، نحوه‌ی deploy، changelog) context را پر میکند و عملاً بودجه‌ی توکن را روی چیزهای بی‌ربط هدر میدهد. CLAUDE.md باید فقط شامل دستورات اجرایی و قوانین فنی باشد.
MCP چیست و چطور Claude Code را از کدنویسی به ایجنت‌سازی ارتقا میدهد؟#
Model Context Protocol (MCP) پروتکلی است که ابزارهای خارجی (database، API داخلی، سرویس‌های ابری) را بهصورت server به Claude Code وصل میکند. بدون MCP، ایجنت فقط فایل‌سیستم محلی را می‌بیند. با MCP، state واقعی سیستم را میخواند و تصمیماتش بر اساس دادهی زنده گرفته میشود، نه حدس از روی کد محلی.
مفهوم MCP server: یک process مستقل است که tools و resources را با پروتکل استاندارد MCP در اختیار ایجنت قرار میدهد. با Node.js یا Python قابل توسعه است.
نحوه‌ی اتصال: تنظیمات در .claude/settings.json یا flag خط فرمان. ایجنت هنگام اجرا به MCP server متصل میشود و tools آن را در دسترس می‌گیرد.
مثال عملی PostgreSQL: یک MCP server برای database بنویسید که schema را به ایجنت بدهد. حالا وقتی می‌گویید «migration بنویس»، ایجنت schema واقعی را میخواند و migration درست تولید میکند. بدون MCP، ایجنت schema را از فایلهای محلی حدس می‌زند و migrationهای ناقص یا غلط می‌سازد.
مثال عملی API داخلی: MCP server که endpointهای Swagger/OpenAPI را parse میکند. ایجنت قبل از نوشتن client code، schema واقعی API را بررسی میکند.
ساخت MCP server ساده با Node.js#
SDK رسمی Anthropic شامل ابزارهای اولیه برای ساخت MCP server است. حداقلها: یک process که با stdio یا SSE با ایجنت ارتباط برقرار میکند و چند tool expose میکند. مستندات رسمی Anthropic شامل مثالهای شروعبهکار است.
امنیت MCP — محدود کردن scope دسترسی server#
MCP server به داده‌های حساس (database، secrets) دسترسی دارد. اصول امنیتی:
- فقط tools مورد نیاز را expose کنید، نه همه‌چیز.
- read-only access بدهید مگر واقعاً نیاز به write باشد.
- در محیط production، MCP server را با credentials محدود اجرا کنید.
- هرگز MCP server را بدون review به repo عمومی commit نکنید.
این چهار مورد را جدی بگیرید. یک MCP server با write access که بهصورت تصادفی commit شده، میتواند به secrets دسترسی پیدا کند و در لاگ session باقی بماند.
کدام مدل Claude برای کدنویسی مناسب است؟#
انتخاب مدل Claude برای کدنویسی به پیچیدگی task و بودجه‌ی توکن بستگی دارد. Claude 3.5 Sonnet برای کارهای روزمره، مدلهای جدیدتر Sonnet برای reasoning پیچیده‌تر، و Claude Opus برای معماری سطح بالا مناسب است. الگوی انتخاب: ساده‌ترین مدلی که task را حل کند، نه قوی‌ترین.
الگوی عملی که در پروژههای واقعی تکرار میشود:
- Implementation روزمره: Sonnet — سرعت بالا، هزینه پایین، کیفیت قابل‌قبول برای اکثر کارها.
- Architecture review و reasoning پیچیده: Opus — عمق تحلیل بیشتر، اما هزینه و latency بالاتر.
- Taskهای ساده (rename، formatting): Haiku — ارزان‌ترین گزینه.
تأثیر انتخاب مدل بر token consumption در agentic loop مهم است. Opus در هر iteration توکن بیشتری مصرف میکند (output طولانی‌تر) ولی ممکن است iterations کمتری نیاز داشته باشد. Sonnet iterations بیشتری لازم دارد ولی هر iteration ارزان‌تر است. در عمل، برای taskهای زیر 5 فایل، Sonnet تقریباً همیشه جواب میدهد و Opus فقط برای تحلیل معماری چندلایه ارزش هزینه دارد.
برای جزئیات capability هر مدل، مستندات رسمی Anthropic را بررسی کنید. این جدول ثابت نیست و مدلها به‌روزرسانی میشوند.
هزینه‌ی پنهان Claude Code و مدیریت مصرف توکن#
هزینه‌ی Claude Code در گردش‌کار ایجنتی چند برابر یک chat ساده است. هر iteration شامل خواندن فایلها (input token)، نوشتن کد (output token) و اجرای تست است. context compaction و تقسیم task ابزارهای اصلی کنترل هزینه‌اند. بدون این دو، یک session ایجنتی ساده میتواند هزینه‌ی یک هفته چت را در چند دقیقه بسوزاند.
چرا هزینه‌ی ایجنتی ≠ هزینه‌ی چت؟ در چت شما یک بار سوال می‌پرسید. در ایجنت، هر iteration چندین فایل را میخواند. اگر 10 فایل 500 خطی بخواند، فقط در یک iteration، بیش از 5000 خط input token مصرف شده است.
تکنیک‌های مدیریت هزینه:
- Context compaction: sessionهای طولانی را خلاصه کنید. ایجنت از خلاصه استفاده میکند نه از کل تاریخچه.
- تقسیم task: به‌جای یک session بزرگ، چند session کوچک‌تر باز کنید.
- CLAUDE.md دقیق: هرچه ایجنت conventions را بهتر بداند، iterations کمتر لازم دارد.
- مدل مناسب برای task: برای rename کردن از Opus استفاده نکنید.
اشتراک Claude Pro/Max در برابر API pay-per-token: اگر روزانه چندین session ایجنتی اجرا میکنید، اشتراک بهصرفهتر است. اگر استفاده sporadic است، API pay-per-token. جزئیات قیمت‌گذاری را از صفحه‌ی pricing Anthropic بررسی کنید چون مدام تغییر میکند.
Claude Code در برابر Cursor، GitHub Copilot و Windsurf#
تفاوت بنیادین معماری است، نه UI. Cursor IDE-centric است (inline completion و chat در editor)، Claude Code terminal-centric است (full repo access و اجرای command). این تفاوت، نوع workflow را تعیین میکند و انتخاب بین این دو، انتخاب بین «ویرایش سریع در editor» و «اجرای task چندفایلی با feedback loop» است.
| معیار | Claude Code | Cursor | GitHub Copilot | Windsurf |
|---|---|---|---|---|
| معماری | Terminal-centric، agentic loop | IDE-centric، inline + chat | IDE plugin، autocomplete | IDE-centric، agentic flow |
| دسترسی | کل فایل‌سیستم + اجرای command | فایلهای باز + context محدود | فایل باز + context window | فایلهای پروژه + terminal |
| نوع task مناسب | Refactor چندفایلی، نوشتن test، debug با اجرای command | Edit سریع داخل editor، completion | Autocomplete خطی | Agentic flow در IDE |
| مدلهای پشتیبانی | Claude (Anthropic) | چند مدل (Claude، GPT، و...) | OpenAI | چند مدل |
مقایسه‌ی عملی: اگر task شما «این component را refactor کن، test بنویس، و مطمئن شو lint pass میشود» است، Claude Code بهترین گزینه است. اگر «این خط را کامل کن» است، Copilot سریع‌تر است. اگر «در editor فعلی edit بده» است، Cursor طبیعی‌تر است.
چه زمانی ترکیب Cursor + Claude Code بهتر از هرکدام تنهاست#
الگوی رایج در پروژههای واقعی: Cursor برای editهای سریع روزمره + Claude Code برای taskهای سنگین چندفایلی. بسیاری از توسعه‌دهندگان هر دو را هم‌زمان استفاده می‌کنند. Cursor در editor باز است برای inline edit، و وقتی task بزرگ میشود، در ترمینال Claude Code را اجرا می‌کنند. این ترکیب نه تضاد دارد نه تکرار — هر ابزار در نقطه‌ی قوت خودش کار میکند.
اشتباهات رایج و چه زمانی نباید از Claude Code استفاده کرد#
رایج‌ترین اشتباهات: one-shot prompting، ندانستن scope، نادیده گرفتن CLAUDE.md، و استفاده برای مشکلاتی که با grep حل میشوند. Claude Code برای debug خطای single-line، کارهای UI design، و زمانی که developer هنوز مشکل را درک نکرده، مناسب نیست. پرهزینه‌ترین اشتباه، استفاده از ایجنت برای کاری است که در 30 ثانیه با grep حل میشود.
اشتباه 1 — One-shot prompting: انتظار ساخت کل feature با یک پرامپت. ایجنت بدون feedback loop نمیتواند کیفیت را تضمین کند.
اشتباه 2 — ندانستن scope: ایجنت بدون محدودیت، فایلهای نامرتبط را ویرایش میکند. همیشه مشخص کنید کدام فایلها در scope هستند.
اشتباه 3 — استفاده برای grep-able problem: خطای typo در یک فایل با grep در چند ثانیه حل میشود. ایجنت برای این کار overkill است و توکن هدر میدهد.
اشتباه 4 — CLAUDE.md خالی: بدون conventions، ایجنت سبک‌های مختلف را مخلوط میکند و شما در هر iteration اصلاح میکنید.
اشتباه 5 — نادیده گرفتن permissions: ایجنت بدون محدودیت به فایل‌سیستم حساس (env، secrets، production config) دسترسی پیدا میکند.
مواردی که Claude Code مناسب نیست#
- پروژههای single-file: context overhead بیهوده است.
- UI design و pixel-perfect layout: ایجنت نمیتواند design visual را «ببیند».
- Task بدون تعریف شفاف: اگر خودتان نمی‌دانید چه می‌خواهید، ایجنت هم نمی‌داند.
- Debug خطاهای runtime پیچیده که نیاز به breakpoint و step-through دارند.
Best practice برای محیط‌های حساس و production#
در محیط‌های production:
- ایجنت را فقط در branch غیر-production اجرا کنید.
- خروجی را همیشه قبل از merge review کنید.
- CLAUDE.md را با قوانین سخت‌گیرانه تنظیم کنید (مثلاً «هیچ‌وقت فایل .env را ویرایش نکن»).
- MCP serverها را با read-only credentials اجرا کنید.
این قوانین محدودکننده‌اند، ولی در پروژه‌هایی که secrets در فایلهای config ذخیره شده، یک ویرایش ناخواسته میتواند فاجعه‌بار باشد.
Claude Code برای کار تیمی: تنظیمات و workflow مشترک#
برای استفاده تیمی، CLAUDE.md باید در repo commit شود، MCP serverها بهصورت مشترک config شوند، و conventions تیم در system prompt ایجنت بازتاب یابد. در غیر این صورت هر developer خروجی متفاوتی می‌گیرد و code review عملاً بی‌معنا میشود.
الگوی عملی:
- CLAUDE.md در ریشه‌ی repo commit شود و در code review بررسی شود.
- فایل
.claude/در Git track شود (نه در .gitignore). - MCP server config مشترک در repo باشد.
- هر developer خروجی ایجنت را مثل PR عادی review کند.
الگوی branch-per-task با Claude Code#
هر task ایجنتی روی یک branch جدا اجرا میشود. ایجنت در همان branch کد می‌نویسد، تست اجرا میکند، و commit می‌زند. سپس developer branch را review و merge میکند. این الگو از collision جلوگیری میکند و history تمیز نگه می‌دارد.
مستندسازی تصمیمات ایجنت برای onboarding اعضای جدید#
وقتی ایجنت یک refactor انجام میدهد، rationale را در commit message یا PR description بنویسید. اعضای جدید تیم می‌توانند بفهمند چرا این تغییرات انجام شده، بدون اینکه مجبور باشند session ایجنت را replay کنند. این کار در پروژه‌هایی که چند developer هم‌زمان با ایجنت کار می‌کنند، ضروری است نه اختیاری.
جمع‌بندی عملی#
Claude Code یک ابزار قدرتمند است، اما قدرت‌اش مشروط به سه چیز است: CLAUDE.md درست، task تقسیم‌شده، و MCP server مناسب. بدون این سه، ایجنت مثل یک developer بدون documentation عمل میکند — سریع ولی بی‌کیفیت.
اگر می‌خواهید عمیق‌تر با Claude و ابزارهای ایجنتی کار کنید، کامیونیتی پرداختی Claude در اسکول و دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» را بررسی کنید. در آنجا workflowهای واقعی با Claude Code، تنظیم CLAUDE.md و ساخت MCP server را بهصورت عملی تمرین میکنید.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته میشوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.