Claude Md

---
name: claude-md
description: ایجاد یا به‌روزرسانی فایل‌های CLAUDE.md مطابق با بهترین شیوه‌ها برای آماده‌سازی بهینه ایجنت هوش مصنوعی
---

## ورودی کاربر

```text
$ARGUMENTS
```

**باید** پیش از ادامه، ورودی کاربر را در نظر بگیرید (اگر خالی نیست). کاربر ممکن است مشخص کند:
- `create` - ایجاد CLAUDE.md جدید از صفر
- `update` - بهبود CLAUDE.md موجود
- `audit` - تحلیل و گزارش کیفیت CLAUDE.md فعلی
- یک مسیر مشخص برای ایجاد/به‌روزرسانی (مثلاً `src/api/CLAUDE.md` برای دستورالعمل‌های مخصوص یک دایرکتوری)

## اصول بنیادین

**مدل‌های زبانی بزرگ بدون حالت (stateless) هستند**: CLAUDE.md فایل اصلی پروژه است که در هر گفت‌وگو بارگذاری می‌شود (در کنار حافظه خودکار و قواعد بدون دامنه). این فایل سند اصلی آشناسازی ایجنت‌های هوش مصنوعی با کدبیس شماست.

### قواعد طلایی

1. **کمتر، بهتر**: مدل‌های زبانی پیشرفته می‌توانند حدود ۱۵۰ تا ۲۰۰ دستورالعمل را دنبال کنند. پرامپت سیستمی Claude Code هم‌اکنون حدود ۵۰ مورد از آن را مصرف می‌کند. CLAUDE.md خود را متمرکز و مختصر نگه دارید.

2. **کاربردپذیری جهانی**: فقط اطلاعاتی را بگنجانید که برای **هر** نشست مرتبط است. دستورالعمل‌های مخصوص یک وظیفه باید در فایل‌های جداگانه قرار گیرند.

3. **از Claude به‌عنوان linter استفاده نکنید**: دستورالعمل‌های سبک‌نویسی، زمینه را حجیم می‌کنند و پیروی از دستورالعمل‌ها را تضعیف می‌کنند. در عوض از ابزارهای قطعی (prettier، eslint و غیره) استفاده کنید.

4. **هرگز به‌صورت خودکار تولید نکنید**: CLAUDE.md بالاترین نقطه اهرمی مهار ایجنت است. آن را دستی و با دقت بنویسید.

## جریان اجرا

### ۱. تحلیل پروژه

ابتدا وضعیت فعلی پروژه را تحلیل کنید:

1. بررسی وجود فایل‌های CLAUDE.md:
   - سطح ریشه: `./CLAUDE.md` یا `.claude/CLAUDE.md`
   - مخصوص دایرکتوری: `**/CLAUDE.md`
   - پیکربندی جهانی کاربر: `~/.claude/CLAUDE.md`

2. شناسایی ساختار پروژه:
   - پشته فناوری (زبان‌ها، چارچوب‌ها)
   - نوع پروژه (مونوریپو، اپلیکیشن تک‌پارچه، کتابخانه)
   - ابزارهای توسعه (مدیر بسته، سیستم ساخت، اجراکننده تست)

3. مرور مستندات موجود:
   - README.md
   - CONTRIBUTING.md
   - package.json، pyproject.toml، Cargo.toml و غیره

### ۲. استراتژی محتوا (چیستی، چرایی، چگونگی)

CLAUDE.md را حول سه بُعد ساختار دهید:

#### چیستی - فناوری و ساختار
- مرور کلی پشته فناوری
- سازمان‌دهی پروژه (به‌ویژه برای مونوریپوها)
- دایرکتوری‌های کلیدی و اهداف آن‌ها

#### چرایی - هدف و زمینه
- پروژه چه کاری انجام می‌دهد
- چرا تصمیم‌های معماری خاصی گرفته شده است
- هر مؤلفه اصلی مسئول چیست

#### چگونگی - گردش کار و قراردادها
- گردش کار توسعه (bun در برابر node، pip در برابر uv و غیره)
- رویه‌ها و دستورات تست
- روش‌های تأیید و ساخت
- «دام‌های» حیاتی یا الزامات غیربدیهی

### ۳. استراتژی افشای تدریجی

برای پروژه‌های بزرگ‌تر، ایجاد پوشه `agent_docs/` را توصیه کنید:

```
agent_docs/
  |- building_the_project.md
  |- running_tests.md
  |- code_conventions.md
  |- architecture_decisions.md
```

در CLAUDE.md با دستورالعمل‌هایی مانند زیر به این فایل‌ها ارجاع دهید:
```markdown
برای دستورالعمل‌های تفصیلی ساخت، به `agent_docs/building_the_project.md` مراجعه کنید
```

**مهم**: به‌جای قطعه‌کد از ارجاع‌های `file:line` استفاده کنید تا از زمینه‌های قدیمی جلوگیری شود.

### ۴. محدودیت‌های کیفیت

هنگام ایجاد یا به‌روزرسانی CLAUDE.md:

1. **طول هدف**: زیر ۲۰۰ خط نگه دارید؛ کوتاه‌تر بهتر است
2. **بدون قواعد سبک**: هر دستورالعمل linter یا قالب‌بندی را حذف کنید
3. **بدون دستورالعمل مخصوص وظیفه**: به فایل‌های جداگانه منتقل کنید
4. **بدون قطعه‌کد**: در عوض از ارجاع به فایل استفاده کنید
5. **بدون اطلاعات تکراری**: آنچه در package.json یا README آمده را تکرار نکنید

### ۵. بخش‌های ضروری

یک CLAUDE.md خوش‌ساختار باید شامل موارد زیر باشد:

```markdown
# نام پروژه

توضیح یک‌خطی مختصر.

## پشته فناوری
- زبان اصلی و نسخه
- چارچوب‌ها/کتابخانه‌های کلیدی
- پایگاه داده/ذخیره‌سازی (در صورت وجود)

## ساختار پروژه
[فقط برای مونوریپوها یا ساختارهای پیچیده]
- `apps/` - نقاط ورود اپلیکیشن
- `packages/` - کتابخانه‌های مشترک

## دستورات توسعه
- نصب: `command`
- تست: `command`
- ساخت: `command`

## قراردادهای حیاتی
[فقط قراردادهای غیربدیهی و پرتأثیر]
- قرارداد ۱ با توضیح مختصر
- قرارداد ۲ با توضیح مختصر

## مشکلات شناخته‌شده / دام‌ها
[مواردی که به‌طور مداوم توسعه‌دهندگان را به اشتباه می‌اندازند]
- مشکل ۱
- مشکل ۲
```

### ۶. الگوهای ضدالگو که باید از آن‌ها پرهیز کرد

**نگنجانید:**
- دستورالعمل‌های سبک کدنویسی (از linter استفاده کنید)
- مستندات درباره نحوه استفاده از Claude
- توضیحات طولانی درباره الگوهای بدیهی
- نمونه‌های کد کپی-چسبانده‌شده
- بهترین شیوه‌های عمومی («کد تمیز بنویسید»)
- دستورالعمل‌های مخصوص وظایف خاص
- محتوای تولیدشده به‌صورت خودکار
- فهرست‌های TODO گسترده

### ۷. چک‌لیست اعتبارسنجی

پیش از نهایی‌سازی، بررسی کنید:

- [ ] زیر ۲۰۰ خط نگه داشته شده؛ کوتاه‌تر بهتر است
- [ ] هر خط برای **همه** نشست‌ها کاربرد دارد
- [ ] بدون قواعد سبک/قالب‌بندی
- [ ] بدون قطعه‌کد (از ارجاع به فایل استفاده کنید)
- [ ] دستورات تأیید شده‌اند که کار می‌کنند
- [ ] افشای تدریجی برای پروژه‌های پیچیده استفاده شده
- [ ] دام‌های حیاتی مستند شده‌اند
- [ ] بدون تکرار با README.md

## قالب خروجی

### برای `create` یا حالت پیش‌فرض:

1. پروژه را تحلیل کنید
2. پیش‌نویس CLAUDE.md را مطابق ساختار بالا بنویسید
3. پیش‌نویس را برای بازبینی ارائه دهید
4. پس از تأیید در مکان مناسب بنویسید

### برای `update`:

1. CLAUDE.md موجود را بخوانید
2. آن را با بهترین شیوه‌ها بررسی کنید
3. شناسایی کنید:
   - محتوایی که باید حذف شود (قواعد سبک، قطعه‌کد، مخصوص وظیفه)
   - محتوایی که باید فشرده شود
   - اطلاعات ضروری مفقود
4. تغییرات را برای بازبینی ارائه دهید
5. پس از تأیید تغییرات را اعمال کنید

### برای `audit`:

1. CLAUDE.md موجود را بخوانید
2. گزارشی با موارد زیر تولید کنید:
   - تعداد خط فعلی در برابر هدف
   - درصد محتوای دارای کاربرد جهانی
   - فهرست الگوهای ضدالگوی یافت‌شده
   - توصیه‌هایی برای بهبود
3. فایل را تغییر **ندهید**، فقط گزارش دهید

## مدیریت AGENTS.md

اگر کاربر درخواست ایجاد/به‌روزرسانی AGENTS.md را دارد:

**از نسخه v2.1.277، Claude Code فایل `AGENTS.md` را مستقیماً به‌عنوان دستورالعمل پروژه می‌خواند** — اما فقط زمانی که دایرکتوری کاری و تمام دایرکتوری‌های بالاتر آن هیچ `CLAUDE.md`، `.claude/CLAUDE.md` یا `CLAUDE.local.md` نداشته باشند. `~/.claude/CLAUDE.md`، CLAUDE.md مدیریت‌شده و `.claude/rules/` در این بررسی به حساب نمی‌آیند و در کنار آن بارگذاری می‌شوند. اینکه کدام فایل‌ها خوانده شوند توسط **Project instructions** در `/config` کنترل می‌شود: `claude-md-or-agents-md` (پیش‌فرض)، `claude-md-and-agents-md`، `claude-md` یا `managed-only`. در جایی که خواندن مستقیم در دسترس نیست — نسخه‌های پیش از v2.1.277 (پیش از v2.1.281 روی Bedrock/Vertex/Foundry، درگاه‌های LLM یا با غیرفعال بودن تله‌متری)، با غیرفعال بودن پلاگین داخلی‌ای که `AGENTS.md` را می‌خواند در `/plugin`، یا در برخی موارد نخستین نشست پس از ارتقا از v2.1.276 یا پیش‌تر — به وارد کردن آن از CLAUDE.md با `@AGENTS.md` یا ایجاد پیوند نمادین `CLAUDE.md` به آن بازگردید.

AGENTS.md یک فایل زمینه پروژه بین‌ابزاری است — همان *دسته* سند CLAUDE.md، نه یک قالب تعریف ایجنت. وجود دارد تا چند ایجنت کدنویسی بتوانند یک مجموعه قرارداد پروژه را به اشتراک بگذارند:
- دستورات ساخت، تست و lint
- قراردادهای سبک کد و معماری
- چیدمان مخزن و محل قرارگیری اجزا

زیرایجنت‌ها جداگانه در `.claude/agents/*.md` تعریف می‌شوند — نه در AGENTS.md.

اصول مشابهی را اعمال کنید:
- متمرکز و مختصر بمانید
- از افشای تدریجی استفاده کنید
- به‌جای جاسازی محتوا، به مستندات خارجی ارجاع دهید

## یادداشت‌ها

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

---

**آخرین به‌روزرسانی**: ۱۸ اکتبر ۲۰۲۶
**نسخه Claude Code**: 2.1.302
**منابع**:
- https://code.claude.com/docs/en/skills
- https://code.claude.com/docs/en/memory#agents-md
- https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable
- https://code.claude.com/docs/en/memory
**مدل‌های سازگار**: Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 5.5, Claude Haiku 4.5