نوشتن CLAUDE.md که واقعاً رفتار هوش مصنوعی را عوض کند

پاسخ کوتاه: CLAUDE.md فایلی در مخزن است که Claude Code در شروع هر نشست می‌خواند. با آن مثل یادداشت آشنایی برای یک نیروی جدید باهوش رفتار کنید که هر شب همه‌چیز را فراموش می‌کند: چطور build و تست کند، چه چیزی کجاست، قواعدی که از روی کد معلوم نیست و «تمام شد» یعنی چه. کوتاه، مشخص و قابل بررسی نگهش دارید و هر بار ایجنت یک اشتباه را دو بار تکرار کرد، یک خط به آن اضافه کنید.

یک مثال واقعی: سومین بار که از DateTime.Now استفاده کرد

ایجنت یک قابلیت به سرویس پرداخت اضافه می‌کند. کد کار می‌کند، تست‌ها پاس می‌شوند و در سه جا از DateTime.Now استفاده شده. پروژه همه‌جا از TimeProvider استفاده می‌کند تا تست‌های مغایرت‌گیری بتوانند زمان را کنترل کنند. اصلاحش می‌کنید. روز بعد، در نشست جدید، دوباره همین کار را می‌کند؛ چون چیزی که می‌خواند خلافش را نمی‌گوید.

یک خط در CLAUDE.md («هرگز از DateTime.Now یا DateTime.UtcNow استفاده نکن؛ TimeProvider را inject کن») این را برای همه نشست‌های بعدی حل می‌کند. ایده کل ماجرا همین است: کامنت‌های تکراری code review را به دستورالعمل دائمی تبدیل کنید.

چه چیزی در آن بنویسیم

1. دستورها. دستور دقیق build، تست، اجرا و migration. ایجنت این‌ها را اجرا می‌کند، پس باید عیناً درست باشند.
2. نقشه. کدام پروژه چه کاری می‌کند، نقطه ورود کجاست، تست‌ها کجا هستند. پنج تا ده خط، نه فهرست کامل پوشه‌ها.
3. قواعدی که در کد دیده نمی‌شوند. پول long به ریال است، هرگز double. زمان‌ها در دیتابیس UTC هستند. پکیج NuGet جدید بدون پرسیدن نه.
4. تعریف «تمام شد». build موفق، تست‌ها موفق، migration اگر مدل عوض شده، هیچ warning جدید.
5. مناطق خطر. فایل‌ها یا پوشه‌هایی که هرگز نباید ویرایش شوند (کد تولیدشده، تنظیمات production، ماژول پرداخت بدون تست).

چه چیزی را ننویسیم

• توصیه‌های کلی مثل «کد تمیز و قابل نگهداری بنویس». هیچ چیزی را عوض نمی‌کند.
• چیزهایی که ایجنت از کد می‌خواند، مثل این‌که از کدام ORM استفاده می‌کنید.
• توضیح طولانی. یک جمله «چرا» کافی است؛ ایجنت قاعده را لازم دارد، نه تاریخچه را.
• اطلاعات محرمانه. connection string و کلیدها هرگز در فایلی که ایجنت می‌خواند و ممکن است تکرارش کند نمی‌روند.

یک CLAUDE.md واقعی برای پروژه دات‌نت

# Wallet service

## Commands
- Build: dotnet build -warnaserror
- Test: dotnet test
- Add migration: dotnet ef migrations add <Name> -p src/Wallet.Infrastructure -s src/Wallet.Api

## Map
- src/Wallet.Api: minimal API endpoints, DI setup (Program.cs)
- src/Wallet.Domain: entities and rules, no EF or HTTP references
- src/Wallet.Infrastructure: EF Core DbContext, gateway clients
- tests/: xUnit, one test project per src project

## Rules
- Money is long in Rials. Never double or float.
- Never use DateTime.Now/UtcNow; inject TimeProvider.
- Ledger entries are append-only. No UPDATE or DELETE on LedgerEntries.
- Every POST that moves money takes an Idempotency-Key header.
- Don't add NuGet packages without asking.
- Don't edit tests to make them pass; fix the code or ask.

## Done means
- Build and all tests pass.
- New behaviour has a test.
- A migration exists if the model changed.

خود فایل را انگلیسی نوشته‌ام؛ ایجنت فارسی را هم می‌فهمد، ولی دستورها و نام‌ها در کد انگلیسی‌اند و یک‌دست ماندن به دقت کمک می‌کند.

زنده نگه داشتنش

• وقتی بزرگ شد، تودرتو کنید. یک CLAUDE.md داخل زیرپوشه وقتی اعمال می‌شود که ایجنت آن‌جا کار می‌کند؛ پس قواعد هر ماژول فایل ریشه را شلوغ نمی‌کند.
• مثل کد review کنید. در مخزن است، پس تغییراتش از pull request می‌گذرد و قواعد کهنه حذف می‌شوند.
• قواعد مهم را تست کنید. اگر قاعده‌ای واقعاً مهم است (نبودن DateTime.Now) با یک analyzer یا تست معماری پشتیبانی‌اش کنید. فایل راهنمایی می‌کند؛ build اجبار می‌کند.

مزایا و معایب

مزایا

• کامنت‌های review تکراری کمتر؛ ایجنت هر نشست را با قراردادهای شما شروع می‌کند.
• برای هم‌تیمی‌های انسانی هم یادداشت آشنایی است.
• ارزان: یک فایل کوچک که همراه کد نسخه‌بندی می‌شود.

معایب

• راهنماست، نه اجبار؛ قواعد مهم هنوز تست یا analyzer می‌خواهند.
• فایل طولانی یا متناقض به‌صورت ناپایدار رعایت می‌شود.
• نگهداری می‌خواهد، وگرنه کدبیسی را توصیف می‌کند که دیگر وجود ندارد.

می‌خواهید برای تیمتان جریان کار با کمک هوش مصنوعی راه بیندازید یا پروژه‌ای را با آن تحویل دهید؟ ببینید چطور می‌توانم کمک کنم.