CLAUDE.md ما 162 خط است. چه چیزی در آن است — و چه چیزی را حذف کردیم.

گران‌ترین فایل در مخزن شما که نمی‌دانستید

اگر از Claude Code استفاده می‌کنید، CLAUDE.md ریشه پروژه شما گران‌ترین فایل منفرد در مخزن شماست. نه به‌خاطر فضای دیسک — به این دلیل که هر بایت آن در شروع هر نشست بدون بارگذاری lazy وارد context می‌شود. مهارت‌ها به‌طور تدریجی بارگذاری می‌شوند. ابزارهای MCP می‌توانند موکول شوند. CLAUDE.md فقط آنجا می‌نشیند، همیشه بارگذاری شده، همیشه روی پنجره شما مالیات می‌گذارد.

مال ما 820 خط بود. ما آن را به 162 خط کاهش دادیم بدون از دست دادن یک guardrail منفرد. این پست دقیقاً آنچه خارج شد، آنچه ماند، و سه الگو که کار را انجام دادند است.

اعداد سرتیتر: 820 به 162 خط، حدود 8,000 به حدود 1,200 توکن، و حدود 12% به حدود 0.75% سهم از پنجره context 200K.

چرا CLAUDE.md سزاوار پست خود است

در نوشته بهینه‌سازی توکن گسترده‌تر ما، MCP Tool Search بزرگ‌ترین اهرم منفرد بود. CLAUDE.md دومین است. تحقیقات روی frameworkهای بزرگ Claude Code گزارش می‌دهد که پیکربندی‌های ریشه بهینه شده به کاهش 54 تا 62% در سربار baseline دست می‌یابند، و یک ضد الگوی مستند — یک CLAUDE.md با 2,800 خط — حدود 62% توکن‌ها به ازای هر نشست را هدر می‌دهد.

دلیل، مکانیزم است. محتوای CLAUDE.md در هر سطح از سلسله مراتب بدون قید و شرط بارگذاری می‌شود:

فایل‌های سیاست enterprise
CLAUDE.md ریشه پروژه
~/.claude/CLAUDE.md در سطح کاربر
override های محلی پروژه
هر فایل وارد شده از طریق نحو @path/to/file (بازگشتی تا 5 سطح عمیق)

هر چیز دیگری که Claude Code در اطراف context انجام می‌دهد — بارگذاری تدریجی مهارت، MCP Tool Search، ایزولاسیون subagent — برای دور زدن مالیات always-loaded طراحی شده است. CLAUDE.md تنها چیزی است که بدون قید و شرط برای آن می‌پردازید، در هر نوبت.

قبل ما: 820 خط، تقریباً 12% از context

CLAUDE.md اصلی ما مثل کتابچه راهنمای شرکت می‌خواند. هر مهارت که استفاده می‌کردیم، هر گام گیت عرضه، هر تفاوت پیکربندی WordPress Coding Standards ما، هر قرارداد نام‌گذاری برای componentهای React، هر قاعده scoping دارایی پیشخوان را مستند می‌کرد. واقعاً مرجع مفیدی بود. همچنین در هر نشست بارگذاری می‌شد، از جمله نشست‌هایی که هیچ ربطی به بیشتر آن نداشتند.

اینجا یک حسابداری تقریبی از آنچه در آن بود:

بخش	خطوط	توکن تقریبی	فرکانس بارگذاری توجیه شده؟
نقشه workspace و ساختار پروژه	90	900	بله — context برای هر نشست
معماری و tech stack	60	600	بله
قواعد حریم خصوصی (غیرقابل مذاکره)	40	400	بله — invariantهای بحرانی
توضیحات به ازای هر مهارت (30+ ورودی)	180	1,800	خیر — مهارت‌های منفرد on-demand بارگذاری می‌شوند
پروتکل‌های به ازای هر workflow (دقیق)	200	2,000	خیر — فقط در طول آن workflow نیاز است
استانداردهای آزمون با جزئیات	120	1,200	خیر — فقط برای نشست‌های آزمون‌نویسی مرتبط
راهنمای گیت عرضه	80	800	خیر — در مهارت release زندگی می‌کند
یادداشت‌های عیب‌یابی	50	500	خیر — به‌ندرت لازم

هر چیزی که با «خیر» علامت‌گذاری شده بود، در هر نشست برای در دسترس بودن برای کسری از آن‌ها مالیات می‌داد. این تقریباً 6,300 توکن هدر — حدود 3% از کل پنجره context، به‌طور دائمی.

بعد ما: 162 خط، تقریباً 0.75%

CLAUDE.md جدید همان سطح را با سه الگو پوشش می‌دهد: یک جدول راه‌انداز، فایل‌های CLAUDE.md تو در تو، و قواعد path-scoped.

الگوی 1: جدول راه‌انداز مهارت

به جای مستندسازی هر مهارت با یک پاراگراف، حدود 30 توضیح به ازای هر مهارت را با یک جدول جستجوی منفرد جایگزین کردیم:

## Skill triggers
| Trigger keywords | Skill | Domain |
|------------------|-------|--------|
| sprint, backlog, iteration | pm-sprint-plan | PM |
| story, acceptance criteria | pm-story-write | PM |
| deploy, release, ship | statnive-release | Dev |
| security, audit, CVE | sec-audit-remediate | Security |
| wireframe, mockup | ux-design | UX |
| benchmark, performance | wp-performance | WP |

تحقیق روی frameworkهای بزرگ گزارش می‌دهد این الگو حدود 800 توکن در مقابل 3,000+ برای متن مهارت‌به‌مهارت verbose هزینه دارد. مسیریابی Claude همچنان به‌درستی کار می‌کند زیرا کلمات کلیدی راه‌انداز چیزی است که در واقع با آن مطابقت می‌دهد — متن طولانی «وقتی استفاده شود / وقتی استفاده نشود» که قبلاً می‌نوشتیم هرگز به مسیریابی کمک نکرد، فقط context را پر کرد.

همه محتوای دقیق «وقتی استفاده شود / وقتی استفاده نشود» در فایل‌های منفرد SKILL.md زندگی می‌کند، فقط زمانی بارگذاری می‌شود که Claude به آن‌ها مسیریابی کند. جدول راه‌انداز شاخص است؛ مهارت‌ها فصل‌ها هستند.

الگوی 2: فایل‌های CLAUDE.md تو در تو برای قواعد دامنه

اینجا ویژگی بحرانی است که بیشتر توسعه‌دهندگان از دست می‌دهند: فایل‌های CLAUDE.md تو در تو در زیرپوشه‌ها به‌صورت lazy بارگذاری می‌شوند. آن‌ها فقط زمانی وارد context می‌شوند که Claude فایل‌هایی را در آن زیردرخت‌ها بخواند.

طرح مخزن ما اکنون به این شکل است:

statnive-workflow/
├── CLAUDE.md                    # 162 lines — global only
├── statnive/
│   ├── CLAUDE.md                # PHP / WordPress plugin conventions
│   ├── src/
│   └── tests/
├── statnive-website/
│   └── CLAUDE.md                # Astro / MDX / frontend conventions
└── jaan-to/
    └── CLAUDE.md                # AI framework conventions

وقتی PHP برای plugin می‌نویسیم، statnive/CLAUDE.md به‌طور خودکار بارگذاری می‌شود و یادداشت‌های WordPress Coding Standards، قاعده اعمال $wpdb->prepare() و قاعده scoping دارایی پیشخوان ما را می‌آورد. وقتی محتوای MDX blog می‌نویسیم، statnive-website/CLAUDE.md با قراردادهای Astro و یادداشت‌های سبک خانه بارگذاری می‌شود. هیچکدام با دیگری تداخل ندارد.

این الگو حدود 2,200 توکن از محتوای «گاهی فقط مرتبط» را از ریشه قطع کرد.

الگوی 3: قواعد path-scoped در `.claude/rules/`

مکانیزم سوم .claude/rules/ است — فایل‌های قواعد با frontmatter YAML که می‌توانند اعلام کنند به کدام مسیرها اعمال می‌شوند:

---
paths: ["statnive-website/src/**/*.tsx", "statnive-website/src/**/*.astro"]
---
Use Tailwind utilities scoped under `#statnive-app`. Never import the default
Tailwind bundle — it restyles the WordPress admin chrome.

قواعد با فیلد paths: به‌صورت مشروط بارگذاری می‌شوند — فقط زمانی که Claude با فایل‌های منطبق کار می‌کند. قواعد بدون فیلد paths: بدون قید و شرط بارگذاری می‌شوند، بنابراین آن‌ها را به یک تعداد محدود نگه می‌داریم (قواعد حریم خصوصی، قواعد امنیتی، قراردادهای commit).

ما حدود 1,800 توکن از قراردادهای خاص framework را از CLAUDE.md ریشه به قواعد path-scoped زیر .claude/rules/ منتقل کردیم. آن‌ها همچنان وقتی مرتبط هستند به‌طور قابل‌اعتماد شلیک می‌کنند، و وقتی نامرتبط هستند هیچ هزینه‌ای ندارند.

ضد الگویی که حذف کردیم: `@-Imports`

CLAUDE.md اصلی ما سه @-import داشت:

@jaan-to/docs/best-practices.md
@jaan-to/context/tech.md
@jaan-to/outputs/ROADMAP.md

مرتب به نظر می‌رسد. یک تله است. نحو @ به‌صورت بازگشتی محتوای کامل هر فایل هدف را در هر نشست تا پنج سطح عمیق بارگذاری می‌کند. سه import ما به‌تنهایی حدود 6,000 توکن سربار دائمی را برای محتوایی که مدل احتمالاً در یکی از هر بیست نشست به آن نیاز داشت اضافه می‌کرد.

ما هر کدام را با یک اشاره‌گر جایگزین کردیم:

For architectural context see `jaan-to/context/tech.md`.
For the current roadmap see `jaan-to/outputs/ROADMAP.md`.

Claude این مسیرها را زمانی که واقعاً به آن‌ها نیاز دارد می‌خواند — از طریق ابزار Read، on demand. صفر هزینه baseline، همان نتیجه عملی.

چه چیزی هنوز در فایل ریشه زندگی می‌کند

پس از کاهش‌ها، CLAUDE.md ریشه 162 خطی دقیقاً شامل این موارد است:

بخش	خطوط	چرا ماند
فلسفه محصول (8 اصل از تحقیق)	28	هر تصمیم را شکل می‌دهد؛ باید بر همه نشست‌ها تأثیر بگذارد
نقشه workspace	18	جهت‌گیری در یک نگاه، برای هر نشست بارگذاری می‌شود
قواعد حریم خصوصی (غیرقابل مذاکره)	16	invariantهای بحرانی — کوکی‌ها، IPهای خام، saltها، SHA-256
قاعده scoping دارایی پیشخوان	22	قبلاً ما را گزیده، به‌طور گسترده اعمال می‌شود
سیاست commit (trailer co-authored-by ممنوع است)	8	قرارداد git سراسری
قاعده workflow `/simplify`	18	اعمال گیت کیفیت ما
جدول راه‌انداز مهارت	32	جایگزین حدود 30 بخش به ازای هر مهارت verbose
مسیرهای کلیدی (اشاره‌گرها، نه importها)	20	ارجاعات یک خطی به docs

هر چیز دیگری به CLAUDE.md تو در تو، قواعد path-scoped، یا بدنه مهارت‌های منفرد منتقل شد.

آنچه بهینه نکردیم

ملاحظات صادقانه، همان الگوی بقیه سری:

~/.claude/CLAUDE.md در سطح کاربر خارج از کنترل ما است. هر یک از مهندسان ما پیکربندی سراسری خود را دارد، و آن‌ها روی فایل پروژه بارگذاری می‌شوند. تحقیق این را به‌عنوان یک منبع رایج سربار پنهان شناسایی می‌کند — یک CLAUDE.md سراسری که شامل «به یاد داشته باشید قبل از commit آزمون‌ها را اجرا کنید» روی یک workflow در سطح پروژه که دقیقاً همین کار را انجام می‌دهد، توکن هزینه دارد بدون افزودن سیگنال. ما از اعضای تیم خواستیم خودشان را ممیزی کنند. مال شما احتمالاً ارزش یک نگاه را دارد.
هنوز یک گیت CI روی اندازه CLAUDE.md ریشه نداریم. تحقیق پیشنهاد می‌کند PR را شکست دهید اگر CLAUDE.md ریشه + هر @-import از حدود 2,500 توکن فراتر برود. ما با بررسی نقطه‌ای /context اعمال می‌کنیم. یک گیت CI در roadmap است.
نشانگرهای IMPORTANT و YOU MUST وسوسه‌انگیز هستند. Anthropic داخلی فایل‌های CLAUDE.md را از طریق ابزار بهبود prompt اجرا می‌کند و از نشانگرهای تأکید برای قواعد بحرانی استفاده می‌کند. ما کم از آن‌ها استفاده می‌کنیم — هر یک سربار دائمی است، بنابراین آن‌ها را برای قواعد حریم خصوصی (بدون کوکی، بدون IP خام) و سیاست commit (بدون trailer co-authored-by) ذخیره می‌کنیم.

گام اندازه‌گیری که نمی‌توانید رد کنید

اگر CLAUDE.md خود را ممیزی می‌کنید، یک دستور که اهمیت دارد /context است. آن را در ابتدای یک نشست تازه، قبل از هر prompt، اجرا کنید. استفاده context شما را بر اساس منبع تجزیه می‌کند: system prompt، ابزارها، حافظه (که CLAUDE.md است)، metadata مهارت‌ها و schemaهای ابزار MCP.

اعدادی که در یک نشست با پنجره 200K هدف می‌گیریم:

منبع	هدف	سقف سخت
CLAUDE.md ریشه + قواعد unscoped	حداکثر 1,500 توکن	2,500
metadata مهارت	حداکثر 2,500 توکن	5,000
schemaهای ابزار MCP (با Tool Search)	حداکثر 3,000 توکن	8,000
stdout هوک (SessionStart، UserPromptSubmit)	0 توکن	300 به ازای هر هوک

اگر /context شما از هر یک از این‌ها بیش از حدود 50% فراتر می‌رود، مشکل مشابه ما را دارید. راه‌حل‌ها سه الگوی بالا به‌علاوه MCP Tool Search هستند.

چرا این برای افرادی که Statnive را اجرا می‌کنند اهمیت دارد

CLAUDE.md ما در مخزن Statnive روی GitHub عمومی است — به همان دلیلی که خط لوله آزمون ما عمومی است. یک پیکربندی ریشه فشرده به معنای نشست‌های سریع‌تر، اجراهای ارزان‌تر و یک مدل است که در واقع آنچه را که اهمیت دارد می‌خواند به جای غرق شدن در مرجع «همیشه در دسترس، به‌ندرت لازم». آن کارایی به همان چیزی که کاربران ما به آن اهمیت می‌دهند منتقل می‌شود: یک plugin که اغلب عرضه می‌شود و زیر بودجه 5KB tracker خود می‌ماند.

Statnive را امتحان کنید

تحلیل‌گری حریم‌خصوصی‌محور WordPress، ساخته شده توسط تیمی که بودجه‌های توکن را به همان جدیت بودجه‌های عملکردی می‌گیرد. Statnive را رایگان از WordPress.org نصب کنید — داده‌های شما روی سرور شما باقی می‌ماند، شیوه‌های مهندسی ما روی GitHub برای هر کسی که بازرسی کند می‌ماند.