Imported from arsamadineh/Persian-Quote-API (AGENTS.md). Install upstream with npx skills add arsamadineh/Persian-Quote-API. Copyright stays with the author.

AGENTS.md

این فایل دربردارنده قواعد الزام‌آور برای هر مشارکت‌کننده انسانی یا ابزار اتوماسیون است که به کد منبع این پروژه دسترسی دارد یا در آن مشارکت می‌کند. نادیده گرفتن این قواعد به معنای نقض قرارداد مشارکت در پروژه است.

۱. ثبت تغییرات (Changelog)

این قانون مطلق است. هر تغییر در کد — حتی یک خط — باید در فایل lib/changelog.ts ثبت شود. رابط کاربری و صفحه /changelog مستقیماً همین فایل را می‌خوانند. تغییری که در changelog ثبت نشده، از دید کاربر نهایی وجود ندارد.

۱.۱ ساختار ثبت

فایل lib/changelog.ts آرایه‌ای به نام CHANGELOG دارد. هر عنصر نماینده یک «نسخه» است و شامل:

• version: رشته به ارقام فارسی (مثال: "۲.۳.۰"). از قاعده نسخه‌گذاری معنایی پیروی کند.
• isoDate: تاریخ میلادی به فرمت YYYY-MM-DD. فقط برای مرتب‌سازی استفاده می‌شود و به کاربر نمایش داده نمی‌شود.
• date: تاریخ شمسی به نوشته فارسی (مثال: "۱۳ تیر ۱۴۰۵").
• changes: آرایه‌ای از اشیاء با دو فیلد:
  • type: یکی از "added" | "changed" | "fixed" | "removed"
  • description: یک جمله کوتاه فارسی، معلوم، بدون ابهام.

جدیدترین نسخه همیشه در ابتدای آرایه قرار می‌گیرد.

۱.۲ قواعد نگارش توضیح

• فارسی روان: جملات کوتاه، معلوم، بدون ابهام. لحن رسمی-دوستانه، نه تبلیغاتی.
• بدون ایموجی: هیچ‌گونه ایموجی، شکلک، یا نویسه تزئینی در متن یا نام فیلد استفاده نشود.
• بدون اضافات بازاریابی: عبارت‌هایی مثل «عالی»، «بی‌نظیر»، «فوق‌العاده»، «در نهایت»، «تغییر دهنده بازی» مجاز نیستند.
• بدون نام تجاری: نام شرکت‌ها، محصولات، یا فناوری‌های خاص در توضیح changelog درج نشود مگر در موارد ضروری فنی.
• مبتدی‌دوستانه: فرض بر این است که خواننده توسعه‌دهنده‌ای است که با فارسی آشنایی دارد، اما با کل پروژه آشنا نیست.

۱.۳ قواعد نوع تغییر

• added: قابلیت، فایل، یا endpoint جدید.
• changed: رفتار موجود تغییر کرده (سازگار یا شکستن، مستند شده).
• fixed: رفع خطا یا رفتار نادرست.
• removed: فایل، فیلد، یا قابلیتی حذف شده.

۱.۴ فرآیند

1. پیش از هر commit، pull request، یا تغییر کد: ابتدا مقدار جدید را در lib/changelog.ts وارد کنید.
2. در حال رفع یک باگ: یک entry با type="fixed" اضافه کنید.
3. در حال افزودن قابلیت: یک entry با type="added" اضافه کنید.
4. در حال بازنویسی: یک entry با type="changed" اضافه کنید و توضیح دهید چه چیزی برای کاربر عوض شده است.
5. در حال حذف: یک entry با type="removed" اضافه کنید.
6. اگر بیش از یک نوع تغییر دارید، هر نوع را در entry جداگانه بنویسید.

۱.۵ قاعده نسخه‌گذاری

سه‌بخشی معنایی، به ارقام فارسی:

• افزایش MAJOR (X.۰.۰): تغییر breaking در API یا ساختار.
• افزایش MINOR (۰.X.۰): قابلیت جدید با سازگاری قبلی.
• افزایش PATCH (۰.۰.X): رفع باگ یا بهبود جزئی بدون تغییر API.

۲. زبان و محتوا

• تمام متن‌های رابط کاربری فارسی روان و راست‌چین باشد.
• متن انگلیسی فقط در موارد ضروری (URL، نام فناوری، اصطلاحات فنی شناخته‌شده) مجاز است.

۳. فوتر و ساختار صفحات

• فوتر یکپارچه در تمام صفحات از طریق app/layout.tsx و کامپوننت components/footer.tsx بارگذاری می‌شود. فوتر را در صفحات جداگانه تکرار نکنید.
• اگر در حال افزودن صفحه جدید هستید، نیازی به افزودن فوتر به آن نیست — به‌صورت خودکار نمایش داده می‌شود.

۴. آیکون‌ها

• لوگوی پروژه صرفاً برای فاوآیکن استفاده می‌شود (app/icon.svg). در رابط کاربری (ناوبری، فوتر، صفحات) از لوگو استفاده نکنید. از متن عنوان استفاده کنید.

۵. ممنوعیت ایموجی

هیچ ایموجی در کد تولید، رابط کاربری، commit message، یا توضیحات قرار ندهید — نه در متن دکمه، نه در عنوان، نه در توضیح، نه در changelog.

۶. حذف نشانه‌های متن تولید خودکار

متن‌های داخل مخزن نباید حاوی نشانه‌های متن تولیدشده توسط ابزارهای اتوماسیون باشند. پیش از commit، موارد زیر باید بررسی و حذف شوند:

۶.۱ کلمات و عبارت‌های ممنوع

• «قطعاً»، «البته»، «به طور کلی»، «لازم به ذکر است»، «همان‌طور که می‌دانید».
• ترکیبات انگلیسی رایج در متن فارسی بدون ضرورت: Certainly, Of course, Here is, It is important to note, Let's.
• توضیحات اضافی درباره خود فرآیند تولید متن (مثل «در این پاسخ»، «برای این منظور»).
• عناوین پرزرق‌و‌برق و بازاری: «بهترین»، «بی‌نظیر»، «منحصربه‌فرد»، «تغییر دهنده بازی».

۶.۲ ساختار جمله

• جمله‌های طولانی با چند بند موصولی که در یک پاراگراف فشرده شده‌اند، تجزیه شوند.
• لیست‌های سه‌تایی («سرعت، دقت، زیبایی») بی‌مورد حذف یا کوتاه شوند.
• شروع هر پاراگراف با ادات تعارف («خوب»، «همان‌طور که») ممنوع است.

۶.۳ اشاره به ابزار

• نام ابزار، شرکت، یا فناوری خاص تولیدکننده متن در commit message، کامنت کد، README، یا هر متن قابل مشاهده دیگری مجاز نیست.
• در توضیح PR، از عباراتی مثل «این PR توسط ... تولید شده» خودداری شود.

۶.۴ بررسی پیش از commit

پیش از ارسال commit:

1. فایل‌های تغییریافته را با git diff مرور کنید و هر نمونه از عبارت‌های بالا را حذف یا بازنویسی کنید.
2. در متن‌های فارسی، لحن رسمی-دوستانه را با لحن دوستانه-رسمی اشتباه نگیرید؛ متن باید محکم و صریح باشد.
3. اگر متن به نظر «بیش از حد کامل» یا «بیش از حد صیقل‌خورده» می‌رسد، احتمالاً نشانه‌ای از تولید خودکار است؛ بازنویسی با لحن طبیعی‌تر لازم است.

۷. عدم درج نام تجاری ابزار

نام هیچ ابزار، شرکت، محصول، یا فناوری خاصی — چه در commit، چه در کد، چه در README، چه در changelog — بدون ضرورت فنی روشن درج نشود. اگر نامی برای توضیح ضروری است، با اسم عمومی فناوری (مثل «پایگاه داده» به جای نام محصول) جایگزین شود.