✨ AGENTS.md Generator

یک ابزار جامعه‌محور برای ساخت فایل AGENTS.md به‌شکل استاندارد، سریع و قابل‌فهم
برای بهبود تجربه Vibe Coding و همکاری بهتر با مدل‌های هوش مصنوعی.

چرا این پروژه؟ • ویژگی‌ها • شروع سریع • معماری • مشارکت

---

📌 درباره پروژه

AGENTS.md Generator با هدف کمک به توسعه‌دهنده‌ها ساخته شده تا بتوانند برای پروژه‌های خود یک فایل راهنمای دقیق و حرفه‌ای برای Agentها (مثل Codex، Cursor، Claude Code و ...) تولید کنند.

این پروژه تجاری نیست و با هدف یاری‌رساندن به جامعه توسعه‌دهندگان ساخته شده است.

---

🎯 چرا این پروژه؟

وقتی Agentها بدون کانتکست درست وارد کد می‌شوند، معمولاً این مشکلات رخ می‌دهد:

• تغییرات ناسازگار با معماری پروژه
• نقض استانداردهای تیم
• خروجی‌های غیرقابل پیش‌بینی
• اتلاف زمان در بازخوردهای رفت و برگشتی

این ابزار کمک می‌کند با تولید یک AGENTS.md استاندارد:

• Agent دقیقاً بداند چه کاری انجام دهد.
• خروجی‌ها با سبک تیم و پروژه هم‌راستا شوند.
• کیفیت همکاری انسان + AI بهتر و پایدارتر شود.

---

✅ ویژگی‌ها

• تولید خودکار فایل AGENTS.md با ساختار حرفه‌ای
• پشتیبانی از فارسی و انگلیسی
• انتخاب سبک UI/UX مرجع (Design Style Mapping)
• امکان تکمیل خودکار فیلدهای اختیاری با best-practice
• پیش‌نمایش زنده خروجی
• خروجی در قالب‌های:
  • .md
  • .html
  • .pdf
• رابط کاربری مدرن با پشتیبانی از:
  • حالت روشن/تاریک
  • راست‌به‌چپ (RTL) برای فارسی

---

🧱 معماری پروژه

این ریپو شامل دو اپ جداگانه است:

1) Angular App (ریشه پروژه)

اپ اصلی ژنراتور که فرم ورودی، تولید محتوا و خروجی نهایی را مدیریت می‌کند.

• مسیر: /src
• تکنولوژی: Angular 21 + Signals + Angular Material + Tailwind

2) Next.js App (agentsmd/)

یک لندینگ/سایت جانبی برای معرفی agents.md و محتوای مرتبط.

• مسیر: /agentsmd
• تکنولوژی: Next.js + React + Tailwind

---

🚀 شروع سریع

پیش‌نیازها

• Node.js 20+
• npm (برای اپ Angular)
• pnpm (برای اپ Next.js داخل agentsmd/)

---

اجرای اپ Angular (اصلی)

1. نصب وابستگی‌ها:

npm install

2. تعریف کلید Gemini در فایل env (محیط توسعه):

# .env.local
GEMINI_API_KEY=your_key_here

3. اجرا:

npm run dev

اپ روی آدرس زیر در دسترس خواهد بود:

• http://localhost:3000

---

اجرای اپ Next.js (agentsmd/)

cd agentsmd
pnpm install
pnpm dev

---

🛠️ اسکریپت‌های مهم

در ریشه (Angular)

دستور	توضیح
npm run dev	اجرای سرور توسعه روی پورت 3000
npm run lint	اجرای ESLint
npm run test	اجرای تست‌ها
npm run build	بیلد production

در agentsmd/ (Next.js)

دستور	توضیح
pnpm dev	اجرای محیط توسعه Next.js
pnpm lint	بررسی lint
pnpm build	بیلد production
pnpm start	اجرای بیلد production

---

🧠 AGENTS.md چیست و چه باید داشته باشد؟

یک AGENTS.md خوب بهتر است شامل این بخش‌ها باشد:

1. معرفی پروژه و هدف
2. نکات محیط توسعه
3. دستورالعمل تست
4. قواعد Pull Request
5. استانداردهای کدنویسی
6. دستورات مهم پروژه
7. منابع مرجع

این ابزار دقیقاً همین ساختار را تولید می‌کند تا Agent با کمترین ابهام کار کند.

---

🌍 راهنمای استفاده پیشنهادی

1. فرم را کامل کنید (نام پروژه، توضیح، Tech Stack).
2. در صورت نیاز، سبک UI/UX را انتخاب کنید.
3. اگر می‌خواهید بخش‌های خالی با استاندارد پر شوند، گزینه مربوطه را فعال کنید.
4. روی Generate بزنید.
5. خروجی را بررسی و سپس با فرمت دلخواه دانلود کنید.

---

🔐 نکات مهم

• این پروژه برای تسهیل تولید مستندات Agent ساخته شده، نه جایگزینی کامل تصمیم مهندسی تیم.
• بهتر است خروجی نهایی AGENTS.md همیشه توسط انسان بازبینی شود.
• اگر تیم شما قوانین خاصی دارد، حتماً بعد از تولید فایل، شخصی‌سازی انجام دهید.

---

🤝 مشارکت

مشارکت شما بسیار ارزشمند است.

اگر ایده یا بهبود دارید:

1. Fork کنید
2. Branch جدید بسازید
3. تغییرات را commit کنید
4. Pull Request باز کنید

پیشنهاد می‌شود در PR:

• دلیل تغییر را واضح بنویسید
• اگر UI تغییر کرده، اسکرین‌شات بگذارید
• اگر رفتار جدید اضافه شده، تست/اعتبارسنجی هم اضافه کنید

---

🗺️ نقشه راه کلی

• بهبود کیفیت خروجی AGENTS.md برای سناریوهای پیچیده‌تر
• افزایش پوشش تست (unit + integration)
• ماژولارتر کردن ساختار UI
• بهبود مستندات توسعه‌دهنده و Contribution Guide

---

📄 License

برای لایسنس، فایل‌های زیر را ببینید:

• agentsmd/LICENSE (برای زیرپروژه Next.js)
• لایسنس اپ ریشه را در صورت نیاز به‌صورت مستقل اضافه/شفاف کنید.

---

ساخته‌شده با ❤️ برای جامعه توسعه‌دهندگان و طرفداران هوش مصنوعی