---
name: quera-lesson-author
description: >-
  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 کوئرا کالج** تدوین شده است.

---

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

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

```text
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`)

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

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

[مقدمه و قلاب داستانی (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)
در کوئرا کالج، تصاویر مستقیماً رها نمی‌شوند؛ بلکه همیشه درون یک جدول مارک‌داون تک‌خانه‌ای وسط‌چین با کپشن توضیحی قرار می‌گیرند:

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

### ۲.۴. جعبه‌های پیام و آکاردئون‌های رنگی (`<details class="...">`)
به جای الرت‌های مرسوم گیت‌هاب، از تگ‌های `<details>` با کلاس‌های رنگی کوئرا استفاده می‌شود:

* **کلاس قرمز (`class="red"`) — هشدارها، تله‌ها و توهم‌های هوش مصنوعی:**
  ```html
  <details class="red">
  <summary>**هشدار: [عنوان هشدار]**</summary>

  متن هشدار و راه‌های پیشگیری از خطا...

  </details>
  ```

* **کلاس سبز (`class="green"`) — نکات طلایی و شیوه‌های بهینه (Best Practices):**
  ```html
  <details class="green">
  <summary>**نکته: [عنوان نکته]**</summary>

  متن نکته و توصیهٔ کلیدی...

  </details>
  ```

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

  توضیحات پیشرفته و لینک به مستندات رسمی...

  </details>
  ```

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

### ۳.۴. بلوک‌های کد و هایلایت خطوط (`<mark>`)
بلوک‌های کد به صورت سه‌تکه تعریف می‌شوند:
````markdown
```<زبان> <نام_فایل> <زبان>
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. **واترمارک لوگوی کوئرا:**
   * در گوشهٔ پایین سمت راست تمام نمودارها، لوگوی وکتور کوئرا قرار می‌گیرد:
   ```xml
   <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>` و توضیح تحلیلی در باکس نقل‌قول (`> ...`) هستند؟
- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟
- [ ] آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟
- [ ] آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟