vibe-coding-college-specs/.agents/rules/quera-styleguide.md

شیوه‌نامهٔ نگارش فنی و استانداردهای کوئرا کالج

دورهٔ وایب کدینگ (Vibe Coding)

این شیوه‌نامه استانداردهای زبانی، ساختاری و بصری درس‌نامه‌های متنی و تمرین‌های دوره را مشخص می‌کند.

---

۱. لحن و زبان نگارش (Tone & Voice)

• مخاطب دوره: افراد بدون پیش‌زمینهٔ کدنویسی (طراحان، مدیران محصول، کارآفرینان، بازاریاب‌ها و علاقه‌مندان).
• لحن: صمیمی، حرفه‌ای، تشویق‌کننده، شفاف و بدون اصطلاحات پیچیدهٔ غیرضروری.
• رعایت نیم‌فاصله‌ها: در تمام متون فارسی، نیم‌فاصله برای پیشوندها و پسوندها (مانند «می‌شود»، «درس‌نامه»، «ایجنت‌ها»، «راه‌اندازی») الزامی است.
• اصطلاحات فنی: اصطلاحات کلیدی (مثل Token, Context Window, Prompt, Agent, Git, Repository, PRD, MVP, Mock Data, Supabase) در اولین اشاره به همراه معادل انگلیسی درون پرانتز یا پاورقی آورده شوند.

---

۲. ساختار استاندارد درس‌نامه‌های کوئرا (Lesson Anatomy)

هر درس‌نامه متنی باید ساختار زیر را رعایت کند:

1. مقدمه و قلاب (Hook): یک موقعیت واقعی، مسئله یا چالش روزمره که ضرورت این موضوع را نشان می‌دهد.
2. شرح مفهوم به زبان ساده (Core Concept): توضیح اصل موضوع بدون پرداختن به جزییات زائد، همراه با نمودارها و دیاگرام‌های باکیفیت برداری (SVG / پکیج diagrams).
3. نمایش تصاویر و دیاگرام‌ها (Centered Image Tables):
   • قرارگیری تصویر در جدول تک‌خانه‌ای وسط‌چین مارک‌داون:

     | ![عنوان تصویر](./images/diagram.png) |
     | :-: |
     | توضیح تفصیلی و آموزنده زیر تصویر. |
     

4. جعبه‌های راهنما و هشدار (Quera Collapsible Details):
   • <details class="red"> با <summary>**هشدار: ...**</summary> برای تله‌ها و خطاهای رایج هوش مصنوعی
   • <details class="green"> با <summary>**نکته: ...**</summary> برای نکات کلیدی و Best Practiceها
   • <details class="violet"> با <summary>**بیشتر بدانید: ...**</summary> برای مباحث عمیق‌تر
5. بلوک‌های کد و هایلایت خطوط (<mark>):
   • استفاده از <mark class="green|blue|violet|yellow|red" title="..."> روی خطوط کلیدی
   • درج بلافاصلهٔ پاراگراف نقل‌قول (> ...) زیر هر بلوک کد برای تشریح خط‌به‌خط
6. جمع‌بندی و گام بعدی (Summary & Bridge): خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش و پل ارتباطی به درس بعدی.

---

۳. استاندارد تمرین‌های داوری خودکار (Judge Problems)

• داستان‌پردازی بومی (Iranian Startup Scenarios): تمرین‌ها حول مسائل واقعی استارتاپ‌ها (اسنپ‌فود، دیوار، طاقچه، دیجی‌کالا، فیلیمو، علی‌بابا، تپسی، شیپور، پونیشا، والکس، بازار، ویرگول، آپارات، جابینجا) طراحی می‌شوند.
• وضوح خروجی: دانشجو باید دقیقاً بداند چه فایل‌هایی با چه ساختاری و چه فرمتی از او خواسته شده است.
• پیام‌های خطای آموزشی: تست‌های داور خودکار باید خطاهای شفاف تولید کنند تا دانشجو با ارائهٔ همان خطا به هوش مصنوعی بتواند کد را دیباگ کند.