CLAUDE.md: کاری کنید که AI پروژه شما را واقعاً درک کند
یک فایل برای ذخیره دائمی مشخصات پروژه، تصمیم‌های معماری و قراردادهای تیمی — Claude آن را در شروع هر نشست میخواند
به‌روزرسانی شده 2026-11-14
CLAUDE.md چیست؟
CLAUDE.md فایلی ویژه در ریشه پروژه شماست که Claude Code هنگام راه‌اندازی به‌طور خودکار میخواند. این فایل یک «خلاصه معرفی پروژه» برای AI است — شامل مجموعه فناوری‌ها، قواعد کدنویسی، ساختار دایرکتوری و دستورهای کلیدی، تا Claude زمینه شما را بدون توضیحات تکراری درک کند. بر اساس اطلاعات تا 2026-10-07: اگر یک مخزن AGENTS.md داشته باشد اما CLAUDE.md نداشته باشد، Claude Code 2.1.277 و نسخه‌های بعدی بهجای آن AGENTS.md را می‌خوانند.
مستندات رسمی آن را جایی معرفی می‌کنند که در آن چیزهایی را می‌نویسید که در غیر این صورت مدام دوباره توضیح می‌دادید: فقط واقعیت‌هایی که هر جلسه به آن‌ها نیاز دارد باید درون آن باشند و جزئیات یک کار موردی در مکالمه می‌ماند (بررسیشده در 2026-09-21).
یک فایل متنی ساده
این یک فایل markdown ساده در مخزن است: شما آن را می‌نویسید، commit می‌کنید، مانند هر چیز دیگری می‌خوانید و diff می‌گیرید. بر اساس مستندات، شما آن را می‌نویسید و Claude Code در آغاز هر جلسه آن را میخواند (بررسیشده در 2026-09-21).
در زمان راه‌اندازی بارگذاری میشود
CLAUDE.md در پوشه کاری و هر سطح بالاتر از آن در زمان راه‌اندازی بارگذاری میشود؛ فایل‌های زیرپوشه‌ها زمانی بارگذاری می‌شوند که Claude فایل‌های آنجا را میخواند (بررسیشده در 2026-09-21).
زمینه، نه پیکربندی
این فایل در هر جلسه در پنجره زمینه بارگذاری میشود و همراه با مکالمه شما توکن مصرف میکند، بدون هیچ تضمینی برای پیروی سخت‌گیرانه — مستندات آن را زمینه می‌نامند، نه پیکربندی الزامی (بررسیشده در 2026-09-21).
چرا CLAUDE.md؟
دستاورد آن سه‌گانه است: دیگر در شروع هر جلسه تایپ اطلاعات زمینه‌ای لازم نیست، خروجی برای هر کسی که می‌پرسد یکسان است، و شروع به کار به سنت شفاهی وابسته نیست.
حذف تکرار
دیگر لازم نیست هر نشست توضیح دهید که «ما از TypeScript استفاده می‌کنیم» یا «تست‌ها با Jest اجرا می‌شوند» — یک بار بنویسید، همیشه مؤثر.
خروجی یکدست
سبک کدنویسی، قراردادهای نام‌گذاری و محدودیت‌های معماری را تعریف کنید تا خروجی Claude همیشه با استانداردهای پروژه مطابقت داشته باشد.
اشتراک دانش تیمی
وقتی اعضای جدید به تیم می‌پیوندند، CLAUDE.md هم نقش پیکربندی AI را دارد و هم راهنمای ورود به پروژه قابل‌خواندن برای انسان است.
قالب پیشنهادی
یک CLAUDE.md خوب معمولاً شامل این بخش‌هاست
# نمای کلی پروژه
- بک‌اند مرکز سفارش، REST API برای وب و مینی‌برنامه
- اعضای جدید ابتدا این فایل را می‌خوانند، سپس راهنمای شروع به کار را
- پیش از تغییر API، بررسی کنید که آیا کلاینت‌ها به همگام‌سازی نیاز دارند
## پشته فناوری
- زبان TypeScript روی Node.js، pnpm برای بسته‌ها
- PostgreSQL برای داده‌ها، خواندن‌های پرتکرار از Redis ارائه می‌شوند
- Vitest برای تست‌ها، پوشش تست در CI کنترل میشود
## چیدمان پوشه‌ها
- src/api: ورودی HTTP و بررسی آرگومان‌ها، بدون قواعد کسب‌وکار
- src/domain: قواعد کسب‌وکار، بدون import فریم‌ورک
- tests: آینه درخت src، برای یافتن سریع خطاها
## قواعد کد
- تورفتگی دو فاصله، کوتیشن تک، نقطه‌ویرگول حفظ شود
- نام‌ها کامل نوشته شوند، بدون اختصار
- بدون انواع فریم‌ورک در لایه دامنه؛ این یک نقص است
## فرمان‌های متداول
- npm run dev: اجرای محلی
- npm test: کل مجموعه تست واحد، پیش از توقف باید موفق شود
- npm run lint: یک‌بار پیش از commit
## نکته‌های مهم
- هیچ اطلاعات محرمانه یا URLهای داخلی را اینجا قرار ندهید؛ از متغیرهای محیطی استفاده کنید
- مهاجرت‌های پایگاه داده را نخست روی پایگاه داده سایه اجرا کنید
- حالت مرزی نامشخص: بپرسید، پیش‌فرضی از خود نسازیدنکات پیشرفته
این پنج نکته تعیین می‌کنند که فایل رعایت شود یا به نویزی تبدیل شود که هیچ‌کس دوباره نمی‌خواند؛ هر یک آزمونی ارائه می‌دهد که می‌توانید آن را روی فایل خودتان اجرا کنید.
فقط واقعیت‌های تکرارشونده
معیار ساده است: آیا این خط در جلسه بعدی هنوز مفید است؟ دستورهای build، قواعد نام‌گذاری و دام‌های گذشته در آن می‌گنجند؛ فهرست‌های پوشه و فهرست‌های وابستگی نه — Claude آن‌ها را از کد استخراج میکند (بررسیشده در 2026-09-21).
زیر 200 خط بمانید
خط مرجع در مستندات کمتر از 200 خط برای هر فایل است؛ فراتر از آن، زمینه بیشتری مصرف میکند و کمتر رعایت میشود (بررسیشده در 2026-09-21). اگر نمی‌گنجد، آن را به قواعد محدود به مسیر تقسیم کنید که فقط زمانی بارگذاری می‌شوند که Claude با فایل‌های منطبق کار میکند.
آن را قابل راستی‌آزمایی کنید
«کد را خوب قالب‌بندی کنید» هیچ اطلاعاتی ندارد؛ «تورفتگی دو فاصله‌ای، گیومه‌های تک، و اجرای npm test پیش از commit» قابل پیروی است. خطوط را زیر زیرعنوان‌ها و بولت‌ها گروه‌بندی کنید — Claude ساختار را همان‌طور که یک خواننده اسکن میکند، اسکن میکند (بررسیشده در 2026-09-21).
تولید کنید، سپس پیرایش کنید
از صفحه خالی شروع نکنید: /init پایگاه کد را تحلیل میکند و دستورهای build، تنظیمات تست و قراردادهایی را که می‌یابد پیش‌نویس میکند؛ سپس مواد اضافی را همان‌طور که /doctor انجام می‌دهد حذف کنید و دام‌ها و دلایل را نگه دارید؛ در پایان با /context تأیید کنید که فایل بارگذاری شده است (بررسیشده در 2026-09-21).
بدون اطلاعات محرمانه در داخل
این فایل در Git قرار میگیرد و در هر جلسه توسط همه خوانده میشود. اطلاعات محرمانه، URLهای داخلی و حساب‌های کاربری تست را در متغیرهای محیطی نگه دارید؛ ترجیحات شخصی را در CLAUDE.local.md بگذارید و آن را در gitignore قرار دهید تا نسخه تیمی تمیز بماند (بررسیشده در 2026-09-21).
استانداردهای همکاری تیمی
بهترین شیوه‌ها برای نگهداری CLAUDE.md در پروژه‌های چندنفره
آن را مثل کد بازبینی کنید
نسخه پروژه دارایی تیم است، نه یادداشت شخصی: آن را در همان PR کد تغییر دهید، دلیلش را توضیح دهید و بگذارید مالک آن پوشه بازبینی‌اش کند. مستندات: دستورهای پروژه از طریق کنترل نسخه به اشتراک گذاشته می‌شوند (بررسیشده در 2026-09-21).
ترتیب و تناقض‌ها
فایل‌های بالاتر ابتدا وارد زمینه می‌شوند و فایل‌های زیرپوشه به‌هنگام نیاز بارگذاری می‌شوند — محتوا به هم پیوند می‌خورد و هیچ‌چیز چیز دیگری را باطل نمی‌کند. اگر دو فایل یک رفتار را متفاوت بیان کنند، Claude ممکن است تصادفی یکی را برگزیند؛ پس عبارت را یکدست کنید یا یکی را حذف کنید (بررسیشده در 2026-09-21).
تفکیک بر اساس ماژول
در مخزن بزرگ، فایل ریشه را پر نکنید: یادداشت‌های مخصوص هر ماژول به CLAUDE.md یک زیرپوشه یا قاعده‌ای محدود به مسیر می‌روند که فقط وقتی Claude آنجا کار میکند وارد زمینه میشود — ارزان‌تر و دقیق‌تر از یک فایل ریشه غول‌آسا (بررسیشده در 2026-09-21).
بررسی را خودکار کنید
دو کار را عادی کنید: بررسی CI که وجود CLAUDE.md ریشه و ماندنش در اندازه توافق‌شده را کنترل کند، و اینکه هر PR معماری مدخلهای موجود را دوباره بخواند. مستندات نیز حذف دورهای دستورهای کهنه و متناقض را میخواهد (بررسیشده در 2026-09-21).
اشتباه‌های رایج
هر چهار مورد فایل را از اهرم به نویز تبدیل می‌کنند و رفع هیچ‌کدام نیازمند بازنویسی نیست.
یادداشت کار، نه قاعده
چسباندن مراحل بازتولید یک باگ یا یادداشت‌های موقت یک بازآرایی یعنی آن‌ها در نشست بعدی هم زمینه را اشغال می‌کنند، بی‌آنکه قاعده کلی نوشته شده باشد. جای آن‌ها در یک issue یا توضیحات PR است (بررسیشده در 2026-09-21).
فقط بزرگ‌تر میشود
مستندات مرز را 200 خط می‌گذارد: بیش از آن، فایل زمینه بیشتری مصرف میکند و کمتر اطاعت میشود (بررسیشده در 2026-09-21). درمان تورم با افزودن یک قاعده دیگر جواب نمی‌دهد — آنچه فقط در برخی پوشه‌ها اهمیت دارد را از آن بیرون ببرید.
قاعده‌ها با هم تناقض دارند
ریشه pnpm میگوید، یک زیرپوشه npm — Claude ممکن است از هر کدام که برگزیده پیروی کند (بررسیشده در 2026-09-21). برای هر موضوع یک گزاره مرجع نگه دارید و از جای دیگر به آن ارجاع دهید، نه اینکه نسخه دومی کپی کنید.
هیچ‌کس نگه‌داری‌اش نمی‌کند
پشته تغییر کرده، چیدمان بازآرایی شده، اما فرمان‌های داخل فایل هنوز قدیمی‌اند. مستندات بازبینی دورهای هر سطح و حذف مدخلهای منسوخ و متناقض را میخواهد (بررسیشده در 2026-09-21) — که ساده‌ترین راه آغازش، PR معماری است.
پرسش‌های متداول
آیا باید در هر نشست CLAUDE.md را ارائه دهید؟
خیر. CLAUDE.md در دایرکتوری کاری شما یا هر دایرکتوری بالاتر از آن، در شروع نشست به‌طور خودکار بارگذاری میشود؛ فایل‌های زیردایرکتوری‌ها وقتی Claude کد را در آنجا میخواند اضافه می‌شوند. دستور /context را اجرا کنید و فهرست فایل‌های حافظه را بررسی کنید تا ببینید واقعاً چه چیزی بارگذاری شده است (بررسیشده در 2026-09-21).
چه اندازه‌ای بیش از حد بزرگ است؟
مرجع مستندشده زیر 200 خط در هر فایل است؛ بیش از آن، هزینه زمینه بالا می‌رود و پایبندی کاهش می‌یابد (بررسیشده در 2026-09-21). محتوای هر ماژول را به فایل‌های قاعده محدود به مسیر منتقل کنید تا فقط زمانی بارگذاری شود که Claude به فایل‌های منطبق دست می‌زند.
وضعیت AGENTS.md چگونه است؟
حالت پیشفرض یکی یا دیگری است: هر CLAUDE.md در پوشه کاری شما یا بالاتر از آن، مانع بارگذاری AGENTS.md میشود. برای داشتن هر دو، در پنل /config گزینه Project instructions را روی بارگذاری هر دو تنظیم کنید، یا فایل را از CLAUDE.md با @AGENTS.md وارد کنید (بررسیشده در 2026-09-21). افزودهشده در 2026-10-07: این رفتار در Claude Code 2.1.277 (منتشرشده در 2026-09-18) آمد که تغییرات آن میگوید «پشتیبانی AGENTS.md افزوده شد: در پروژهای که CLAUDE.md ندارد، Claude Code بهجای آن AGENTS.md را میخواند»؛ از 2.1.281 (2026-09-23) در نشستهای دروازه LLM نیز کار میکند.
چه کسی آن را نگهداری میکند؟
همان گردشکار کد: نسخه پروژه در کنترل نسخه نگهداری میشود و همراه با تغییری که آن را ایجاب کرده بازبینی میشود؛ هر کس به معماری دست بزند آن را بهروز میکند. ترجیحات شخصی در فایلی محلی و جداگانه قرار میگیرد که در gitignore ثبت شده است، و مستندات پاکسازی دورهای مدخلهای کهنه را میخواهد (بررسیشده در 2026-09-21).
شیوه‌های تیمی با QCode.cc
یک کلید API QCode.cc + CLAUDE.md یکپارچه = کدنویسی با هوش مصنوعی یکدست و کارآمد برای کل تیم شما
یک کلید برای کل تیم
تیم از یک کلید QCode.cc به‌طور مشترک استفاده میکند و مصرف زیر یک حساب کاربری واحد ثبت میشود، بهجای یک کلید برای هر نفر (بررسیشده در 2026-09-21).
مدل را عوض کنید، فایل را نگه دارید
CLAUDE.md را کلاینت درون پروژه میخواند و به این بستگی ندارد که کدام مدل پاسخ می‌دهد، پس تغییر مدل نیازی به بازنویسی ندارد.
یک نقطه شروع
همه از یک نقطه شروع می‌کنند: تازه‌وارد و مهندس ارشد با همان پیش‌فرض‌های پروژه در زمینه درخواست می‌دهند، پس خروجی دیگر به این بستگی ندارد که چه کسی آن را تایپ کرده است.
سه شکل پروژه
یک قالب واحد نباید فایل یکسانی تولید کند. این سه شکل مخزن به بیان صریح موارد متفاوتی نیاز دارند؛ هر چیز باقی‌مانده را حذف کنید.
بک‌اند تیمی
دستورهای ساخت و مهاجرت، قواعد سخت سازگاری API و اینکه کدام دایرکتوری‌ها ممنوع هستند را صریح بنویسید؛ اینجا بخش پرهزینه همان چیزی است که همه تکرار می‌کنند.
کتابخانه متن‌باز
جریان مشارکت، الزامات تست و اینکه چه چیزی تغییر شکننده محسوب میشود: مشارکت‌کنندگان بیرونی و نگه‌دارندگان از یک متن واحد کار می‌کنند، بنابراین هر خط باید قابل راستی‌آزمایی باشد.
ابزارهای انفرادی
از فهرست کامل بخش‌ها بگذرید. نحوه اجرای آن، سیاست نسخه وابستگی‌ها و محدودیت‌های سخت مانند «کل فایل را دوباره قالب‌بندی نکنید» را نگه دارید — نه چیزی بیشتر.
CLAUDE.md بهتر بنویسید، هوشمندانه‌تر کدنویسی کنید.
حافظه پروژه + پلن QCode.cc = بهترین شیوه‌های کدنویسی تیمی با هوش مصنوعی