Claude Code بدون یک قرارداد صریح، هر جلسه معماری متفاوتی پیشنهاد می‌دهد و توسعه‌دهنده را در چرخه‌ی بی‌پایان اصلاح قرار می‌دهد. الگوی عملی‌ای که این مشکل را حل میکند، حاکمیت سه‌لایه (Governance) است: فایل CLAUDE.md برای ثبات معماری، Plan Mode برای جلوگیری از ویرایش‌های مخرب، و زمینه‌ی محدود (Scoped Context) برای کنترل هزینه‌ی توکن. این مقاله هر سه لایه را با مثال واقعی از شکست‌ها و موفقیت‌های پروژههای عملیاتی توضیح می‌دهد.
Claude Code چیست و چرا بدون قرارداد شکست می‌خورد؟#
Claude Code یک ابزار ترمینالی مبتنی بر عامل هوش مصنوعی (Agentic AI) است. بدون فایل CLAUDE.md و دستورالعمل صریح، هر جلسه معماری متفاوتی پیشنهاد می‌دهد، خروجی‌های ناسازگار تولید میکند و توسعه‌دهنده را در چرخه‌ی بی‌پایان اصلاح فرو می‌برد. ریشه‌ی این شکست، نبودِ قرارداد پروژه‌ای است.
تفاوت ماهوی Claude Code با ابزارهای autocomplete درون IDE در یک کلمه خلاصه میشود: تصمیم‌گیری. ابزارهای پیشنهاددهنده یک خط کد پیشنهاد می‌کنند و شما انتخاب می‌کنید. Claude Code خودش فایل می‌خواند، تصمیم می‌گیرد کدام بخش را ویرایش کند، و تغییر را اعمال میکند. این یعنی قدرت بیشتر، ولی ریسک بالاتر.
الگوی شکست رایج در پروژههای واقعی: بدون CLAUDE.md، Claude در جلسه‌ی اول معماری MVC پیشنهاد می‌دهد، در جلسه‌ی دوم الگوی Repository را وارد میکند، و در جلسه‌ی سوم هر دو را ترکیب میکند. نتیجه، کدی است که هیچ‌کس نمی‌تواند نگه‌دارد.
مفهوم حاکمیت سه‌لایه از همین شکست‌ها متولد شده:
- قرارداد فایل (CLAUDE.md): ثبات معماری و قوانین کدنویسی بین جلسات
- حالت برنامه‌ریزی (Plan Mode): بازبینی قبل از اجرا، جلوگیری از تغییرات مخرب (Breaking Changes)
- زمینه‌ی محدود (Scoped Context): محدود کردن ورودی به فایلهای مرتبط، کاهش هزینه و افزایش دقت
هر سه لایه مکمل یکدیگرند. CLAUDE.md بدون Plan Mode، Claude را مجاز به ویرایش‌های ساختاری می‌گذارد. Plan Mode بدون زمینه‌ی محدود، توکن‌های بی‌ربط مصرف میکند. زمینه‌ی محدود بدون CLAUDE.md، Claude بدون چارچوب تصمیم می‌گیرد.
نصب و راه‌اندازی در ترمینال#
Claude Code با Node.js و Git نصب میشود، یک API Key یا اشتراک Claude Pro/Max می‌خواهد و در پوشه‌ی کاری (Working Directory) پروژه فعال می‌گردد. مراحل نصب ساده است، اما تنظیم اولیه‌ی پوشه — به‌ویژه ساختار فایل CLAUDE.md — تعیین‌کننده‌ی کیفیت خروجی‌هاست و نادیده‌گرفتنش، هزینه‌ی اصلاح را در جلسات بعدی چند برابر میکند.
پیش‌نیازها: Node.js نسخه‌ی LTS، Git، و دسترسی ترمینال. برای احراز هویت، یا API Key از حساب Anthropic یا اشتراک Claude Pro/Max لازم است.
گام‌های راه‌اندازی:
- نصب با npm:
npm install -g @anthropic-ai/claude-code - احراز هویت: اجرای
claudeدر ترمینال و ورود با حساب Anthropic - انتقال به پوشه‌ی پروژه:
cd /path/to/project - ایجاد فایل CLAUDE.md خالی در ریشه‌ی پروژه
- اجرای اولین جلسه با
claudeو مشاهده‌ی رفتار اولیه
ساختار اولیه‌ی پوشه و فایل CLAUDE.md#
فایل CLAUDE.md در ریشه‌ی پروژه قرار می‌گیرد. حتی اگر خالی باشد، Claude Code آن را به‌عنوان زمینه‌ی دائمی بارگذاری میکند. اما فایل خالی فایده‌ای ندارد — ارزش آن در محتوای ساختارمند است که در بخش بعد توضیح می‌دهم.
نکته‌ی عملی: اگر پروژه‌ی شما تک‌مخزنی (Monorepo) است، می‌توانید CLAUDE.md را در هر sub-package جداگانه بگذارید. Claude Code فایلهای CLAUDE.md را از پوشه‌ی فعلی به سمت بالا جست‌وجو میکند و همه را بارگذاری میکند.
CLAUDE.md: قرارداد پروژه‌ای که خروجی را تضمین میکند#
فایل CLAUDE.md باید چهار بخش داشته باشد — معماری، قوانین کدنویسی، فهرست وابستگی‌ها و دستورالعمل تست — تا Claude Code در هر جلسه خروجی سازگار تولید کند. بدون این ساختار، فایل به یک README تبدیل میشود که هیچ تضمینی برای سازگاری نمی‌دهد و عملاً بی‌اثر است.
ساختار استاندارد چهاربخشی#
الگویی که در پروژههای اعضای کامیونیتی اسکول مکرراً دیده شده، این چهار بخش است:
- بخش معماری: توصیف لایه‌ها (مثلاً Controller → Service → Repository → Database)، الگوی طراحی، مرزهای ماژول
- بخش قوانین کدنویسی: style guide، الگوی نام‌گذاری، الگوهای مجاز و ممنوع
- بخش وابستگی‌ها: کتابخانه‌های مجاز با نسخه، کتابخانه‌های ممنوع با دلیل
- بخش دستورالعمل تست: framework، الگوی نام‌گذاری تست‌ها، پوشش حداقلی
مثال واقعی از بخش معماری:
Architecture: Clean Architecture با چهار لایه. Controller فقط validation و delegation انجام می‌دهد. Business logic در Service Layer است. Repository Pattern برای دسترسی به دیتابیس. هیچ import مستقیم از Database به Controller مجاز نیست.
این یک خط توصیفی نیست — یک قرارداد اجرایی است. Claude Code این متن را در هر جلسه به‌عنوان system instruction بارگذاری میکند و بر اساس آن تصمیم می‌گیرد.
تکنیک دستورالعمل‌های محدوده‌مند (Scoped Instructions)#
عبارت «فقط فایلهای src/api/ را لمس کن» در ابتدای هر وظیفه، Claude را مجبور میکند خارج از آن محدوده ویرایش نکند. این تکنیک به‌ویژه در پروژههای بزرگ حیاتی است چون بدون آن، Claude ممکن است یک helper مشترک را تغییر دهد و ده‌ها فایل دیگر را بشکند.
الگوی عملی: در ابتدای هر درخواست، محدوده را صریح بنویسید. «فقط این سه فایل را تغییر بده» بهجای «کد را اصلاح کن». این یک تفاوت ساده است اما هزینه‌ی چرخه‌ی اصلاح را به‌طرز محسوسی کاهش می‌دهد.
چطور با Plan Mode از ویرایش‌های مخرب جلوگیری کنیم؟#
حالت برنامه‌ریزی (Plan Mode) در Claude Code با کلید Shift+Tab فعال میشود و قبل از اجرای هر تغییر، فقط پلان متنی تولید میکند. کاربر پلان را تأیید یا اصلاح میکند و سپس اجرا انجام میشود. این ساده‌ترین و مؤثرترین مکانیزم جلوگیری از تغییرات مخرب است.
تفاوت Plan Mode با حالت عادی: در حالت عادی، Claude فوراً فایل‌ها را ویرایش میکند. در Plan Mode، Claude ابتدا پلان متنی تولید میکند — چه فایل‌هایی را تغییر می‌دهد، چه توابعی اضافه می‌شوند، چه وابستگی‌هایی لازم است. شما این پلان را بازبینی می‌کنید و اگر تأیید کردید، اجرا میشود.
الگوی چندمرحله‌ای: Plan → Review → Execute → Verify#
الگویی که در پروژههای production مکرراً استفاده شده:
- Plan: Shift+Tab فعال کنید، task را توصیف کنید، پلان دریافت کنید
- Review: پلان را بخوانید. آیا فایلهای درستی انتخاب شده؟ آیا معماری رعایت شده؟
- Execute: اگر پلان درست است، Shift+Tab را بزنید و اجازه‌ی اجرا بدهید
- Verify: تست‌ها را اجرا کنید، diff را بررسی کنید
مثال عملی: فیچر احراز هویت از صفر. در Plan Mode، Claude پلان می‌دهد که یک فایل Controller، یک Service، یک Repository و سه فایل تست ایجاد کند. شما در مرحله‌ی Review متوجه می‌شوید که Service باید از الگوی Factory استفاده کند نه Constructor ساده. پلان را اصلاح می‌کنید و سپس اجرا میشود.
چرا این الگو از تغییرات مخرب جلوگیری میکند؟ چون تصمیم‌های معماری قبل از نوشتن کد گرفته می‌شوند. اگر بعد از اجرا متوجه اشتباه شوید، rollback هزینه‌ی بیشتری دارد.
مقایسه با Vibe Coding#
Vibe Coding (پروتوتایپ سریع بدون بازبینی) برای ایده‌های اولیه مناسب است. برای پروژه‌ی production، Plan Mode ضروری است. الگوی ترکیبی: در فاز کشف و ایده‌پردازی، vibe coding مجاز است. در فاز اجرا و production، Plan Mode اجباری.
مدیریت Context Window و هزینه‌ی پنهان توکن#
پنجره‌ی زمینه (Context Window) 200 هزار توکنی Claude به‌معنای استفادهی بهینه نیست؛ ورود اطلاعات بی‌ربط کیفیت خروجی را کاهش می‌دهد و سقف مصرف اشتراک را زودتر پر میکند. مدیریت هوشمندانه‌ی زمینه، مهمترین مهارت عملی در استفادهی روزمره از Claude Code است و نادیده‌گرفتنش، هزینه‌ی پنهانی است که در قبض ماهانه ظاهر میشود.
مفهوم Context Window: Claude Code قبل از هر پاسخ، فایلهای مرتبط را می‌خواند و در زمینه قرار می‌دهد. هر توکن در زمینه، هزینه دارد و کیفیت را هم تحت تأثیر قرار می‌دهد. ورود 500 فایل بی‌ربط، Claude را گیج میکند و احتمال توهم (Hallucination) را بالا می‌برد.
الگوی Exclude#
فایل‌ها و پوشه‌هایی که هرگز نباید در زمینه بیایند:
- node_modules
- dist و build
- فایلهای باینری و تصاویر
- فایلهای lock (package-lock.json، yarn.lock)
- فایلهای لاگ و cache
تکنیک زمینه‌ی محدود: در هر جلسه، فقط فایلهای مرتبط با task را مشخص کنید. «فقط فایلهای src/api/auth/ را بخوان» بهجای «کل پروژه را بررسی کن». این تکنیک هم کیفیت خروجی را بالا می‌برد هم هزینه‌ی توکن را کاهش می‌دهد.
مدل هزینه و سقف مصرف#
اشتراک Claude Pro شامل Claude Code است، اما مصرف سنگین API در پروژههای بزرگ به سقف می‌رسد. الگوی شکست سریع (Fail-Fast) برای تک‌مخزنی‌ها: اگر task شما بیش از چند صد فایل را در زمینه می‌خواهد، احتمالاً باید آن را به sub-taskهای کوچک‌تر تقسیم کنید. شکست سریع بهجای مصرف بی‌رویه.
نکته‌ی عملی که در محتوای فارسی‌زبان تقریباً غایب است: قبل از شروع هر جلسه، تخمین بزنید چند فایل در زمینه می‌آید. اگر بیش از 10 فایل مرتبط است، task را بشکنید. هر sub-task باید حداکثر 3 تا 5 فایل مرتبط داشته باشد.
MCP و زیرایجنت‌ها: گسترش قدرت Claude Code#
Model Context Protocol (MCP) یک استاندارد باز برای اتصال Claude Code به ابزارهای خارجی است و زیرایجنت‌ها (Sub-agent) امکان تقسیم وظایف بین عامل‌های تخصصی را فراهم می‌دهند. این دو مفهوم، Claude Code را از یک ابزار ویرایش کد به یک پلتفرم ارکستراسیون (Orchestration) تبدیل می‌کنند.
MCP به‌عنوان پروتکل ارتباطی: یک MCP Server، یک ابزار خارجی را به Claude Code متصل میکند. Claude Code می‌داند چه ابزارهایی در دسترس دارد و بر اساس task، تصمیم می‌گیرد کدام را صدا بزند.
MCP Serverهای کاربردی#
الگوهایی که در پروژههای واقعی دیده شده:
- دیتابیس: اتصال به PostgreSQL یا MongoDB برای query مستقیم
- GitHub API: خواندن issue، نوشتن PR، ویرایش branch
- ابزارهای CI/CD: اجرای pipeline، خواندن لاگ build
- فایل سیستم: دسترسی به پوشه‌های خارج از پروژه
ساخت MCP Server سفارشی در چند خط کد ممکن است. برای جزئیات فنی و نمونه‌های عملی به مستندات Anthropic مراجعه کنید.
زیرایجنت‌ها و الگوی Orchestration#
Sub-agent یک عامل تخصصی با وظیفه‌ی مشخص است: یک زیرایجنت فقط تست می‌نویسد، دیگری فقط refactoring انجام می‌دهد، سومی مستندسازی میکند. الگوی Orchestration: خروجی چند زیرایجنت در یک جلسه ترکیب میشود.
مثال عملی: task «اضافه کردن فیلد جدید به مدل کاربر». زیرایجنت اول مدل و migration را تغییر می‌دهد. زیرایجنت دوم تست‌ها را آپدیت میکند. زیرایجنت سوم مستندات API را به‌روز میکند. هر سه در یک جلسه و با زمینه‌ی جداگانه اجرا می‌شوند.
Claude Code بهتر است یا Cursor؟#
Claude Code برای کارهای چندفایلی، اتوماسیون ترمینالی و ارکستراسیون مناسب است؛ Cursor برای ویرایش تعاملی با بافت بصری و autocomplete درون IDE بهتر عمل میکند. انتخاب بین ابزار و محیط است، نه رقابت بین دو محصول. هرکدام در جای خود بی‌رقیب‌اند.
| معیار | Claude Code | Cursor | GitHub Copilot |
|---|---|---|---|
| نوع تعامل | ترمینالی، متنی | IDE با بافت بصری | Plugin درون IDE |
| توانایی چندفایلی | قوی — خودش فایل‌ها را می‌خواند و تغییر می‌دهد | متوسط — بیشتر single-file focus | ضعیف — خط‌به‌خط |
| بازبینی بصری | ندارد — باید diff را در ترمینال بخوانید | دارد — inline diff | دارد — ghost text |
| مناسب برای | refactor، migration، taskهای پیچیده | iterative development، UI | autocomplete، کارهای کوچک |
| مدل هزینه | اشتراک یا API | اشتراک | اشتراک |
الگوی ترکیبی که در پروژههای واقعی دیده شده: Claude Code برای refactor و taskهای ساختاری، Cursor برای iteration سریع و کارهای UI. این دو جایگزین یکدیگر نیستند — مکمل‌اند.
چه زمانی Claude Code انتخاب اشتباه است؟#
در پروژههای تک‌مخزنی با صدها فایل، پروژههای بدون Git branch، و کارهایی که نیاز به بازبینی لحظه‌به‌لحظه‌ی بصری دارند، Claude Code انتخاب اشتباه است. شناخت محدودیت‌ها به‌اندازه‌ی شناخت توانایی‌ها اهمیت دارد، و نادیده‌گرفتن این محدودیت‌ها هزینه‌ی بازگشت را سنگین‌تر از آن میکند که به‌نظر می‌رسد.
محدودیت تک‌مخزنی: در monorepo با صدها فایل، context window پر میشود و Claude فایلهای بی‌ربط را هم می‌خواند. نتیجه: کد ناسازگار. الگوی شکست سریع (تقسیم task به sub-taskهای کوچک) این مشکل را کاهش می‌دهد اما حذف نمی‌کند.
ریسک بدون Git: Claude Code فایل‌ها را مستقیم ویرایش میکند. بدون Git branch، امکان rollback وجود ندارد. یک اشتباه در Plan Mode تأییدنشده می‌تواند چندین فایل را خراب کند و بدون version control، بازیابی دشوار است.
پروژههای UI سنگین: Claude Code preview بصری ندارد. اگر task شما نیاز به دیدن نتیجه‌ی بصری دارد (CSS، layout، انیمیشن)، Cursor یا IDE سنتی + Copilot انتخاب بهتری است.
جایگزین‌ها در این موارد: Cursor برای ویرایش تعاملی، Windsurf برای پروژههای متوسط، IDE سنتی + Copilot برای کارهای خطی.
جریان کاری کامل: یک نمونه‌ی عملی#
جریان کاری کامل Claude Code در یک وظیفه‌ی واقعی پنج مرحله دارد: تعریف محدوده‌ی تغییر (Scope)، نوشتن فایل CLAUDE.md، فعالسازی Plan Mode، اجرای مرحله‌ای با تأیید کاربر، و راستی‌آزمایی نهایی. هر مرحله ابزار و تصمیم خاصی می‌طلبد و حذف حتی یکی، قابلیت‌اعتمادی خروجی را تضعیف میکند.
سناریو: اضافه کردن endpoint جدید به یک API با Node.js و TypeScript.
مرحله ۱ — Scope: «فقط فایلهای src/routes/، src/controllers/ و src/services/ را تغییر بده. هیچ فایل دیگری لمس نشود.»
مرحله ۲ — CLAUDE.md: فایل شامل معماری (Controller → Service → Repository)، قوانین نام‌گذاری (camelCase، PascalCase برای کلاس‌ها)، و وابستگی‌های مجاز (express، zod) است.
مرحله ۳ — Plan Mode: Shift+Tab فعال. درخواست: «endpoint GET /users/:id اضافه کن». پلان تولید میشود: یک فایل controller جدید، یک متد در service موجود، یک route در فایل routes.
مرحله ۴ — Review و Execute: پلان تأیید میشود. Shift+Tab دوباره. اجرا.
مرحله ۵ — Verify: تست‌ها اجرا می‌شوند. diff بررسی میشود. اگر چیزی خارج از scope تغییر کرده، rollback.
این پنج مرحله، زمان بیشتری نسبت به حالت بدون ساختار می‌طلبد. اما هزینه‌ی چرخه‌ی اصلاح (که بدون ساختار ممکن است ده‌ها دقیقه یا ساعت باشد) را حذف میکند.
نتیجه‌ی عملی: Claude Code بدون حاکمیت سه‌لایه، ابزاری ناپایدار است که بیشتر وقت شما را در چرخه‌ی اصلاح می‌گیرد تا صرف ساختن. CLAUDE.md، Plan Mode و زمینه‌ی محدود سه لایه‌ای‌اند که این ناپایداری را به قابلیت‌اعتمادی تبدیل می‌کنند. اگر تازه شروع کرده‌اید، ابتدا CLAUDE.md را بنویسید — حتی اگر ناقص باشد، بهتر از نبودنش است.
اگر می‌خواهید این الگوها را در پروژه‌ی واقعی پیاده کنید و از شکست‌های دیگران یاد بگیرید، کامیونیتی پرداختی Claude در اسکول با دوره‌ی «آموزش جامع Claude و ابزارهای مشابه» دقیقاً همین مسیر را پوشش می‌دهد.
دیدگاهها
برای گذاشتن دیدگاه وارد شو
دیدگاهها فقط از حسابهای کاربری پذیرفته می‌شوند.
ورود / ثبتنامهنوز دیدگاهی ثبت نشده — اولین نفر باش.