CLAUDE.md فایلی است که در ابتدای هر جلسه خوانده میشود و قاعدههای ثابت پروژهات را به Claude میدهد: دستور ساخت و تست، سبک کدنویسی، ساختار و عادتهای کاری. مهمترین نکته این است که کوتاه و مشخص باشد؛ فایل بلند و مبهم، بیشتر نادیده گرفته میشود.
بر پایهٔ مستندات رسمی Claude Code که در ۲۶ آبان ۱۴۰۵ خواندیم. اگر تازه شروع کردهای، اول اولین جلسهٔ کاری را بخوان.
کجا قرار میگیرد؟
مستندات چند جا را نام میبرد:
- پروژه:
./CLAUDE.mdیا./.claude/CLAUDE.md، برای قاعدههای مشترک تیم. - کاربر:
~/.claude/CLAUDE.md، برای ترجیحهای شخصی در همهٔ پروژهها. - محلی:
./CLAUDE.local.md، برای تنظیمات شخصی همین پروژه. مستندات توصیه میکند آن را به.gitignoreاضافه کنی. - فایلهای پوشهٔ کاری و پوشههای بالاتر هنگام شروع خوانده و کنار هم گذاشته میشوند؛ فایلهای زیرپوشهها وقتی Claude در آن پوشه کار میکند بارگذاری میشوند.
چقدر بلند باشد؟
راهنما هدف را کمتر از ۲۰۰ خط برای هر فایل میگذارد. دلیلش ساده است: این فایل بخشی از زمینهٔ هر جلسه است و هر خطش جای کار اصلی را میگیرد.
چه چیزی بنویسیم؟
مستندات اینها را نام میبرد: دستور ساخت و تست، استانداردهای کدنویسی، تصمیمهای معماری، قاعدهٔ نامگذاری و روالهای رایج. و یک اصل: قاعدهٔ مشخص بنویس.
| ضعیف | قوی |
|---|---|
| «کد را مرتب بنویس» | «از دو فاصله برای تورفتگی استفاده کن» |
| «تست بنویس» | «برای هر تابع جدید یک تست در tests/ بنویس و با npm test اجرا کن» |
نکتهٔ مهم: این فایل «زمینه» است، نه «قانون»
مستندات صریح میگوید CLAUDE.md بهعنوان پیام کاربر به Claude داده میشود و تنظیم اجباری نیست. یعنی Claude ممکن است گاهی از آن پیروی نکند. قاعدهای که هیچ استثنایی ندارد، مثل «هرگز فایل .env را نخوان»، جای درستش مجوزها و قلابها (hooks) است، نه این فایل. نوشتهٔ مجوزها این را شرح میدهد.
کارهایی که کمک میکنند
/init: از روی کد، یک CLAUDE.md اولیه میسازد. اگر فایل داشته باشی، بهجای بازنویسی، پیشنهاد بهبود میدهد.@مسیر/فایل: یک فایل دیگر را وارد میکند. مسیرهای نسبی از فایل واردکننده حساب میشوند و عمق import چهار مرحله است. دستورهای تکراری را همینطور میشود از جای دیگر آورد./memory: فایلهای حافظه را فهرست میکند و باز میکند./context: برای اینکه مطمئن شوی کدام فایلها واقعاً بارگذاری شدهاند.- روالهای چندمرحلهای یا قاعدههای مخصوص بخشی از کد را مستندات به skills یا قاعدههای مخصوص مسیر در
.claude/rules/میسپارد.
یک نمونهٔ کوتاه
# دستورهای پروژه
- ساخت: npm run build
- تست: npm test (قبل از هر commit اجرا شود)
- لینت: npm run lint
# قاعدهها
- از TypeScript و دو فاصله تورفتگی استفاده کن.
- فایلهای جدید در src/features/ بسازند، نه src/utils/.
- پیام commit به انگلیسی و در یک خط.
اشتباههای رایج
- نوشتن توضیح معماری بلند. ما توصیه میکنیم هر چیزی که با خواندن کد هم معلوم میشود، در این فایل نیاید.
- تأکید با حروف بزرگ و «IMPORTANT». مستندات میگوید چنین تأکیدی احتمالاً مشکل را حل نمیکند؛ یا خط در فایل بلند گم میشود یا باید قلاب باشد.
- فایلهای متناقض در سطحهای مختلف.
/doctor prompt-auditایرادهایی مثل دستور کهنه یا اشارهٔ فایل ناموجود را نشان میدهد.
ادامه
اگر ابزارهای دیگر هم استفاده میکنی، AGENTS.md در Codex، قواعد Cursor و دستورهای Copilot همین نقش را دارند؛ مقایسهشان در مقایسهٔ ابزارهای کدنویسی آمده است.
سوالات متداول
راهنمای اصلی این بخش
کار مؤثر با ابزارهای هوش مصنوعی: پنج اصل مشترکتحریریهٔ سرنخ
تیم نویسندگان و آزمایشگران
ما چند نفریم که هر روز با ابزارهای هوش مصنوعی و اتوماسیون کار میکنیم. هر راهنمایی که اینجا میبینید اول روی کارِ خودمان امتحان شده و بعد نوشته شده است.