62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# 🤖 AGENTS.md — دليل الوكلاء لمشروع diyaa.de
|
|
|
|
> أي agent (Claude Code أو غيره) يشتغل على هالمشروع لازم يتبع هالملف. الهدف: تعرف الوضع وتشتغل صح **بدون ما تقرأ كل الكود**.
|
|
|
|
---
|
|
|
|
## 1) قبل أي شغل — اقرأ التوثيق
|
|
|
|
كل الحقيقة موجودة بمجلد [`docs/`](./docs/):
|
|
|
|
1. [`docs/PROJECT-STATE.md`](./docs/PROJECT-STATE.md) — **الوضع الحالي الفعلي**. اقرأه أول شي.
|
|
2. [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) — المعمارية، مخطط الداتابيس، اتفاقيات المجلدات والمكوّنات.
|
|
3. [`docs/STACK.md`](./docs/STACK.md) — الستاك المعتمد (لا تضيف مكتبة خارج المعتمد بدون توثيق السبب).
|
|
4. [`docs/TODO.md`](./docs/TODO.md) — المهام المفتوحة.
|
|
5. [`docs/CHECKLIST.md`](./docs/CHECKLIST.md) — نظرة شاملة على المتبقّي.
|
|
6. [`docs/IDEAS.md`](./docs/IDEAS.md) — أفكار مستقبلية.
|
|
|
|
## 2) لما يُسأل "شو عنا شي نعملو؟"
|
|
|
|
- افتح `docs/TODO.md`.
|
|
- اقترح **أول مهمة `🔵 مفتوحة` وغير محجوبة** من أعلى القائمة.
|
|
- لا تقترح مهمة حالتها `⛔ محجوبة` قبل ما تخلص المهمة يلي بتحجبها.
|
|
|
|
## 3) أثناء التنفيذ
|
|
|
|
- غيّر حالة المهمة بـ `TODO.md` لـ `🟡 قيد التنفيذ`.
|
|
- التزم باتفاقيات `ARCHITECTURE.md`:
|
|
- **كل شي مكوّنات قابلة لإعادة الاستخدام.**
|
|
- **Tailwind + shadcn/ui** فقط للتنسيق (بدون CSS خام جديد).
|
|
- **كل المكتبات محليّة** — بدون CDN وقت التشغيل.
|
|
- Server Components افتراضياً؛ `"use client"` عند الحاجة فقط.
|
|
- دعم ar/en و RTL/LTR بكل مكوّن عام.
|
|
- كل مدخلات المستخدم تتحقّق بـ Zod.
|
|
|
|
## 4) بعد إنجاز المهمة (إلزامي)
|
|
|
|
1. **`docs/TODO.md`**: انقل المهمة من "🔵 مفتوحة" لـ "✅ منجزة (Ready)" مع التاريخ ورقم المهمة، وحرّر حالات المهام يلي انفتحت (من ⛔ لـ 🔵).
|
|
2. **`docs/PROJECT-STATE.md`**: حدّث جداول "الموجود/الناقص"، وأضف سطر بالـ Changelog إذا كانت خطوة كبيرة.
|
|
3. **`docs/CHECKLIST.md`**: علّم البنود المنجزة `[x]`.
|
|
4. إذا انبثقت فكرة جديدة مو مجدولة → ضيفها لـ `docs/IDEAS.md`.
|
|
|
|
> ⚠️ **القاعدة الذهبية:** لا تخلّي الكود يسبق التوثيق. إذا غيّرت كود وما وثّقت — الشغل مو خالص.
|
|
|
|
## 5) أوامر مفيدة
|
|
|
|
```bash
|
|
make start # تشغيل عبر Docker
|
|
make logs # اللوقات
|
|
make stop
|
|
npm run dev # تطوير محلي
|
|
npm run check # lint + typecheck + build
|
|
```
|
|
|
|
(بعد إضافة الداتابيس رح ينضاف: `make migrate`, `make studio`, `make seed` — شوف `ARCHITECTURE.md §9`.)
|
|
|
|
## 6) حدود مهمة
|
|
|
|
- **لا ترفع أسرار للـ git** (SMTP, DATABASE_URL, AUTH secret). كلها بـ `.env` فقط.
|
|
- لا تضيف dependency خارج `STACK.md` بدون توثيق السبب بـ `PROJECT-STATE.md`.
|
|
- لا تكسر وضع coming-soon / الصيانة الموجود.
|
|
- حافظ على بنية النشر (Docker + Traefik) شغّالة.
|