فایل CLAUDE.md چیست؟ آموزش ساخت دستورالعمل دقیق برای Claude Code
فایل CLAUDE.md قوانین پایدار پروژه را در آغاز هر نشست Claude Code در دسترس عامل قرار می‌دهد. در این راهنما جای درست فایل، ساختار پیشنهادی، Rules مسیرمحور، Import، Permission و روش ارزیابی کیفیت دستورها را یاد می‌گیرید.
اگر در هر نشست Claude Code دوباره توضیح می‌دهید پروژه چگونه Build می‌شود، نام‌گذاری چه قاعده‌ای دارد یا قبل از تحویل کدام Testها باید اجرا شوند، بخشی از Context پایدار پروژه کم است. فایل CLAUDE.md محل ثبت همین دانش تکرارشونده است تا عامل از ابتدای کار بداند در این مخزن چه قراردادهایی معتبرند.
این فایل جای Prompt بلند، مستندات کامل معماری یا مجوز فنی نیست. یک CLAUDE.md خوب، کوتاه و قابل‌سنجش است: فرمان‌های واقعی، مسیرهای مهم، محدودیت‌های صریح و تعریف پایان کار را بیان می‌کند. در ادامه ساختار، Scope، Rules، Import، امنیت و روش سنجش کیفیت آن را مرحله‌به‌مرحله پیاده می‌کنیم.
فایل CLAUDE.md چیست و چه مسئله‌ای را حل می‌کند؟
CLAUDE.md یک فایل Markdown حاوی دستورها و Context پایدار است که Claude Code در شروع نشست می‌خواند. اطلاعاتی مانند فرمان Build، Test و Lint، تصمیم‌های معماری، قرارداد نام‌گذاری و مسیر فایل‌های حساس در آن قرار می‌گیرند. فایل پروژه معمولاً وارد Version Control می‌شود تا همه اعضای تیم دستورهای یکسانی دریافت کنند.
این دستورها Context هستند، نه یک کنترل امنیتی قطعی. اگر جلوگیری فنی از خواندن فایل Secret یا اجرای فرمان خاص لازم است، باید از تنظیمات Permission استفاده کنید. راهنمای رسمی نیز CLAUDE.md را برای هدایت رفتاری و Settings را برای اعمال محدودیت فنی تفکیک می‌کند.
CLAUDE.md در چه مسیرهایی قرار می‌گیرد؟
| Scope | مسیر معمول | کاربرد | اشتراک‌گذاری |
|---|---|---|---|
| سازمانی | /etc/claude-code/CLAUDE.md یا مسیر Managed ویندوز | سیاست و استاندارد عمومی شرکت | با همه کاربران دستگاه |
| کاربر | ~/.claude/CLAUDE.md | ترجیح شخصی مشترک میان پروژه‌ها | فقط همان کاربر |
| پروژه | ./CLAUDE.md یا ./.claude/CLAUDE.md | قواعد تیمی مخزن | از طریق Git |
| محلی پروژه | ./CLAUDE.local.md | تنظیم شخصی همان پروژه | در .gitignore |
| مسیرمحور | ./.claude/rules/*.md | قانون ویژه فایل یا زیرپوشه | از طریق Git |
Claude Code فایل‌های موجود در مسیر جاری و والدهای آن را به‌ترتیب بارگذاری می‌کند و فایل نزدیک‌تر به محل اجرا دیرتر وارد Context می‌شود. فایل‌های داخل زیرپوشه‌ها هنگام خواندن فایل‌های همان بخش فعال می‌شوند. به همین دلیل محل اجرای فرمان claude بر مجموعه دستورهای دیده‌شده اثر دارد.
از کجا بفهمیم کدام فایل بارگذاری شده است؟
در نشست Claude Code فرمان /context را اجرا و بخش Memory files را بررسی کنید. فرمان /memory نیز فایل‌های حافظه و دستور را فهرست می‌کند و امکان بازکردن آن‌ها را می‌دهد. اگر قاعده‌ای رعایت نمی‌شود، پیش از بازنویسی Prompt مطمئن شوید فایل واقعاً در Scope نشست قرار گرفته است.
چه چیزهایی باید داخل CLAUDE.md باشد؟
قاعده انتخاب ساده است: فقط چیزی را بنویسید که Claude نمی‌تواند با یک جست‌وجوی سریع و مطمئن از مخزن کشف کند، یا اشتباه در آن هزینه دارد. فرمان‌های معتبر، Conventionهای غیرمعمول، مرزهای معماری و گیت تحویل از بهترین گزینه‌ها هستند.
- فرمان دقیق Restore، Build، Test، Lint و اجرای پروژه
- ساختار Solution و مالکیت هر Module در حد لازم
- قاعده نام‌گذاری و Formatting که با تنظیم خودکار پوشش داده نمی‌شود
- مسیر Generated files و ممنوعیت ویرایش مستقیم آن‌ها
- روش افزودن Migration و محدودیت اجرای آن روی محیط واقعی
- Testهای الزامی برای هر نوع تغییر
- تعریف Done شامل Build موفق، Test و خلاصه فایل‌های تغییرکرده
- نیاز به تأیید انسان پیش از Push، Publish یا عملیات برگشت‌ناپذیر
فهرست Dependencyها، توضیح بدیهی پوشه‌ها و محتوای کامل README معمولاً ارزش تکرار ندارند. فایل طولانی در هر نشست Context مصرف می‌کند و احتمال تعارض میان دستورها را بالا می‌برد.
نمونه CLAUDE.md کوتاه و قابل‌سنجش
قالب زیر یک نقطه شروع است. فرمان‌ها و مسیرها باید با Repository واقعی شما جایگزین شوند؛ نگه‌داشتن مثال اشتباه از نداشتن دستور بدتر است.
# Project workflow ## Commands- Restore: `dotnet restore`- Build: `dotnet build --no-restore`- Test: `dotnet test --no-build` ## Architecture- Domain must not reference Infrastructure.- HTTP handlers live under `src/Api/Endpoints/`.- Never edit files under `src/Generated/`. ## Definition of done- Run build and affected tests.- Report changed files and any test not run.- Ask before migrations, publishing, or pushing.هر بند در این نمونه قابل بررسی است. عامل می‌تواند فرمان مشخص را اجرا کند، Dependency ممنوع را در Diff ببیند و اعلام کند کدام Test اجرا نشده است. عبارت‌هایی مانند «کد خوب بنویس» یا «امن باش» معیار مشاهده‌پذیر ندارند و رفتار یکنواخت ایجاد نمی‌کنند.
چگونه دستور خوب بنویسیم؟
هر دستور را با سه سؤال بسنجید: چه عملی باید انجام شود؟ در چه Scope یا شرایطی؟ نتیجه چگونه قابل‌تأیید است؟ برای نمونه، «قبل از Commit تست کن» مبهم است؛ «پس از تغییر پروژه Billing، فرمان dotnet test tests/Billing.Tests را اجرا و Failure را گزارش کن» محدوده و معیار دارد.
- از فعل صریح مانند Run، Use، Ask، Report یا Never استفاده کنید.
- مسیر، فرمان یا Artifact موردنظر را دقیق نام ببرید.
- شرط فعال‌شدن قاعده را مشخص کنید.
- رفتار هنگام Failure را بنویسید.
- نتیجه قابل‌مشاهده و قابل‌مرور تعریف کنید.
- دستور را با یک Task واقعی آزمایش کنید.
دستور مثبت بهتر است یا ممنوعیت؟
تا جای ممکن رفتار مطلوب را مستقیم بگویید؛ مثلاً «برای زمان از IClock استفاده کن» از «مستقیم DateTime نزن» راهنمای کامل‌تری است. بااین‌حال برای عملیات پرخطر مانند حذف داده، اجرای Migration روی Production یا Push مستقیم به شاخه اصلی، ممنوعیت صریح و Permission فنی هر دو لازم‌اند.
CLAUDE.md، Settings و Skills چه تفاوتی دارند؟
| ابزار | برای چه چیزی مناسب است؟ | زمان بارگذاری | نمونه |
|---|---|---|---|
CLAUDE.md | Context و قرارداد پایدار پروژه | شروع هر نشست در Scope | فرمان Build و مرز معماری |
.claude/rules/ | قانون ویژه مسیر یا نوع فایل | عمومی یا هنگام تطبیق Path | قواعد Endpointهای API |
| Settings | تنظیم ابزار، محیط و Permission | بر اساس Scope تنظیمات | Deny خواندن .env |
| Skill | فرایند تخصصی و چندمرحله‌ای | هنگام فراخوانی یا تشخیص نیاز | Workflow بررسی Pull Request |
| Auto memory | یادداشت‌های آموخته‌شده محلی | بخشی در شروع و بخشی عندالنیاز | نکته Debug پروژه |
اگر دستور باید همیشه در ذهن عامل باشد، CLAUDE.md مناسب است. اگر فقط برای فایل‌های خاص معنا دارد، Rule مسیرمحور بسازید. اگر محدودیت باید مستقل از تصمیم مدل اعمال شود، Settings و Permission لازم‌اند. فرایند بلند و تخصصی نیز بهتر است Skill باشد؛ راهنمای Agent Skills و SKILL.md تفاوت این لایه را با دستورهای همیشگی توضیح می‌دهد.
Rules مسیرمحور برای Monorepo
در پروژه بزرگ، بارگذاری همه قواعد Frontend، Backend، Database و Mobile در هر Task Context را شلوغ می‌کند. فایل‌های .claude/rules/*.md می‌توانند با Frontmatter فقط برای Patternهای مشخص فعال شوند.
---paths: - "src/Api/**/*.cs"--- # API security- Validate every external input.- Use the shared error response contract.- Add authorization tests for protected endpoints.- Never log tokens, passwords, or personal identifiers.Pattern باید دقیق باشد. Rule بسیار گسترده دوباره همان مشکل فایل اصلی شلوغ را ایجاد می‌کند و Rule بسیار محدود ممکن است روی فایل جدید فعال نشود. برای هر Rule یک نمونه فایل تطبیق‌یافته و یک نمونه خارج از Scope در Review تیم ثبت کنید.
Import و ارتباط با AGENTS.md
در CLAUDE.md می‌توانید با نوشتن @path/to/file محتوای فایل دیگری را Import کنید. مسیر نسبی نسبت به فایل حاوی Import حل می‌شود. Import برای جلوگیری از کپی چندباره راهنمای تیم مفید است، اما به‌تنهایی مصرف Context را کم نمی‌کند؛ محتوای Importشده نیز در شروع وارد Context می‌شود.
اگر Repository برای عامل‌های دیگر AGENTS.md دارد، می‌توانید در CLAUDE.md بنویسید @AGENTS.md و فقط قواعد ویژه Claude Code را زیر آن اضافه کنید. این روش از دو نسخه ناسازگار جلوگیری می‌کند. Import خارج از Working directory ممکن است به تأیید کاربر نیاز داشته باشد؛ مسیر خارجی را بدون بررسی وارد فایل مشترک نکنید.
امنیت: CLAUDE.md جای Permission نیست
جمله «فایل‌های Secret را نخوان» یک یادآوری رفتاری است، نه مانع فنی. برای فایل‌هایی مانند .env، Credential و خروجی Build از permissions.deny در Settings استفاده کنید. قواعد Permission با ترتیب deny، سپس ask و سپس allow ارزیابی می‌شوند و Deny بر Allow اولویت دارد.
خود CLAUDE.md نیز بخشی از ورودی عامل است. تغییر آن در Pull Request باید مانند تغییر Configuration امنیتی بازبینی شود. دستور ناشناس، Import خارجی، فرمان Shell مبهم یا درخواست انتشار خودکار می‌تواند دامنه عمل عامل را تغییر دهد.
- مالک فایل و Reviewer مشخص داشته باشید.
- تغییرات CLAUDE.md را در Code Review برجسته کنید.
- Secret، Token، URL خصوصی و داده شخصی را در آن ننویسید.
- برای عملیات حساس از Ask یا Deny فنی استفاده کنید.
- به Agent اجازه ندهید صرفاً برای عبور از Test قواعد را بازنویسی کند.
- فرمان‌های دریافت‌شده از اینترنت را بدون بررسی اجرا نکنید.
چگونه فایل اولیه را بسازیم؟
فرمان /init می‌تواند مخزن را تحلیل و یک پیشنهاد اولیه ایجاد کند. خروجی را نسخه نهایی تلقی نکنید؛ موارد بدیهی، مسیرهای قدیمی و فرمان‌های نامعتبر را حذف کنید. هدف این است که دانش غیرقابل‌استنتاج تیم باقی بماند.
- README، فایل Solution و Pipeline را مرور کنید.
- فرمان‌های واقعی Build و Test را روی سیستم تمیز اجرا کنید.
- پنج خطای تکراری Agent یا اعضای تازه تیم را فهرست کنید.
- برای هر خطا یک دستور قابل‌سنجش بنویسید.
- قواعد تخصصی مسیرها را به
.claude/rules/منتقل کنید. - فایل را زیر ۲۰۰ خط نگه دارید و موارد تکراری را حذف کنید.
- با یک تغییر کوچک واقعی، میزان رعایت قواعد را بسنجید.
- پس از Review تیمی فایل را Commit کنید.
اگر هنوز Claude Code را نصب نکرده‌اید، ابتدا راهنمای نصب Claude Code در ویندوز را ببینید و بعد در یک Repository آزمایشی /init را اجرا کنید.
آزمون کیفیت CLAUDE.md
کیفیت فایل با زیبایی متن سنجیده نمی‌شود؛ باید ببینید روی نتیجه کار اثر قابل‌تکرار دارد یا نه. یک Task مرجع انتخاب کنید، آن را در نشست تازه اجرا و رفتار عامل را با Checklist مقایسه کنید. نشست تازه مهم است، چون History قبلی ممکن است ضعف فایل را پنهان کند.
- با
/contextبارگذاری فایل را تأیید کنید. - یک تغییر کوچک شامل Build و Test درخواست کنید.
- بررسی کنید عامل مسیر درست و فرمان درست را انتخاب کرده است.
- یک حالت Failure کنترل‌شده بسازید و نحوه گزارش را ببینید.
- تلاش برای خواندن فایل Denyشده را جداگانه آزمایش کنید.
- خلاصه خروجی را با Definition of done تطبیق دهید.
- موارد رعایت‌نشده را به دستور دقیق‌تر تبدیل کنید.
شاخص‌های ساده برای تیم
نرخ اجرای Test الزامی، تعداد اصلاح‌های تکراری در Review، تعداد دستورهای متناقض و حجم فایل را ماهانه ثبت کنید. اگر فایل رشد می‌کند اما خطاهای تکراری کم نمی‌شوند، اطلاعات زائد را حذف و Ruleها را به Scope مناسب منتقل کنید.
اشتباه‌های رایج
- نوشتن کتابچه کامل پروژه: Context پر می‌شود و قواعد مهم گم می‌شوند.
- دستور مبهم: عبارتی مانند «Best Practice را رعایت کن» قابل ارزیابی نیست.
- کپی از پروژه دیگر: فرمان و مسیر نادرست وارد Workflow می‌شود.
- تعارض میان فایل‌ها: قواعد نزدیک و دور رفتار متفاوتی می‌خواهند.
- ذخیره Secret: فایل مشترک به مسیر نشت Credential تبدیل می‌شود.
- اتکا برای امنیت: دستور رفتاری جای Deny و Sandbox را می‌گیرد.
- نداشتن Owner: قواعد منسوخ پس از تغییر معماری باقی می‌مانند.
- ویرایش برای عبور از Task: Agent قرارداد تیم را به‌جای کد تغییر می‌دهد.
چک‌لیست بازبینی پیش از Commit
- هر فرمان در محیط واقعی اجرا و تأیید شده است.
- هیچ Secret یا نشانی خصوصی در فایل نیست.
- هر دستور فعل، Scope و معیار بررسی دارد.
- قواعد مسیرمحور از فایل اصلی جدا شده‌اند.
- ممنوعیت‌های امنیتی در Settings نیز اعمال شده‌اند.
- Importها شناخته‌شده و قابل‌اعتمادند.
- تناقضی با README، CI یا فایل والد وجود ندارد.
- فایل کوتاه است و مالک نگهداری دارد.
- تغییر آن توسط حداقل یک Reviewer فنی دیده شده است.
جمع‌بندی
فایل CLAUDE.md زمانی ارزشمند است که دانش تکرارشونده تیم را به دستورهای کوتاه، دقیق و قابل‌آزمون تبدیل کند. آن را برای Context پایدار نگه دارید، Rules را برای Scope مسیرها، Skills را برای فرایندهای تخصصی و Settings را برای محدودیت فنی به کار ببرید.
از یک فایل کوچک با فرمان‌های واقعی و Definition of done شروع کنید. سپس فقط وقتی یک خطا تکرار شد یا Context ضروری تازه‌ای پدید آمد، قاعده اضافه کنید. نگهداری منظم و آزمون در نشست تازه، فایل را از انبار متن به قرارداد اجرایی تیم تبدیل می‌کند.
امروز در یک Repository آزمایشی فایل CLAUDE.md را با حداکثر ده دستور قابل‌سنجش بسازید، بارگذاری آن را با /context تأیید کنید و نتیجه یک Task کوچک را پیش از Commit خط‌به‌خط بازبینی کنید.