vibe-coding-college-specs/.agents/skills/quera-lesson-author/SKILL.md

name, description

name	description
quera-lesson-author	Use this skill when drafting or refining full document-based lessons (README.md) from an approved spec.md file, following Quera College pedagogical, visual, and formatting standards (FastAPI College reference).

Quera Lesson Author (نگارش درس‌نامه‌های متنی کوئرا کالج)

این مهارت راهنمای جامع و استاندارد برای ایجنت‌های نویسنده است تا بتوانند یک سند مشخصات تایید شده (spec.md) را به یک درس‌نامهٔ کامل، جذاب، استاندارد و آمادهٔ انتشار در کوئرا کالج (README.md) تبدیل کنند.

الگو، ساختار و لحن این راهنما دقیقاً بر اساس استانداردهای پیاده‌سازی‌شده در دورهٔ FastAPI کوئرا کالج تدوین شده است.

---

۱. ساختار پوشه‌بندی هر درس‌نامه

هر درس‌نامه در پوشهٔ اختصاصی خود درون فصل مربوطه قرار دارد و باید شامل فایل متن درس‌نامه و پوشهٔ تصاویر اختصاصی باشد:

chapters/ch<XX>-<name>/<YY>-<lesson-slug>/
├── spec.md           # سند مشخصات و قرارداد یادگیری درس (ورودی ایجنت)
├── README.md         # متن کامل درس‌نامه کوئرا کالج (خروجی نهایی ایجنت)
└── images/           # پوشهٔ اختصاصی تصاویر، نمودارها و دیاگرام‌های درس
    ├── cover.png     # تصویر کاور استاندارد درس‌نامه (یا cover.svg)
    ├── [diagram-1].png / .svg
    └── [diagram-2].png / .svg

نکتهٔ نام‌گذاری فایل: فایل اصلی درس‌نامه در کوئرا کالج نامش README.md است (نه lesson.md).

---

۲. گردش‌کار نگارش درس‌نامه (Author Agent Workflow)

ایجنت نویسنده باید این ۵ گام را به ترتیب طی کند:

1. بررسی قرارداد spec.md:

   • اهداف یادگیری بلوم (Understand, Apply, Evaluate) را به دقت بخوانید.
   • مرزهای محتوا را رعایت کنید: موارد In-Scope باید کامل پوشش داده شوند و به هیچ‌وجه نباید وارد موضوعات Out-of-Scope شوید.
   • جدول واژگان تخصصی و اصطلاحات انگلیسی/فارسی را بررسی کنید.
   • لیست جایگاه‌های تصاویر و نمودارها (Visual Placeholders) را استخراج کنید.

2. تولید تصاویر و نمودارهای بصری (Visuals & Diagrams):

   • برای هر Placeholder مشخص‌شده در spec.md، تصویر یا دیاگرام متناظر را تولید و در پوشهٔ images/ ذخیره کنید.
   • از نمودارهای مدرن و تمیز با ابزارهایی مثل پکیج پایتونی diagrams (https://github.com/mingrammer/diagrams) یا کدهای برداری SVG با تم تیرهٔ کوئرا کالج (مشخصات تم در بخش ۵) استفاده کنید.
   • هر درس‌نامه باید حتماً دارای یک تصویر کاور (cover.png یا cover.svg) و حداقل ۱ تا ۴ نمودار مفهومی باشد.

3. نگارش متن درس بر اساس کالبدشکافی کوئرا:

   • ساختار استاندارد بخش‌ها (قلاب داستانی، نقشه درس، مفاهیم اصلی، جعبه‌های کال‌اوت، کدهای هایلایت‌شده و جمع‌بندی) را پیاده کنید.

4. اعمال استانداردهای فرانت‌اند کوئرا (HTML & CSS Components):

   • جعبه‌های هشدار، نکته و بیشتر بدانید را با تگ‌های <details class="..."> پیاده کنید.
   • خطوط مهم کد را با تگ‌های <mark class="..."> هایلایت نمایید.
   • تصاویر را در جدول‌های تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج کنید.

5. بازبینی نهایی و انطباق با معیارهای پذیرش (Acceptance Checklist).

---

۳. ساختار و کالبدشکافی استاندارد درس‌نامه (README.md)

متن نهایی درس‌نامه باید از این قالب دقیق پیروی کند:

# [عنوان درس‌نامه به فارسی روان]

[مقدمه و قلاب داستانی (Hook): یک موقعیت ملموس، سناریوی واقعی محصولی یا پرسش کلیدی که انگیزهٔ مطالعه را در دانشجو ایجاد می‌کند. مثلاً: «فرض کنید تغییر کوچکی روی یک اندپوینت پرداخت اعمال کرده‌ایم و می‌خواهیم همان امروز آن را دیپلوی کنیم...»]

| ![کاور درس‌نامهٔ [عنوان]](./images/cover.png) |
| :-: |

[نقشهٔ راه درس‌نامه (Overview): توضیح کوتاه ۲ تا ۳ جمله‌ای از اینکه در این درس قرار است چه مراحلی طی شود، چه ابزارهایی بررسی می‌شوند و در پایان دانشجو به چه خروجی ملموسی می‌رسد.]

## [عنوان بخش اول: مفهوم پایه یا چرایی موضوع]

[توضیح عمیق و شفاف مفهوم همراه با استعاره‌های ملموس و مقایسه‌های روزمره]

| ![عنوان یا توضیح کوتاه نمودار](./images/concept-diagram.png) |
| :-: |
| [توضیح تفصیلی، آموزنده و چندخطی زیر نمودار که پیام کلیدی و ارتباط اجزا را بیان می‌کند.] |

[ادامهٔ شرح درس...]

<details class="red">
<summary>**هشدار: [عنوان هشدار درباره خطای رایج، تله یا توهم هوش مصنوعی]**</summary>

[شرح خطای رایج یا توهم ایجنت و نحوهٔ پیشگیری و مهار آن. توضیح اینکه چرا این خطا رخ می‌دهد و چطور باید رفتار صحیح را ارزیابی کرد.]

</details>

## [عنوان بخش دوم: پیاده‌سازی عملی، ابزارها یا کُد]

[توضیح شیوهٔ استفاده از ابزار یا پیاده‌سازی گام‌به‌گام]

```python app.py python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    <mark class="green" title="پاسخ ساده برای بررسی سلامت سرویس">return {"service": "online", "status": "ok"}</mark>
```

> [باکس نقل‌قول بلافاصله پس از بلوک کد: تشریح خط‌به‌خط و دقیق کدهای بالا، کارکرد هر تابع، متغیرها و رفتاری که خروجی تولید می‌کند. هرگز کد بدون توضیح رها نمی‌شود.]

<details class="green">
<summary>**نکته: [قانون طلایی یا بهترین الگو (Best Practice)]**</summary>

[توضیح ترفند یا الگوی حرفه‌ای که کارایی را بالا می‌برد یا از اتلاف وقت دانشجو جلوگیری می‌کند.]

</details>

## [عنوان بخش سوم: مقایسه، سناریوهای خطا یا حالت‌های پیشرفته]

[بررسی حالت‌های خطا، تست یا مقایسهٔ گزینه‌های مختلف]

| معیار | روش الف | روش ب |
| :-: | :-: | :-: |
| سرعت اجرا | سریع | کند |
| انعطاف‌پذیری | بالا | محدود |
| هزینه | کم | بالا |

<details class="violet">
<summary>**بیشتر بدانید: [مبحث تکمیلی و معماری عمیق‌تر]**</summary>

[مطالعهٔ عمیق‌تر برای دانشجویانی که می‌خواهند از پشت‌صحنه یا تاریخچه و معماری مطلع شوند.]

</details>

## جمع‌بندی و گام بعدی

در این درس یاد گرفتیم که:
- **نکته ۱:** [خلاصه نکته کلیدی]
- **نکته ۲:** [خلاصه نکته کلیدی]
- **نکته ۳:** [خلاصه نکته کلیدی]

[پل ارتباطی به درس بعد]: در درس‌نامهٔ بعدی به سراغ **«[عنوان درس بعد]»** می‌رویم تا یاد بگیریم چطور ...

---

۴. اجزای خاص رابط کاربری و فرمت‌بندی کوئرا کالج (Quera Custom UI)

۱.۴. جدول نمایش تصاویر و دیاگرام‌ها (Centered Image Tables)

در کوئرا کالج، تصاویر مستقیماً رها نمی‌شوند؛ بلکه همیشه درون یک جدول مارک‌داون تک‌خانه‌ای وسط‌چین با کپشن توضیحی قرار می‌گیرند:

| ![متن جایگزین کوتاه](./images/filename.png) |
| :-: |
| متن توضیح تفصیلی و آموزنده زیر تصویر که پیام نمودار را تشریح می‌کند. |

۲.۴. جعبه‌های پیام و آکاردئون‌های رنگی (<details class="...">)

به جای الرت‌های مرسوم گیت‌هاب، از تگ‌های <details> با کلاس‌های رنگی کوئرا استفاده می‌شود:

• کلاس قرمز (class="red") — هشدارها، تله‌ها و توهم‌های هوش مصنوعی:

  <details class="red">
  <summary>**هشدار: [عنوان هشدار]**</summary>
  
  متن هشدار و راه‌های پیشگیری از خطا...
  
  </details>
  

• کلاس سبز (class="green") — نکات طلایی و شیوه‌های بهینه (Best Practices):

  <details class="green">
  <summary>**نکته: [عنوان نکته]**</summary>
  
  متن نکته و توصیهٔ کلیدی...
  
  </details>
  

• کلاس بنفش (class="violet") — مباحث عمیق‌تر و بیشتر بدانید:

  <details class="violet">
  <summary>**بیشتر بدانید: [مبحث تکمیلی]**</summary>
  
  توضیحات پیشرفته و لینک به مستندات رسمی...
  
  </details>
  

• کلاس آبی (class="blue") — یادداشت‌ها و پس‌زمینه‌ها.

۳.۴. بلوک‌های کد و هایلایت خطوط (<mark>)

بلوک‌های کد به صورت سه‌تکه تعریف می‌شوند:

```<زبان> <نام_فایل> <زبان>
def example():
    <mark class="green" title="توضیح هايلايت">کد مورد نظر برای جلب توجه</mark>
```

• رنگ‌های مجاز برای class: blue، green، violet، yellow، red.
• ویژگی title: توضیحی کوتاه که هنگام قرار گرفتن ماوس روی خط هایلایت‌شده ظاهر می‌شود.
• الزام حتمی: بلافاصله زیر هر بلوک کد، یک پاراگراف نقل‌قول (> ...) قرار می‌گیرد که کدها را به زبان ساده تشریح می‌کند.

---

۵. راهنمای تولید و استایل دیاگرام‌ها (Visuals & SVG Styleguide)

نمودارها و دیاگرام‌های درس‌نامه باید از نظر بصری فوق‌العاده باکیفیت و حرفه‌ای باشند (مانند خروجی پکیج diagrams یا فایل‌های SVG اختصاصی دوره FastAPI):

1. ابعاد و ساختار پایه SVG:
   • عرض ثابت: width="1100" و viewBox="0 0 1100 <height>" (ارتفاع معمولاً بین 360 تا 690 بسته به محتوا).
   • پس‌زمینهٔ گرادیان تیرهٔ مدرن: از #0B1220 به #111B2E با گوشه‌های گرد (rx="20").
   • فونت متن‌ها: Segoe UI, Vazirmatn, system-ui, -apple-system, sans-serif.
2. پالت رنگی المان‌ها:
   • رنگ‌های برجسته: آبی فیروزه‌ای (#00BDF0)، بنفش (#8B5CF6)، سبز زمردی (#10B981)، زرد/نارنجی (#F59E0B)، قرمز هشداری (#EF4444).
   • رنگ متون: سفید خالص (#FFFFFF) برای تیترها، خاکستری روشن (#C7D2E1 یا #E2E8F0) برای برچسب‌ها، خاکستری خنثی (#8CA0B8) برای توضیحات فرعی.
3. واترمارک لوگوی کوئرا:
   • در گوشهٔ پایین سمت راست تمام نمودارها، لوگوی وکتور کوئرا قرار می‌گیرد:

   <g transform="translate(880 378) scale(0.14)" opacity="0.92" fill="#FFFFFF">
     <!-- مسیر وکتور لوگوی کوئرا -->
   </g>
   

---

۶. نگارش فارسی و قواعد زبانی (Persian Typography)

• اصطلاحات فنی دو زبانه: در اولین مواجهه، واژهٔ فارسی پررنگ و انگلیسی ایتالیک داخل پرانتز می‌آید:
  **تست خودکار (*Automated Testing*)** | **مهندسی پرامپت (*Prompt Engineering*)**
• رعایت دقیق نیم‌فاصله‌ها: در تمام افعال استمراری («می‌شود»، «می‌دانیم»)، جمع‌ها («درس‌نامه‌ها»، «ایجنت‌ها»)، پسوندهای تفضیلی («سریع‌تر»، «مهم‌ترین») و کلمات ترکیبی («تست‌کیس»، «دست‌نخورده»، «کلمه‌به‌کلمه»).
• گیومه‌های فارسی: استفاده از « » برای نقل‌قول‌ها و مفاهیم خاص به جای " ".
• لحن: دوستانه، اول‌شخص جمع («می‌بینیم»، «می‌سازیم»)، آموزنده و گام‌به‌گام؛ متناسب با کسی که کدنویس حرفه‌ای نیست اما قصد ساخت یک محصول کامل را دارد.

---

۷. چک‌لیست نهایی ایجنت نویسنده (Quality Gate)

قبل از پایان نگارش درس‌نامه، بررسی کنید:

• آیا تمام موارد In-Scope از spec.md پوشش داده شده و هیچ مبحث Out-of-Scope مطرح نشده است؟
• آیا کاور (images/cover.png) و تمام دیاگرام‌های Placeholder در پوشهٔ images/ قرار گرفته‌اند؟
• آیا تصاویر در جدول‌های مارک‌داون تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج شده‌اند؟
• آیا حداقل دو باکس <details class="..."> (یکی هشدار red و یکی نکته green) در متن وجود دارد؟
• آیا بلوک‌های کد دارای <mark> و توضیح تحلیلی در باکس نقل‌قول (> ...) هستند؟
• آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟
• آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟
• آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟