240 lines
14 KiB
Markdown
240 lines
14 KiB
Markdown
---
|
||
name: run-prompt
|
||
description: اجرای یک فایل پرامپت .md به صورت گامبهگام و ایمن. هر قابلیت را جداگانه پیادهسازی، تست و مستند میکند. استفاده کن وقتی کاربر میگوید "اجرای پرامپت"، "پرامپت را اجرا کن"، "run prompt"، یا مسیر یک فایل .md میدهد.
|
||
---
|
||
|
||
> **قبل از شروع، فایل `.claude/guidelines.md` را بخوان و همهٔ بخشهای آن را اعمال کن** (اگر روت جلسه workspace است: `clinicpro/.claude/guidelines.md`). آن فایل «چگونه کار کردن» (درک مسئله، todo، تعریف «تمام شد»، مستندات، SOLID، رفتار تحلیلگر، چکلیست پایانی §۷) را تعیین میکند؛ این skill فقط قواعد stack، دستورهای تست و مسیرها را دارد. در تناقض با متن پرامپت، guidelines برنده است — مگر کاربر صریحاً خلافش را بگوید.
|
||
|
||
## نحوه دریافت ورودی
|
||
|
||
اگر کاربر مسیر فایل داد → آن را بخوان.
|
||
اگر فایل مشخص نشد → بپرس: «مسیر فایل پرامپت .md را وارد کنید»
|
||
|
||
---
|
||
|
||
## قبل از شروع — تحلیل پرامپت و ساخت Todo
|
||
|
||
۱. فایل پرامپت را **کامل** بخوان
|
||
۲. مستندات موجود را بررسی کن: `docs/api/`
|
||
۳. کد واقعیِ مرتبط در `src/` و `assets/admin/` را بخوان — هیچ فرضی از حافظه
|
||
۴. **نقد پرامپت (guidelines §۶):** اگر راهحل پرامپت اشتباه، ناقص یا پرریسک است، همینجا صریح و با دلیل بگو و منتظر تعیین تکلیف بمان. اجرای بیچونوچرای پرامپت غلط، خطای agent است.
|
||
۵. لیست قابلیتها را استخراج کن؛ اگر پرامپت «معیار پذیرش» ندارد، خودت برای هر قابلیت بساز (موفق + خطا + مرزی) و به کاربر نشان بده
|
||
۶. **با `TodoWrite` todo کامل بساز** — یک آیتم قابلتست به ازای هر قابلیت
|
||
۷. به کاربر نمایش بده — تحلیل با **بازگویی مسئله و معیار پذیرش** تمام میشود، نه فقط لیست قابلیتها:
|
||
|
||
```
|
||
🧭 بازگویی مسئله: مشکل X است؛ رفتار درست Y؛ محدودهٔ تغییر فایلهای Z.
|
||
📋 قابلیتها + معیار پذیرش:
|
||
۱. [نام] — ✅ [موفق] / ❌ [خطا] / ⚠️ [مرزی]
|
||
۲. ...
|
||
⚠️ ایرادهای پرامپت (اگر هست): ...
|
||
|
||
🚀 شروع با قابلیت ۱ — آیا ادامه دهم؟
|
||
```
|
||
|
||
---
|
||
|
||
## قوانین اجرا (اجباری — هیچ استثنایی ندارد)
|
||
|
||
### ۱. Todo — ستون فقرات اجرا (guidelines §۲)
|
||
|
||
**در ابتدای هر اجرا** یک todo کامل با `TodoWrite` بساز:
|
||
- یک آیتم به ازای هر قابلیت با وضعیت `pending`
|
||
- هر آیتم **قابل تست** با خروجی مشخص («endpoint X با response Y کار میکند»)، نه فعل مبهم («بررسی سیستم نوبت»)
|
||
- آیتمهای زیر-مجموعه اضافه کن اگر قابلیت چند بخش مستقل دارد
|
||
|
||
**در طول اجرا:**
|
||
- هر قابلیت را که شروع میکنی → `in_progress`؛ در هر لحظه فقط یک آیتم `in_progress`
|
||
- آیتم فقط وقتی `completed` میشود که هر سه انجام شده باشد: **پیادهسازی + تست سبز + مستندات بهروز**
|
||
- اگر خطا داری که قابلیت را block کرده → یک آیتم `in_progress` باقی بماند تا رفع شود
|
||
- کشف کار جدید وسط اجرا (باگ جانبی، وابستگی پنهان) → آیتم جدید به todo + اطلاع به کاربر؛ انجام بیصدا ممنوع
|
||
|
||
### ۲. یک قابلیت در هر مرحله
|
||
- هرگز دو قابلیت را همزمان پیادهسازی نکن
|
||
- هرگز بدون تأیید موفقیت مرحله قبل به مرحله بعد نرو — خطا یعنی توقف کامل
|
||
|
||
### ۳. ترتیب اجرای هر قابلیت
|
||
|
||
```
|
||
① تحلیل ② طراحی ③ پیادهسازی ④ تست ⑤ رفع خطا ⑥ مستندسازی ⑦ چکلیست + Todo + گزارش
|
||
```
|
||
|
||
### ۴. سازگاری با پروژه
|
||
- همه تغییرات باید با Symfony 7 + React 19 سازگار باشند
|
||
- از الگوهای موجود پروژه پیروی کن (BaseController، TanStack Query، Zod، ...)
|
||
- اگر Entity تغییر کرد: `doctrine:migrations:diff` و `doctrine:migrations:migrate` اجرا کن
|
||
- اگر قرارداد API تغییر کرد: همه کلاینتهای وابسته را اصلاح کن — admin frontend (types، api calls) **و** اگر endpoint عمومی است، مصرف آن در `nobat724_front/services/` را دستی دنبال کن؛ این تغییرات در build خطا نمیدهند و در رانتایم میشکنند. نتیجه بررسی را گزارش بده.
|
||
|
||
### ۵. اصول کدنویسی (تفصیل در guidelines §۵)
|
||
- SOLID: Controller نازک، منطق در Service، کوئری در Repository؛ رفتار جدید با extension نه if روی نوع؛ وابستگی با constructor injection نه `new`
|
||
- سبک کد جدید = سبک فایلهای مشابه موجود در پروژه
|
||
- هیچ کامنت بدیهی؛ نامگذاری معنادار؛ هیچ abstraction بدون مصرفِ الان
|
||
- error handling فقط در boundaries واقعی (Controller، فراخوانی API، I/O)
|
||
|
||
---
|
||
|
||
## روند اجرای هر قابلیت
|
||
|
||
### مرحله ① — تحلیل
|
||
|
||
قبل از هر چیز:
|
||
- فایلهای مرتبط را بخوان
|
||
- endpoint های موجود را بررسی کن: `php bin/console debug:router | grep api` — API جدید فقط وقتی هیچ موجودی، حتی با توسعه، کافی نباشد
|
||
- Entity های مرتبط را شناسایی کن
|
||
- **ابهام = توقف**: سوال را همینجا بپرس، نه وسط پیادهسازی
|
||
|
||
### مرحله ② — طراحی
|
||
|
||
قبل از کدنویسی، طرح کوتاه را توضیح بده:
|
||
- چه فایلهایی ایجاد/تغییر میکنند
|
||
- چه API endpoint هایی اضافه/تغییر میکنند
|
||
- چه migration لازم است (اگر Entity تغییر کرد)
|
||
|
||
اگر بیش از یک راهحل جدی وجود دارد: مزایا، معایب، ریسک و حداقل یک گزینهٔ جایگزین را مقایسه کن و دلیل انتخاب را بنویس (guidelines §۶). قبل از ساختن چیز جدید: اول بگرد، بعد توسعه بده، در آخر بساز — و دلیلش را بنویس.
|
||
|
||
### مرحله ③ — پیادهسازی
|
||
|
||
- قابلیت را در todo روی `in_progress` بگذار
|
||
- **Backend اول**: Entity → Migration → Repository → Service → Controller
|
||
- **Frontend بعد**: Types → API call → Component → Route
|
||
- یک فایل در هر Edit/Write — نه bulk
|
||
|
||
### مرحله ④ — تست
|
||
|
||
Definition of Done: syntax/build سبز **و** پوشش سه سناریوی معیار پذیرش (موفق، خطا، مرزی). دستورهای زیر حداقلاند نه سقف — اگر قابلیت منطق دارد، همان منطق را واقعاً اجرا کن (curl به endpoint با داده و توکن واقعی، نه فقط `php -l`). اگر پرامپت «نحوه تست» داده، همان را اجرا کن.
|
||
|
||
```bash
|
||
# PHP syntax
|
||
ddev exec php -l src/Path/To/ChangedFile.php
|
||
|
||
# Symfony cache (اگر route یا config تغییر کرد)
|
||
ddev exec php bin/console cache:clear
|
||
|
||
# Migration (اگر Entity تغییر کرد)
|
||
ddev exec php bin/console doctrine:migrations:diff --no-interaction
|
||
ddev exec php bin/console doctrine:migrations:migrate --no-interaction
|
||
|
||
# Frontend build
|
||
ddev exec yarn dev
|
||
|
||
# Route وجود دارد؟
|
||
ddev exec php bin/console debug:router | grep "new-route-name"
|
||
|
||
# تست واقعی endpoint — سه سناریو:
|
||
# ✅ curl با توکن معتبر و داده واقعی → response مطابق معیار پذیرش
|
||
# ❌ بدون توکن / بدون permission / ورودی نامعتبر → status و error code درست
|
||
# ⚠️ حالت مرزی معیار پذیرش
|
||
```
|
||
|
||
اگر frontend تغییر کرد، TypeScript errors را بررسی کن:
|
||
```bash
|
||
ddev exec npx tsc --noEmit --project tsconfig.json 2>&1 | head -30
|
||
```
|
||
|
||
### مرحله ⑤ — رفع خطا
|
||
|
||
- اگر خطا بود → **همینجا** رفع کن، به مرحله بعد نرو؛ هیچ قابلیتی روی خرابهٔ قابلیت قبلی ساخته نمیشود
|
||
- اگر خطا در فایل دیگری بود → آن را هم رفع کن
|
||
- بعد از رفع خطا → دوباره تست را اجرا کن
|
||
|
||
### مرحله ⑥ — مستندسازی
|
||
|
||
سند در **همین جلسه** بهروز میشود — «بعداً» یعنی هرگز. اگر سند موجود با رفتار فعلی فرق دارد، اول سند را اصلاح کن، بعد قابلیت جدید را اضافه کن.
|
||
|
||
| تغییر | فایل مستندات |
|
||
|-------|-------------|
|
||
| `src/Auth/*` | `docs/api/auth.md` |
|
||
| `src/Doctor/*` | `docs/api/doctor.md` |
|
||
| `src/Clinic/*` | `docs/api/clinic.md` |
|
||
| `src/Appointment/Controller/AppointmentController.php` | `docs/api/appointment.md` |
|
||
| `src/Appointment/Controller/AppointmentSettings*` | `docs/api/appointment-settings.md` |
|
||
| `src/Payment/*` | `docs/api/payment.md` |
|
||
| `src/Admin/*` | `docs/api/admin.md` |
|
||
| `src/Secretary/*` | `docs/api/secretary.md` |
|
||
| `src/Representation/*` | `docs/api/representation.md` |
|
||
| `src/Blog/*` | `docs/api/blog.md` |
|
||
| `src/Rating/*` | `docs/api/rating.md` |
|
||
| `src/Settlement/*` | `docs/api/settlement.md` |
|
||
| `src/Sms/*` | `docs/api/sms.md` |
|
||
|
||
الزامات مستندسازی:
|
||
1. endpoint جدید با method، path، permission
|
||
2. Request body با تمام فیلدها و نوع داده
|
||
3. Response با **JSON واقعی از اجرای واقعی** (خروجی curl مرحله تست، نه دستساز)
|
||
4. تمام status codes و error codes
|
||
5. اگر پارامتر query داشت → همه را مستند کن
|
||
|
||
### مرحله ⑦ — چکلیست + Todo + گزارش
|
||
|
||
۱. **چکلیست پایان قابلیت — guidelines §۷** را کامل مرور کن؛ فقط اگر همهٔ آیتمها تیک خورد، ادامه بده
|
||
۲. **آیتم todo را `completed` کن** با `TodoWrite`
|
||
۳. گزارش کوتاه نمایش بده:
|
||
|
||
```
|
||
✅ قابلیت [شماره]: [نام] — تکمیل شد
|
||
|
||
معیار پذیرش: ✅ موفق / ❌ خطا / ⚠️ مرزی — هر سه تست شد (نتیجه واقعی، نه ادعا)
|
||
فایلهای تغییر یافته:
|
||
• src/...
|
||
• assets/admin/...
|
||
• docs/api/...
|
||
مستندات: docs/api/... بهروز شد | نیاز نداشت (دلیل)
|
||
|
||
📊 پیشرفت کلی:
|
||
✅ قابلیت ۱: [نام] — تکمیل
|
||
⏳ قابلیت ۲: [نام] — در صف
|
||
...
|
||
─────────────────────────────────
|
||
▶ قابلیت بعدی: [شماره] — [نام]
|
||
آیا ادامه دهم؟
|
||
```
|
||
|
||
در گزارش، بین **واقعیت** (خروجی تست واقعی)، **فرضیه** و **حدس** تفاوت بگذار و برچسبش را مشخص کن؛ اگر چیزی تست نشده، همان را بگو — قطعی جا نزن.
|
||
|
||
---
|
||
|
||
## قوانین خاص این پروژه
|
||
|
||
### Backend
|
||
- همه controller ها از `BaseController` ارث میبرند
|
||
- پاسخها: `$this->success($data)` | `$this->paginated(...)` | `$this->error(...)`
|
||
- خطاها با `AppException(ErrorCodes::ERR_XXX)`؛ کدها و پیام فارسی در `src/Shared/Constant/ErrorCodes.php`
|
||
- لیستهای admin از DQL array hydration (`.getArrayResult()`) استفاده کنند
|
||
- تاریخها Unix timestamp صحیح (نه DateTime object)
|
||
- بعد از هر تغییر Entity: حتماً migration بساز و اجرا کن
|
||
|
||
### Frontend
|
||
- دادههای paginated: items از `data?.data`، total از `data?.meta?.totalRecords`
|
||
- دادههای single resource: از `data?.data` (ممکن است double-nested باشد)
|
||
- Category API همیشه triple-nested: `data?.data?.data ?? []`
|
||
- JWT در `localStorage['clinicpro-auth']` → `state.token`
|
||
- همه تاریخها با `formatDate()` شمسی نمایش داده شوند (`fa-IR-u-ca-persian`)
|
||
- Form: React Hook Form + Zod resolver
|
||
- State management: TanStack Query v5 برای server state، Zustand برای client state
|
||
|
||
### CSS / UI
|
||
- از کلاسهای موجود استفاده کن: `btn primary sm`، `badge green`، `card`، `toolbar`، `field`، `avatar`، `appt-status`، ...
|
||
- هیچ کتابخانه CSS جدید اضافه نکن مگر ضرورت قطعی داشته باشد
|
||
- RTL رعایت شود
|
||
|
||
---
|
||
|
||
## مثال اجرا
|
||
|
||
```
|
||
کاربر: /run-prompt .claude/prompt/appointments-redesign.md
|
||
|
||
→ guidelines.md خوانده شد
|
||
→ فایل پرامپت را میخوانم...
|
||
→ کد مرتبط را میخوانم و پرامپت را نقد میکنم...
|
||
|
||
🧭 بازگویی مسئله: صفحه نوبتها آمار روز و تغییر وضعیت inline ندارد؛ رفتار درست، toolbar با آمار و تقویم شمسی است؛ محدوده AppointmentsPage + یک endpoint آمار.
|
||
📋 قابلیتها + معیار پذیرش:
|
||
۱. Stats Bar (backend + frontend) — ✅ آمار امروز درست / ❌ بدون توکن 401 / ⚠️ روز بدون نوبت → صفر
|
||
۲. تقویم شمسی Popup — ✅/❌/⚠️ ...
|
||
۳. بازطراحی Toolbar با date navigator — ...
|
||
۴. نمای جدولی با inline status change — ...
|
||
|
||
🚀 شروع با قابلیت ۱ (Stats Bar) — آیا ادامه دهم؟
|
||
```
|