171 lines
9.1 KiB
Markdown
171 lines
9.1 KiB
Markdown
---
|
|
name: prompt-writer
|
|
description: تولید فایل پرامپت .md برای یک قابلیت یا باگفیکس در پروژه ClinicPro. استفاده کن وقتی کاربر میگوید «یک پرامپت بنویس»، «پرامپت بساز»، «write a prompt»، «برام پرامپت بنویس برای X». این skill پروژه را تحلیل میکند، سپس یک فایل .md کامل در .claude/prompt/ میسازد و دستور اجرا را نمایش میدهد.
|
|
---
|
|
|
|
> **قبل از شروع، فایل `.claude/guidelines.md` را بخوان و همهٔ بخشهای آن را اعمال کن — از جمله `§۰ Grill` که قبل از هر تغییر اجباری است** (اگر روت جلسه 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` بساز با این ساختار:
|
|
|
|
---
|
|
|
|
```markdown
|
|
# <عنوان واضح>
|
|
|
|
## زمینه
|
|
|
|
<یک پاراگراف: چرا این تغییر لازم است؟ وضعیت فعلی چیست؟>
|
|
|
|
## مشکل / هدف
|
|
|
|
<توضیح دقیق مشکل یا قابلیت مورد نیاز>
|
|
|
|
## معیار پذیرش
|
|
|
|
<چه چیزی باید درست کار کند تا «تمام» حساب شود — قابل تست، نه کلی>
|
|
|
|
- ✅ موفق: <رفتار درست در مسیر عادی — مثلاً «POST /api/v1/... با توکن ادمین → 200 و رکورد ذخیره میشود»>
|
|
- ❌ خطا: <رفتار درست در مسیر خطا — مثلاً «بدون permission → 403 با envelope خطا و کد از ErrorCodes»>
|
|
- ⚠️ مرزی: <حداقل یک حالت مرزی — لیست خالی، صفحه آخر pagination، تاریخ مرزی شمسی، …>
|
|
|
|
## فایلهای مرتبط
|
|
|
|
| فایل | نقش |
|
|
|------|-----|
|
|
| `src/...` | ... |
|
|
| `assets/admin/...` | ... |
|
|
|
|
## وضعیت فعلی
|
|
|
|
<کد یا رفتار فعلی — کپی از کد واقعی پروژه، نه بازنویسی از حافظه؛ فقط بخش مرتبط>
|
|
|
|
```php / tsx
|
|
// کد فعلی مشکلدار یا ناقص
|
|
```
|
|
|
|
## وظایف
|
|
|
|
### ۱. <اولین وظیفه>
|
|
|
|
<توضیح دقیق + راهحل پیشنهادی>
|
|
|
|
```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/<name>.md
|
|
دستور اجرا:
|
|
|
|
/run-prompt .claude/prompt/<name>.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
|
|
```
|