فایل CLAUDE.md چیست؟ راهنمای حافظه‌ی Claude Code برای توسعه‌دهنده‌ها

تصور کن یک کارمند جدید استخدام کرده‌ای. روز اول کلی وقت می‌گذاری و توضیح می‌دهی که این پروژه چیست، به چه چیزهایی نباید دست بزند، از کدام ابزارها استفاده کنی، چطور به دیتابیس وصل شود و قواعد 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 شخصی و محلی روی ماشین خودت است.