‏CLAUDE.md حافظهٔ کاریه، نه انبار

به گفتهٔ نویسنده، الگوی رایج توی پروژه‌های Claude Code یه فایل CLAUDE.md بزرگه که مدام بلندتر می‌شه و حوالی خط دویست، دستیار به‌جای بهتر شدن بدتر جواب می‌ده. دلیلش شانس بد نیست: این فایل اول سشن لود می‌شه و تا آخر توی context می‌مونه، پس هر خط اضافه چیزیه که کلاد قبل از رسیدن به تسک واقعی از روش رد می‌شه و بابتش توکن می‌ده. راه‌حل، فایل بلندتر نیست؛ اینه که CLAUDE.md رو مثل RAM ببینی و بقیهٔ مستندات رو مثل دیسک.

معیاری که نویسنده استفاده می‌کنه یه سؤال ساده‌ست: کلاد به این چیز همیشه نیاز داره یا گاهی؟ همیشه یعنی جاش توی CLAUDE.md هست؛ گاهی یعنی می‌ره توی پوشهٔ docs/ و فقط یه خط اشاره ازش توی فایل اصلی می‌مونه. خود CLAUDE.md باید اون‌قدر کوتاه باشه که زیر یک دقیقه بخونیش: دو سه جمله توضیح پروژه، استک با نسخه‌های پین‌شده (نه «لاراول»، بلکه «Laravel 11, PHP 8.3, Pest 3»)، دستورهای دقیق تست و لینت و سرور، قواعدی که روی هر تغییر باید برقرار باشن، و آدرس بقیهٔ چیزها.

سمت دیسک، سه فایل جواب بیشتر پروژه‌ها رو می‌ده: DESIGN.md برای معماری و مدل دامنه، PLAN.md برای برنامهٔ فازبندی‌شده با لاگ کارهای انجام‌شده، و DECISIONS.md به‌عنوان یه دفترچهٔ سبک تصمیم‌ها که هر ورودی‌ش زمینه، تصمیم و trade-off رو ثبت می‌کنه. نویسنده تأکید می‌کنه فایل چهارم رو فقط وقتی اضافه کن که نیاز واقعی پیدا شده؛ داربست خالی فقط چیز بیشتری برای خوندنه.

نکتهٔ آخری که نویسنده می‌گه اغلب از قلم می‌افته اینه که کلاد فقط CLAUDE.md ریشه رو نمی‌خونه، بلکه فایل هم‌نامِ داخل پوشه‌ای که توش کار می‌کنه رو هم روش سوار می‌کنه؛ پس قواعدی که فقط به یه پوشه ربط دارن، جاشون همون‌جاست نه توی فایل اصلی. خودش توی یه پروژهٔ لاراولی، قواعد لایهٔ دامنه رو همون‌جا گذاشته. البته توی به‌روزرسانی پست اضافه کرده که امروز نسخهٔ تمیزتر این ترفند، فایل‌های .claude/rules/*.md با کلید paths: هست که همون بارگذاری بر اساس نیاز رو می‌ده، ولی با الگو به‌جای پوشه و در یک جای قابل مرور.

نکات کلیدی:

• CLAUDE.md اول هر سشن لود می‌شه و تا آخر توی context می‌مونه، پس هزینه‌اش دائمیه
• معیار تقسیم: چیزی که همیشه لازمه توی فایل اصلی، چیزی که گاهی لازمه توی docs/
• استک با نسخهٔ پین‌شده و دستورهای دقیق بنویس تا کلاد حدس نزنه
• سه فایل DESIGN.md، PLAN.md و DECISIONS.md نیاز بیشتر پروژه‌ها رو پوشش می‌دن
• قواعد مخصوص یه پوشه رو همون‌جا نگه دار؛ امروز .claude/rules/*.md با paths: نسخهٔ بهتر همین کاره