diyaa.de/AGENTS.md

🤖 AGENTS.md — دليل الوكلاء لمشروع diyaa.de

أي agent (Claude Code أو غيره) يشتغل على هالمشروع لازم يتبع هالملف. الهدف: تعرف الوضع وتشتغل صح بدون ما تقرأ كل الكود.

---

1) قبل أي شغل — اقرأ التوثيق

كل الحقيقة موجودة بمجلد docs/:

1. docs/PROJECT-STATE.md — الوضع الحالي الفعلي. اقرأه أول شي.
2. docs/ARCHITECTURE.md — المعمارية، مخطط الداتابيس، اتفاقيات المجلدات والمكوّنات.
3. docs/STACK.md — الستاك المعتمد (لا تضيف مكتبة خارج المعتمد بدون توثيق السبب).
4. docs/TODO.md — المهام المفتوحة.
5. docs/CHECKLIST.md — نظرة شاملة على المتبقّي.
6. 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) أوامر مفيدة

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) شغّالة.