معماری agent-based یک تغییر پارادایم در نحوه‌ی تعامل با کد است: ابزار خودش تصمیم میگیرد کجا بنگرد، نه شما. استراتژی پرامپتینگ از «این محتوا را بخوان» به «اینجاها را بگرد» جابه‌جا میشود و مدیریت context از انباشتن به انتخاب هوشمند تبدیل می‌گردد. بدون درک این تفاوت، آموزش Claude Code به حفظ دستورات CLI تقلیل می‌یابد.
Claude Code یک agent است، نه یک IDE wrapper#
Claude Code به‌عنوان یک ایجنت (Agent) با دسترسی مستقیم به filesystem و shell طراحی شده؛ برخلاف ابزارهایی مثل Cursor که wrapper روی IDE هستند، Claude Code خودش تصمیم میگیرد کدام فایل‌ها را بخواند و کدام دستورات را اجرا کند. این تفاوت معماری، تمام استراتژی تعامل شما را تغییر میدهد.
در معماری agent-based، مدل در یک loop قرار دارد: reasoning → tool use → observation → reasoning مجدد. هر دور، مدل یک فراخوانی ابزار انجام میدهد، نتیجه را می‌بیند، و بر اساس آن تصمیم بعدی را میگیرد. شما پرامپت اول را می‌دهید، اما بقیه‌ی مسیر را مدل خودش می‌سازد.
معماری داخلی: loop بین reasoning، tool use و execution#
سه مرحله‌ی اصلی در هر تعامل وجود دارد:
- Reasoning: مدل task را تحلیل میکند و تصمیم میگیرد چه ابزاری لازم دارد.
- Tool use: مدل یک فراخوانی ابزار مشخص اجرا میکند — خواندن فایل، جستجوی filesystem، یا اجرای command در shell.
- Observation: خروجی ابزار به مدل برگردانده میشود و مدل بر اساس آن تصمیم بعدی را میگیرد.
این loop تا زمانی ادامه دارد که مدل به نتیجه‌ی نهایی برسد یا به limit برسد. نکته‌ی کلیدی: شما فقط در مرحله‌ی اول تأثیر دارید. بعد از آن، مدل خودش فایل‌ها را کشف میکند.
چرا این تفاوت معماری، تعریف «پرامپت خوب» را عوض میکند#
پرامپت خوب در Claude Code یعنی دادن مسیر و راهنمای کشف، نه چسباندن محتوا. در ابزارهای IDE wrapper، شما فایلهای relevant را انتخاب می‌کنید و به context اضافه می‌کنید. در Claude Code، مدل خودش filesystem را می‌گردد.
الگوی selective context loading: به‌جای نوشتن «این فایل را بخوان: src/auth/login.ts»، بنویسید «در پوشه‌ی src/auth دنبال الگوی authentication بگرد و فایلهای مرتبط را بررسی کن». مدل خودش فایل‌ها را کشف میکند.
یک اشتباه پرهزینه که در پروژه‌های تیمی مکرر تکرار میشود: monorepoهای بزرگ بدون CLAUDE.md مناسب. مدل فایلهای نامرتبط را میخواند، در context window گم میشود و عملکرد به‌طور محسوس افت میکند. این الگو در چندین پروژه‌ی تیمی که از Claude Code استفاده می‌کنند، مشاهده شده است.
چطور Claude Code را نصب و پیکربندی کنم؟#
Claude Code از طریق npm قابل نصب است و پس از احراز هویت با Anthropic API key، بهصورت CLI در terminal پروژه اجرا میشود. پیش‌نیاز اصلی، Node.js نسخه‌ی 18 به بالا و یک حساب Anthropic با دسترسی API است.
پیش‌نیازها#
- Node.js نسخه‌ی 18 یا بالاتر
- حساب Anthropic فعال با دسترسی API
- Terminal با دسترسی به filesystem پروژه
مراحل نصب گام‌به‌گام#
- پیش‌نیازها را بررسی کنید:
node --version - Claude Code را نصب کنید:
npm install -g @anthropic-ai/claude-code - احراز هویت:
claude authو وارد کردن API key - به پوشه‌ی پروژه بروید:
cd /path/to/your/project - اولین session را شروع کنید:
claude - CLAUDE.md را در ریشهی پروژه بسازید (مفصل در بخش بعد)
Claude Code در ژوئن 2025 بهصورت research preview منتشر شد و سپس به general availability رسید. برای جزئیات دقیق‌تر، مستندات رسمی Anthropic را بررسی کنید.
پیکربندی اولیه شامل انتخاب مدل پیش‌فرض، تنظیم permission model (اینکه مدل بدون تأیید شما چه کارهایی می‌تواند بکند)، و ساخت CLAUDE.md است. اولین session را ساده شروع کنید — یک task کوچک که فقط خواندن فایل‌ها را شامل شود.
مدیریت context window: الگوی selective loading در برابر context stuffing#
مدیریت context window در Claude Code بر پایه‌ی سه عنصر استوار است: CLAUDE.md، ساختار پوشهبندی، و ارجاع selective به فایل‌ها. context stuffing — پر کردن context با همه‌چیز — رایج‌ترین الگوی شکست است و مدل را در انتخاب فایلهای relevant ضعیف میکند.
CLAUDE.md چیست و چطور بنویسم؟#
CLAUDE.md یک فایل راهنما در ریشهی پروژه است که به مدل توضیح میدهد این پروژه چه ساختاری دارد و کجا بنگرد. سه بخش اصلی داشته باشد:
- Architecture: معماری کلی پروژه — کدام پوشه چه نقشی دارد.
- Conventions: قراردادهای کدنویسی — naming، patternها، import style.
- Entry points: نقاط ورود اصلی — کجا execution شروع میشود.
مختصر بنویسید. یک CLAUDE.md دهخطی با توضیح architecture و conventions، تأثیر بیشتری از ده خط prompt اضافه دارد. این الگو در پروژه‌های تیمی که از Claude Code استفاده می‌کنند، بارها تأیید شده است.
الگوی شکست: context stuffing#
وقتی فایلهای زیادی را به context اضافه می‌کنید، signal-to-noise ratio افت میکند و مدل در جزئیات بی‌ربط گم میشود. الگوی بهینه: CLAUDE.md + directory tree + selective file references.
Compaction چیست و چه زمانی فعال میشود؟#
Compaction مکانیزمی است که وقتی context window نزدیک به پر شدن میشود، مدل خلاصه‌ای از گفتگوهای قبلی را نگه می‌دارد و جزئیات را حذف میکند. این فرآیند خودکار است، اما شما می‌توانید با شروع session جدید یا استفاده از /compact command، آن را دستی فعال کنید.
Context window مدل‌های Claude از نسل Sonnet به بعد، 200K token است (منبع: مستندات Anthropic). این عدد در پروژه‌های بزرگ ممکن است کم باشد — بنابراین selective loading نه یک بهینه‌سازی، بلکه ضرورت است.
پرامپت‌نویسی برای Claude چه تفاوتی با ChatGPT دارد؟#
Claude روی ساختار XML tags و system prompt آموزش دیده و در zero-shot reasoning قوی‌تر است. توصیه‌های generic مثل «نقش بده» و «few-shot بده» برای Claude همیشه بهینه نیستند و در برخی tasks می‌توانند عملکرد را کاهش دهند.
چرا XML tags مخصوص Claude است؟#
مدل‌های Claude در مرحله‌ی RLHF (Reinforcement Learning from Human Feedback) روی ساختار XML tags آموزش دیده‌اند. استفاده از تگ‌هایی مثل <thinking>، <instructions> و <context> به مدل کمک میکند بخش‌های مختلف پرامپت را از هم تفکیک کند. این یک توصیه‌ی سلیقه‌ای نیست — مدل واقعاً روی این ساختار آموزش دیده است.
Extended thinking mode: چه زمانی فعال و چه زمانی غیرفعال؟#
Claude 3.7 Sonnet extended thinking mode را بهصورت hybrid معرفی کرد: مدل قبل از پاسخ، reasoning داخلی انجام میدهد. برای کارهای ساده، latency را بدون بهبود کیفیت افزایش میدهد.
الگوی thinking budget که در پروژه‌های واقعی تکرار شده:
- فعال: architecture decisions، debugging پیچیده، refactoring چندفایلی
- غیرفعال: boilerplate code، formatting، کارهای تکراری ساده
نکته‌ی مهم: اکثر محتوای آموزشی که قبل از این قابلیت نوشته شده، هیچ اشاره‌ای به thinking mode ندارد. اگر راهنمایی می‌بینید که extended thinking را mention نمی‌کند، احتمالاً outdated است.
Model Context Protocol: پل ارتباطی Claude Code با زیرساخت سازمان#
MCP (Model Context Protocol) یک پروتکل استاندارد برای اتصال ابزارهای خارجی به مدل‌های Claude است. ارزش واقعی آن در enterprise context است — اتصال به internal APIها، database schemaها و deployment pipelineها — نه صرفاً به‌عنوان یک plugin system.
معماری MCP: client، server و protocol layer#
MCP سه لایه دارد:
- Client: سمت مدل — Claude Code یا هر ابزار دیگری که MCP را مصرف میکند.
- Server: سمت ابزار — یک process مستقل که capabilities مشخصی expose میکند.
- Protocol layer: استاندارد ارتباطی بین client و server.
MCP در نوامبر 2024 توسط Anthropic معرفی شد (منبع: modelcontextprotocol.io). تفاوت اصلی با fine-tuning: بدون نیاز به تغییر مدل، ابزارهای جدید اضافه میشوند. مدل خودش تصمیم میگیرد چه زمانی از چه toolای استفاده کند.
کاربرد سازمانی#
ارزش واقعی MCP در اتصال به زیرساخت داخلی است. مثلاً: یک MCP server که به database schema سازمان وصل میشود، به مدل اجازه میدهد بدون شما query بنویسد. یا یک MCP server که به CI/CD pipeline وصل است، به مدل اجازه میدهد deployment status را چک کند.
نکته‌ی عملی: اکثر آموزش‌ها MCP را به‌عنوان plugin system معرفی می‌کنند. این درست است اما ناقص. ارزش اصلی در enterprise integration است، نه در اضافه کردن pluginهای ساده.
هزینه‌ی استفاده از Claude Code چقدر است و چطور کاهشش دهیم؟#
هزینه بر پایه‌ی token محاسبه میشود. prompt caching در workflowهای Claude Code که system prompt یکسان بارها ارسال میشود، می‌تواند هزینه را به‌طور قابل‌توجهی کاهش دهد. این نکته در اکثر آموزش‌ها نادیده گرفته میشود.
چرا prompt caching مخصوص workflowهای agent-based ارزشمند است#
در یک agent loop، system prompt (شامل CLAUDE.md، tool definitions و context اولیه) در هر دور loop دوباره ارسال میشود. بدون caching، شما برای هر دور هزینه‌ی کامل input tokens را می‌پردازید. با prompt caching، بخش‌های تکراری ارزان‌تر محاسبه میشوند.
مدل‌های Haiku، Sonnet و Opus از نظر سرعت و هزینه متفاوت‌اند. Haiku سریعترین و ارزانترین، Sonnet متعادلترین، و Opus قدرتمندترین است. برای کدنویسی روزمره Sonnet انتخاب پیش‌فرض است؛ برای architecture decisions پیچیده Opus و برای کارهای ساده و تکراری Haiku مناسب‌تر است.
نکته: اعداد دقیق قیمت را از مستندات رسمی Anthropic بررسی کنید. قیمت‌ها وابسته به زمان هستند و ممکن است تغییر کنند. در این مقاله عدد قیمتی نمی‌دهم چون از صحت عددی مطمئن نیستم.
الگوهای debug و workflowهای agent-based#
Debug کردن با Claude Code یعنی درک agent loop: reasoning → tool use → observation → reasoning مجدد. وقتی خروجی اشتباه است، ابتدا ببینید مدل در کدام مرحله تصمیم غلط گرفته — نه اینکه prompt را عوض کنید و امیدوار باشید.
ساختار agent loop و نقاط شکست#
سه نقطه‌ی شکست اصلی در agent loop وجود دارد:
- Reasoning error: مدل task را اشتباه فهمیده. راهحل: CLAUDE.md را بهتر کنید یا prompt اول را دقیق‌تر بنویسید.
- Tool selection error: مدل فایل یا command اشتباهی را انتخاب کرده. راهحل: ساختار پوشهبندی را شفاف‌تر کنید.
- Observation misinterpretation: مدل خروجی tool را اشتباه تفسیر کرده. راهحل: context را محدود کنید به فایلهای مرتبط.
الگوی dry-run قبل از apply برای multi-file refactoring#
Claude Code می‌تواند چندین فایل را همزمان تغییر دهد، اما ریسک breaking change بالاتری دارد. الگوی بهینه: ابتدا dry-run (مدل فقط plan را نشان دهد بدون اجرا)، سپس apply. این الگو در پروژه‌های تیمی بارها جلوی production incident را گرفته است.
کاربردهای non-coding#
Claude Code فقط برای کدنویسی نیست. سه کاربرد non-coding که در محتوای فارسی تقریباً پوشش داده نشدهاند:
- Research document synthesis: مدل فایلهای PDF و markdown را میخواند و خلاصه‌ی تحلیلی مینویسد.
- Data analysis با Python execution: مدل script پایتون مینویسد، اجرا میکند، و نتیجه را تفسیر میکند.
- Test-driven development loop: مدل test مینویسد، اجرا میکند، fail را می‌بیند، code را اصلاح میکند — همه در یک loop.
Permission model و sandbox behavior: review کردن diffها ضروری است. مدل بدون تأیید شما فایل‌ها را تغییر میدهد. در پروژه‌های production، حتماً permission model را روی «confirm before write» تنظیم کنید.
Claude Code چه وقت ابزار مناسبی نیست؟#
Claude Code برای کارهای تک‌فایلی ساده، پروژه‌های بدون ساختار مشخص، و taskهایی که نیاز به determinism کامل دارند، ابزار بهینه نیست. overhead agent loop در این موارد، هزینه‌ی اضافی بدون فایده ایجاد میکند.
مقایسه‌ی معماری ابزارها#
| ابزار | دسترسی filesystem | multi-file edit | context management | مناسب برای |
|---|---|---|---|---|
| Claude Code | مستقیم (agent-driven) | بله، چند فایل همزمان | selective loading + CLAUDE.md | refactoring پیچیده، پروژه‌های چندفایلی |
| Cursor | غیرمستقیم (IDE wrapper) | محدود، معمولاً یک فایل | user-driven (شما فایل انتخاب می‌کنید) | کدنویسی روزمره، autocomplete |
| Aider | مستقیم (CLI) | بله | user-driven (git-aware) | توسعه‌دهندگان solo با git workflow |
| Windsurf | غیرمستقیم (IDE) | محدود | user-driven | تجربه‌ی مشابه VS Code با AI |
نکته‌ی کلیدی از این مقایسه: Cursor معمولاً یک فایل را edit میکند؛ Claude Code چند فایل همزمان. trade-off متفاوت است — Cursor برای کارهای کوچک predictableتر است، Claude Code برای refactoringهای بزرگ قوی‌تر.
پروژه‌های بدون ساختار#
monorepo بدون CLAUDE.md، بدترین سناریو برای Claude Code است. مدل نمی‌داند کجا بنگرد، فایلهای نامرتبط را میخواند، و در context window گم میشود. اگر پروژه‌تان ساختار مشخصی ندارد، اول آن را بسازید — بعد سراغ Claude Code بروید.
کارهای ساده‌ی تک‌فایلی#
برای نوشتن یک تابع ساده یا تغییر یک خط config، overhead agent loop بی‌فایده است. در این موارد، یک autocomplete ساده یا حتی نوشتن دستی سریع‌تر است. Claude Code را برای taskهایی نگه دارید که واقعاً multi-step هستند.
Taskهایی که determinism مطلق لازم دارند#
agent loop ذاتاً non-deterministic است. مدل هر بار ممکن است مسیر متفاوتی را انتخاب کند. برای taskهایی که خروجی یکسان و قابل‌تکرار لازم دارید — مثلاً migration script حساس — Claude Code ابزار بهینه نیست. از ابزارهای deterministic استفاده کنید.
نتیجه‌ی عملی#
سه تصمیم فوری که همین امروز می‌توانید بگیرید: اول، یک CLAUDE.md مختصر بنویسید — فقط architecture، conventions و entry points. دوم، extended thinking mode را برای کارهای ساده غیرفعال کنید و فقط برای debugging و architecture decisions فعال نگه دارید. سوم، الگوی selective loading را جایگزین context stuffing کنید — به مدل مسیر بدهید نه محتوا.
این سه تغییر، تفاوت بین استفاده‌ی سطحی و استفاده‌ی مؤثر از Claude Code را مشخص می‌کنند. معماری agent-based یعنی شما دیگر نویسنده‌ی پرامپت نیستید — معمار context هستید.
اگر می‌خواهید این الگوها را در عمل تمرین کنید و از تجربه‌ی تیم‌هایی که Claude Code را در پروژه‌های واقعی استفاده می‌کنند بهره ببرید، دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» در کامیونیتی Claude اسکول، 53 جلسه‌ی عملی دارد که دقیقاً همین workflowها را پوشش میدهد.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته میشوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.