تصور کن یک کارمند جدید استخدام کردهای. روز اول کلی وقت میگذاری و توضیح میدهی که این پروژه چیست، به چه چیزهایی نباید دست بزند، از کدام ابزارها استفاده کنی، چطور به دیتابیس وصل شود و قواعد commit زدن چیست. حالا فرض کن این کارمند هر صبح که سر کار میآید، حافظهاش پاک شده و باید همهی اینها را از اول توضیح بدهی. بدتر از آن، گاهی هم حدس میزند و بدون پرسیدن کاری انجام میدهد که نباید.
این دقیقاً همان اتفاقی است که وقت کار با Claude Code بدون فایل CLAUDE.md برایت میافتد. هر session جدید مثل روز اول کاری است: Claude نه استک پروژه را میداند، نه قراردادهای تیمت را، نه حتی این که برای تست از کدام دستور استفاده کنی. در ادامه میبینیم این فایل دقیقاً چیست، چرا حافظهی Claude Code به آن وابسته است، کجا باید قرار بگیرد، چه چیزی باید داخلش بنویسی و چه چیزهایی نه.
فایل CLAUDE.md دقیقاً چیست؟
CLAUDE.md یک فایل markdown ساده است که داخل پوشهی پروژهات قرار میگیرد و Claude Code در ابتدای هر session بهصورت خودکار آن را میخواند و در context بارگذاری میکند. چیزی که داخل این فایل مینویسی، در عمل تبدیل به دستورهای دائمی پروژه میشود؛ همان چیزهایی که در غیر این صورت باید هر بار در ابتدای گفتگو دوباره برای Claude تکرار کنی.
چند نکتهی مهم دربارهی ماهیت این فایل که باید از همان ابتدا بدانی:
- نام فایل دقیقاً CLAUDE.md است — تمام حروف بزرگ. اگر اسمش را Claude.md یا claude.md بگذاری، شناسایی نمیشود.
- یک پیشنهاد است، نه قانون اجرایی. مستندات رسمی صراحتاً میگوید Claude این فایل را بهعنوان context میبیند، نه پیکربندی اجباری. هرچه دستورهایت دقیقتر و کوتاهتر باشد، احتمال پیروی از آنها بالاتر میرود.
- کوتاه بهتر از بلند است. یک تحلیل از HumanLayer نشان میدهد مدلهای frontier تنها میتوانند حدود ۱۵۰ تا ۲۰۰ دستور را با ثبات پیگیری کنند، و سیستمپرامپت خود Claude Code حدود ۵۰ تا از این ظرفیت را اشغال میکند. پس اگر CLAUDE.md را با هر چیزی که به ذهنت میرسد پر کنی، در عمل بخشی از دستورهایت نادیده گرفته میشود.
یک مقالهی کاربردی پیشنهاد میکند فایل را زیر ۲۰۰ خط نگهداری؛ این یک سقف عملی خوب است.
سلسلهمراتب فایلهای CLAUDE.md کجا باید قرار بگیرد؟
مهمترین سوءتفاهم دربارهی این فایل این است که فکر کنی فقط یک فایل CLAUDE.md داری. در واقع Claude Code چند سطح scope را همزمان پشتیبانی میکند و همهی این فایلها بدون اینکه جای هم را بگیرند، به context اضافه میشوند:
ترتیب اولویت هم مشخص است: محلی روی پروژه، پروژه روی سراسری، و در صورت تعارض، هرچه دامنهی محدودتری دارد برنده میشود. این یعنی میتوانی برای کل تیم یک .claude/CLAUDE.md مشترک در git داشته باشی و در عین حال هر توسعهدهنده CLAUDE.local.md مخصوص خودش را داشته باشد بدون اینکه روی بقیه اثر بگذارد
چه چیزی داخل فایل CLAUDE.md بنویسیم؟
یک قاعدهی عملی خوب از HumanLayer این است که محتوای فایل را حول سه پرسش بچینی:
• WHAT : چی هست؟ استک، نسخهی زبان و فریمورک، ساختار پوشهها، فایلهای مهم. به Claude نقشهی کدبیس را بده.
• WHY : چرا هست؟ هدف پروژه، نقش بخشهای مختلف، تصمیمهای معماری که با نگاه به کد قابل حدس زدن نیستند.
• HOW : چطور کار میکنیم؟ دستورهای build، test، lint، قراردادهای نامگذاری، نکات gotcha که توسعهدهندهی تازهوارد را زمین میزنند.
یک نمونهی واقعی از یک پروژهی Next.js که میتوانی از آن الگو بگیری:
# Project: ShopFront
Next.js 14 e-commerce app with App Router, Stripe payments, Prisma ORM.
## Code Style
– TypeScript strict mode, no `any` types
– Use named exports, not default exports
– CSS: Tailwind utility classes only
## Commands
– `pnpm dev` — Start dev server (port 3000)
– `pnpm test` — Run Jest tests
– `pnpm db:migrate` — Run Prisma migrations
## Architecture
– /app: Next.js App Router pages
– /lib: Utilities and shared logic
– /prisma: Database schema
## Important Notes
– NEVER commit .env files
– Stripe webhook handler must validate signatures
– Product images live in Cloudinary, not locally
به این بعد توجه کن: هیچ خطی هدر نرفته. هر سطر یک تصمیم مشخص است که اگر Claude نمیدانست، بد عمل میکرد.
چه چیزی نباید در CLAUDE.md باشد؟
- توضیحات بدیهی. مثلاً «TypeScript یک زبان است که توسط مایکروسافت ساخته شده» را نمینویسیم. Claude اینها را از قبل میداند.
- هرچیزی که Claude بدون گفتنت هم درست انجام میدهد. یک منبع پیشنهاد میکند: «اگر بدون این دستور هم درست عمل میکند، حذفش کن یا تبدیلش کن به hook».
- قوانین مبهم. «کد تمیز بنویس» تأثیری ندارد. «از indent دو فاصلهای استفاده کن» قابل پیگیری است.
- اسرار و کلیدها. چون این فایل اغلب در git کامیت میشود، هرگز توکن، رمز، یا کلید API داخلش نگذار.
نکتهی مهم: علاوه بر CLAUDE.md فیچر جدید Auto Memory هم وجود دارد!
از نسخهی v2.1.59 به بعد، Claude Code یک سیستم دوم به نام Auto Memory اضافه کرده که خودش بدون اینکه چیزی بنویسی یاد میگیرد و یادداشت برمیدارد. این سیستم در فایلی به نام MEMORY.md ذخیره میشود که در مسیر ~/.claude/projects/<project>/memory/ قرار میگیرد.
تفاوت کلیدی این دو حافظه را متوجه بشی، خیلی به دردت میخورد:
CLAUDE.md vs MEMORY.md
CLAUDE.md دستوراتی است که تو به Claude میدهی. دستی مینویسی، در گیت کامیت میشود، با تیم به اشتراک میگذاری.
MEMORY.md یادداشتهایی است که Claude برای خودش مینویسد. مثلاً «این پروژه از pnpm استفاده میکند، نه npm»، یا «این CORS error را با تغییر Next.js config حل کردیم». شخصی است، در ماشین خودت میماند، با تیم به اشتراک گذاشته نمیشود.
هر دو در ابتدای session بارگذاری میشوند، اما هرکدام نقش متفاوتی دارند. قواعد سفت و سخت پروژه در CLAUDE.md، یادگیریهای تجربی درAuto Memory . همچنین MEMORY.md هم بهصورت پیشفرض روشن است؛ اگر بخواهی خاموشش کنی، در یک session دستور /memory را اجرا کن و گزینهی auto memory را تغییر بده.
جریان کاری عملی: چطور CLAUDE.md را بسازیم و نگهداریم
۱. شروع با /init
لازم نیست از صفر بنویسی. در پوشهی پروژهات Claude Code را اجرا کن و دستور /init را بزن. این دستور پروژه را اسکن میکند و یک CLAUDE.md اولیه با استک، دستورهای رایج، و ساختار پوشه میسازد. بعد آن را باز کن، چیزهای اضافی را حذف کن و نکات خاص پروژهات را اضافه کن.
۲. اضافه کردن سریع با علامت #
یک قابلیت کاربردی که خیلیها از آن غافلاند: وقت چت با Claude Code، اگر خط را با کاراکتر # شروع کنی، بقیهی متن مستقیم به مناسبترین فایل حافظه اضافه میشود. مثلاً اگر Claude یکجا اشتباه کرد و تو اصلاحش کردی، کافی است بنویسی:
|
# همیشه از pnpm استفاده کن، نه npm |
و بعد Claude از تو میپرسد میخواهی این به CLAUDE.md پروژه اضافه شود یا حافظهی شخصیات. دفعهی بعد دیگر تکرار نمیکند.
۳. ویرایش مستقیم با /memory
هر وقت خواستی یک نگاه کلی بکنی یا چیزی را پاک کنی، در یک session دستور /memory را بزن. لیست همهی فایلهای حافظهای که Claude دارد میبیند نشان داده میشود — این بهترین راه برای فهمیدن این است که آیا واقعاً همان CLAUDE.md که فکر میکنی بارگذاری شده یا نه.
۴. بازنگری دورهای
CLAUDE.md را بهعنوان یک سند زنده ببین. وقتی پروژه تغییر میکند، فایل را بهروز کن. وقتی Claude مدام یک اشتباه را تکرار میکند، یک خط دربارهی آن بنویس. وقتی فایل از حدود ۲۰۰ خط بیشتر شد، وقت بازچینی است؛ یا چیزهای کمتر مهم را به یک CLAUDE.md در زیرپوشهای منتقل کن، یا هرس کن.
بر اساس تجربهی توسعهدهندههایی که در ماههای اخیر مفصل با Claude Code کار کردهاند، چند اشتباه پرتکرار وجود دارد:
- md متورم. هرچه فایل بزرگتر شود، Claude نسبت کمتری از قواعد را پیگیری میکند. اگر دستوری در عمل کار نمیکند، حذفش کن.
- کامیت کردن CLAUDE.local.md در گیت. این فایل برای تنظیمات شخصی توست؛ آن را در .gitignore بگذار.
- اعتماد بدون راستیآزمایی. md را نوشتی، یعنی Claude لزوماً به آن عمل میکند؟ نه. هر تغییر مهم را با اجرای تست یا بررسی فایل تأیید کن.
- کپی کردن یک تمپلیت بزرگ از اینترنت. بهتر است کوچک شروع کنی و خط به خط اضافه کنی وقتی نیاز واقعی دیدی، نه اینکه تا یک تمپلیت ۳۰۰ خطی که نه میفهمی چیست و نه به دردت میخورد را دانلود و لود کنی!
چرا این فایل ارزش وقت گذاشتن دارد؟
هر دفعه که session جدیدی باز میکنی و Claude نمیداند پروژهات از Tailwind استفاده میکند یا نام محصولت Workspace است نه Project، باید توضیح بدهی. بدون فایل CLAUDE.md، در طول هفته احتمالاً دهها بار همان توضیحها را تکرار میکنی، توکن میسوزانی، و گاهی هم Claude بدون پرسیدن فرض اشتباهی میکند که باید بعداً اصلاحش کنی.
یک CLAUDE.md خوب در عمل دو چیز را میسازد: ثبات رفتار Claude در طول جلسات مختلف، و سرعت ورود اعضای جدید تیم به پروژه. چون این فایل را میتوانی به git کامیت کنی، هرکس که clone میکند بهطور خودکار همان حافظهی Claude Code را میگیرد که بقیهی تیم دارند.
جمعبندی
فایل CLAUDE.md پیچیده نیست، اما تأثیر زیادی دارد. کافی است یک فایل markdown در پوشهی پروژهات بگذاری و در آن بنویسی استک چیست، چه دستورهایی برای build و تست استفاده میکنی، چه کارهایی نباید انجام شود، و کجا گودالهایی پنهان هستند. این کار حافظهی Claude Code را از یک session یکبارمصرف به یک همکار باسابقه تبدیل میکند.
اگر تا حالا CLAUDE.md نداشتهای، توصیهام این است: امروز /init را اجرا کن، فایل تولیدشده را ساده نگهدار، و در طول هفته با علامت # نکاتی که برخورد میکنی را اضافه کن. تأثیرش روی کیفیت کار Claude Code را خیلی زود میبینی.
سؤالهای پرتکرار (FAQ) در مورد فایل CLAUDE.md
1- آیا فایل CLAUDE.md را باید در گیت کامیت کنیم؟
بله، .claude/CLAUDE.md یا CLAUDE.md در ریشهی پروژه را در گیت کامیت کن تا کل تیم همان context را داشته باشند. اما CLAUDE.local.md را در .gitignore بگذار، چون مخصوص تنظیمات شخصی هر توسعهدهنده است.
2- اگر دو فایل CLAUDE.md دستور متناقض داشته باشند چه میشود؟
ترتیب اولویت بر اساس scope است: محلی روی پروژه، پروژه روی سراسری. در صورت تعارض، فایلی که دامنهی محدودتری دارد برنده میشود. اما در عمل بهتر است از تعارض جلوگیری کنی، چون اگر دستورها مبهم یا متناقض باشند، Claude ممکن است هیچکدام را بهدرستی اعمال نکند.
3- CLAUDE.md و MEMORY.md چه فرقی دارند؟
CLAUDE.md را تو دستی مینویسی و دستوراتت به Claude است. MEMORY.md را خود Claude مینویسد و یادداشتهایی است که در طول جلسات یاد گرفته. CLAUDE.md معمولاً در گیت با تیم به اشتراک گذاشته میشود، MEMORY.md شخصی و محلی روی ماشین خودت است.
