clinicpro/.claude/skills/prompt-writer/SKILL.md

name, description

name	description
prompt-writer	تولید فایل پرامپت .md برای یک قابلیت یا باگ‌فیکس در پروژه ClinicPro. استفاده کن وقتی کاربر می‌گوید «یک پرامپت بنویس»، «پرامپت بساز»، «write a prompt»، «برام پرامپت بنویس برای X». این skill پروژه را تحلیل می‌کند، سپس یک فایل .md کامل در .claude/prompt/ می‌سازد و دستور اجرا را نمایش می‌دهد.

قبل از شروع، فایل .claude/guidelines.md را بخوان و همهٔ بخش‌های آن را اعمال کن (اگر روت جلسه workspace است: clinicpro/.claude/guidelines.md). آن فایل «چگونه کار کردن» (درک مسئله، معیار پذیرش، تست، مستندات، SOLID، رفتار تحلیل‌گر) را تعیین می‌کند؛ این skill فقط قواعد stack و مسیرها و قالب خروجی را دارد. در تناقض، guidelines برنده است.

نحوه دریافت ورودی

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

---

مراحل اجرا

مرحله ۱ — درک موضوع

قبل از نوشتن پرامپت:

1. موضوع را تحلیل کن: باگ‌فیکس است یا قابلیت جدید؟
2. فایل‌های مرتبط را شناسایی کن:
   • Backend: src/ — Controllers، Services، Entities، Repositories
   • Frontend: assets/admin/pages/، assets/admin/components/
   • مستندات: docs/api/
3. APIهای موجود را بررسی کن: ddev exec php bin/console debug:router | grep api — API جدید فقط وقتی هیچ اندپوینت موجودی، حتی با توسعه، کافی نباشد؛ دلیلش را در پرامپت بنویس
4. کد مرتبط را بخوان: فقط فایل‌هایی که مستقیم به موضوع مربوطند — کد واقعی، نه حافظه

بعد از خواندن، مسئله را با کلمات خودت بازگو کن و به کاربر نشان بده: «مشکل این است که X؛ رفتار درست Y است؛ محدودهٔ تغییر فایل‌های Z». اگر این سه جمله را نمی‌توانی بنویسی، هنوز مسئله را نفهمیده‌ای — سوال بپرس.

نقش تحلیل‌گر (guidelines §۶): اگر راه‌حلی که کاربر خواسته اشتباه، ناقص یا پرریسک است، همین‌جا صریح و با دلیل بگو و منتظر تعیین تکلیف بمان — پرامپتِ یک راه‌حل غلط را ننویس. اگر چند راه‌حل جدی وجود دارد، کوتاه مقایسه کن (مزایا/معایب/ریسک) و دلیل انتخاب را در پرامپت ثبت کن.

مرحله ۲ — نام‌گذاری فایل

نام فایل: kebab-case، توصیفی، کوتاه.

مثال‌ها:

• fix-invitation-accept.md
• doctor-dashboard-stats.md
• clinic-gallery-upload.md
• appointment-sms-notification.md

مرحله ۳ — ساخت فایل پرامپت

فایل را در .claude/prompt/<name>.md بساز با این ساختار:

---

# <عنوان واضح>

## زمینه

<یک پاراگراف: چرا این تغییر لازم است؟ وضعیت فعلی چیست؟>

## مشکل / هدف

<توضیح دقیق مشکل یا قابلیت مورد نیاز>

## معیار پذیرش

<چه چیزی باید درست کار کند تا «تمام» حساب شود — قابل تست، نه کلی>

- ✅ موفق: <رفتار درست در مسیر عادی — مثلاً «POST /api/v1/... با توکن ادمین → 200 و رکورد ذخیره می‌شود»>
- ❌ خطا: <رفتار درست در مسیر خطا — مثلاً «بدون permission → 403 با envelope خطا و کد از ErrorCodes»>
- ⚠️ مرزی: <حداقل یک حالت مرزی — لیست خالی، صفحه آخر pagination، تاریخ مرزی شمسی، …>

## فایل‌های مرتبط

| فایل | نقش |
|------|-----|
| `src/...` | ... |
| `assets/admin/...` | ... |

## وضعیت فعلی

<کد یا رفتار فعلی — کپی از کد واقعی پروژه، نه بازنویسی از حافظه؛ فقط بخش مرتبط>

```php / tsx
// کد فعلی مشکل‌دار یا ناقص

وظایف

۱. <اولین وظیفه>

<توضیح دقیق + راه‌حل پیشنهادی>

// نمونه کد یا pseudocode

نحوه تست: <دقیقاً چطور این وظیفه تست می‌شود — دستور، curl با داده واقعی، سناریوی UI — تا run-prompt مجبور نباشد تست را اختراع کند>

۲. <دومین وظیفه>

...

نکات مهم

• <نکته معماری یا محدودیت مهم>
• <edge case که باید پوشش داده شود>
• <الگوی پروژه که باید رعایت شود؛ اگر راه‌حل از الگویی (Strategy، Factory، Event، …) استفاده می‌کند: نام الگو + دلیل انتخابش>

---

### قوانین محتوای پرامپت

**باید داشته باشد:**
- مسیر دقیق فایل‌هایی که باید تغییر کنند
- بخش «معیار پذیرش» با هر سه سناریو (موفق/خطا/مرزی) — **پرامپت بدون معیار پذیرش ناقص است**
- وضعیت فعلی کد (کپی از کد واقعی، نه توصیف کلی) — خود فایل پرامپت سند است
- راه‌حل پیشنهادی با نمونه کد؛ اگر الگو دارد، نام + دلیل
- «نحوه تست» برای هر وظیفه‌ای که منطق دارد
- edge caseها و الگوهای پروژه که باید رعایت شوند (BaseController، TanStack Query، Zod، ...)

**نباید داشته باشد:**
- توضیحات کلی و بدیهی
- کدی که از پروژه واقعی کپی نشده
- وظایف نامشخص مثل «بررسی کن» بدون مشخص کردن چه چیزی
- abstraction «برای آینده» — الگو فقط وقتی الان نیازش هست (guidelines §۵)

**قوانین خاص پروژه که باید در پرامپت منعکس شود:**
- Backend: همه controllerها از `BaseController` ارث می‌برند؛ پاسخ‌ها با `$this->success()` / `$this->paginated()` / `$this->error()`
- Controller نازک: منطق در Service، کوئری در Repository؛ وابستگی‌ها با constructor injection (نه `new`)
- خطاها با `AppException(ErrorCodes::ERR_XXX)` و پیام فارسی در `src/Shared/Constant/ErrorCodes.php`
- Frontend paginated: items از `data?.data`، total از `data?.meta?.totalRecords`
- Frontend single: از `data?.data` (ممکن است double-nested باشد)
- Category API: triple-nested → `data?.data?.data ?? []`
- تاریخ‌ها: Unix timestamp صحیح؛ نمایش با `formatDate()` شمسی
- اگر Entity تغییر کرد: migration لازم است
- مستندات: بعد از هر تغییر API، فایل مربوطه در `docs/api/` باید به‌روز شود
- اگر endpoint توسط سایت عمومی (`nobat724_front`) هم مصرف می‌شود، در پرامپت ذکر کن — تغییر قرارداد در build کلاینت خطا نمی‌دهد

### مرحله ۴ — خروجی نهایی

بعد از ساخت فایل، فقط این سه مورد را نمایش بده:

توضیح: <یک جمله توصیف پرامپت> فایل پرامپت: .claude/prompt/.md دستور اجرا:

/run-prompt .claude/prompt/.md

---

## مثال

کاربر: برام یک پرامپت بنویس — وقتی دکتر دعوت کلینیک را قبول می‌کند به لیست پزشکان اضافه نمی‌شود

→ بررسی می‌کنم...

• src/ClinicInvitation/Service/ClinicInvitationService.php خوانده شد
• متد accept() فقط status تغییر می‌دهد، clinic->getDoctors()->add() صدا نمی‌زند
• Clinic entity دارای ManyToMany $doctors است

→ بازگویی: مشکل — accept() رابطه clinic_doctors را نمی‌سازد؛ رفتار درست — پزشک بعد از accept در لیست پزشکان کلینیک باشد؛ محدوده — ClinicInvitationService.php

→ فایل .claude/prompt/fix-invitation-accept.md ساخته شد (شامل معیار پذیرش: ✅ accept → پزشک در لیست / ❌ دعوت منقضی → خطا / ⚠️ accept تکراری → بدون رکورد تکراری)

توضیح: رفع باگ پذیرش دعوت — پزشک باید پس از accept به clinic_doctors اضافه شود. فایل پرامپت: .claude/prompt/fix-invitation-accept.md دستور اجرا:

/run-prompt .claude/prompt/fix-invitation-accept.md