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

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

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

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

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

چرا CLAUDE.md نوشتهٔ مستقل خودش را می‌خواهد

در نوشتهٔ کلی‌ترمان دربارهٔ بهینه‌سازی توکن، جستجوی ابزار MCP بزرگ‌ترین اهرم بود. CLAUDE.md اهرم دوم است. پژوهش‌ها روی فریم‌ورک‌های بزرگ Claude Code نشان می‌دهند که پیکربندی‌های ریشهٔ بهینه‌شده به کاهش 54 تا 62 درصدیِ سربار پایه می‌رسند؛ و یک ضدالگوی مستندشده — یک فایل CLAUDE.md با 2,800 خط — حدوداً 62% از توکن‌های هر نشست را هدر می‌داد.

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

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

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

وضعیت قبل ما: 820 خط، حدوداً 12% از کانتکست

فایل CLAUDE.md اصلی ما مثل یک دفترچهٔ راهنمای شرکت خوانده می‌شد. هر اسکیلی را که به کار می‌بردیم مستند کرده بود، هر گام دروازهٔ انتشار را، هر ظرافتِ پیکربندی استانداردهای کدنویسی وردپرس‌مان را، هر قرارداد نام‌گذاری برای کامپوننت‌های React را، و هر قاعدهٔ محدودسازی دارایی‌های مدیریتی را. واقعاً مرجع مفیدی بود. اما همین فایل هم در هر نشست بارگذاری می‌شد، حتی نشست‌هایی که به بیشترِ آن هیچ ربطی نداشتند.

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

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

هر چیزی که با «خیر» علامت خورده بود، در هر نشست مالیات می‌داد تا برای کسری از نشست‌ها در دسترس باشد. این می‌شود حدوداً 6,300 توکنِ هدررفته — یعنی حدود 3% از کل پنجرهٔ کانتکست، آن‌هم به‌صورت دائمی.

وضعیت بعد ما: 162 خط، حدوداً 0.75%

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

الگوی 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 |

پژوهش‌ها روی فریم‌ورک‌های بزرگ نشان می‌دهند که هزینهٔ این الگو حدود 800 توکن است، در برابر بیش از 3,000 توکن برای نثر پرحرفِ هر اسکیل. مسیریابیِ Claude همچنان درست کار می‌کند، چون همان کلیدواژه‌های راه‌انداز چیزی است که واقعاً با آن تطبیق می‌دهد؛ آن نثر بلندِ «کِی این اسکیل را به کار ببر و کِی نبر» که قبلاً می‌نوشتیم هیچ کمکی به مسیریابی نمی‌کرد، فقط کانتکست را پر می‌کرد.

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

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

این هم آن ویژگی کلیدی‌ای که بیشتر توسعه‌دهنده‌ها از قلم می‌اندازند: فایل‌های CLAUDE.md تودرتو در زیرشاخه‌ها به‌صورت تنبل بارگذاری می‌شوند. این‌ها فقط زمانی وارد کانتکست می‌شوند که 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 می‌نویسیم، statnive/CLAUDE.md خودکار بارگذاری می‌شود و یادداشت‌های استانداردهای کدنویسی وردپرس، قاعدهٔ الزام $wpdb->prepare() و قاعدهٔ محدودسازی دارایی‌های مدیریتی را با خودش می‌آورد. وقتی محتوای وبلاگ را به‌صورت MDX می‌نویسیم، statnive-website/CLAUDE.md همراه با قراردادهای Astro و یادداشت‌های سبک‌نگارش خانگی بارگذاری می‌شود. هیچ‌کدام در کار آن یکی دخالت نمی‌کند.

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

الگوی 3: قواعد مسیرمحور در `.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: بی‌قیدوشرط بارگذاری می‌شوند؛ بنابراین این‌ها را به مشتی محدود و دقیق نگه می‌داریم (قواعد حریم خصوصی، قواعد امنیتی، قراردادهای کامیت).

ما حدود 1,800 توکنِ قراردادهای مخصوص فریم‌ورک را از CLAUDE.md ریشه بیرون بردیم و درون قواعد مسیرمحور زیر .claude/rules/ گذاشتیم. این‌ها هنوز هم به‌محض ربط‌داشتن مطمئن شلیک می‌کنند، و وقتی بی‌ربط‌اند هیچ هزینه‌ای ندارند.

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

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

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

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

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

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

Claude این مسیرها را وقتی می‌خواند که واقعاً به آن‌ها نیاز داشته باشد — با ابزار Read و به‌محض نیاز. هزینهٔ پایه صفر، نتیجهٔ عملی همان.

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

بعد از این حذف‌ها، فایل CLAUDE.md ریشهٔ 162‌خطی دقیقاً این موارد را در خود دارد:

بخش	خط	چرا ماند
فلسفهٔ محصول (8 اصل برگرفته از پژوهش)	28	هر تصمیمی را شکل می‌دهد؛ باید روی همهٔ نشست‌ها اثر بگذارد
نقشهٔ فضای کاری	18	جهت‌گیری در یک نگاه؛ برای هر نشست بارگذاری می‌شود
قواعد حریم خصوصی (غیرقابل‌مذاکره)	16	تغییرناپذیرهای حیاتی — کوکی، IP خام، سالت، SHA-256
قاعدهٔ محدودسازی دارایی‌های مدیریتی	22	قبلاً ما را گاز گرفته؛ دامنهٔ گسترده‌ای دارد
سیاست کامیت (تریلر co-authored-by ممنوع است)	8	قرارداد سراسری git
قاعدهٔ گردش‌کار `/simplify`	18	الزام دروازهٔ کیفیت ما
جدول راه‌انداز اسکیل	32	جایگزین حدود 30 بخشِ پرحرفِ هر اسکیل می‌شود
مسیرهای کلیدی (اشاره‌گر، نه واردکردن)	20	ارجاع‌های یک‌خطی به مستندات

هر چیز دیگری یا به CLAUDE.md تودرتو رفت، یا به قواعد مسیرمحور، یا به بدنهٔ تک‌تک اسکیل‌ها.

چه چیزی را بهینه نکردیم

اعتراف‌های صادقانه، با همان الگوی بقیهٔ این سری:

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

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

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

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

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

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

چرا این موضوع برای کسانی که Statnive را اجرا می‌کنند اهمیت دارد

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

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

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