1.**مقدمه و قلاب (Hook):** یک موقعیت واقعی، مسئله یا چالش روزمره که ضرورت این موضوع را نشان می‌دهد.
2.**شرح مفهوم به زبان ساده (Core Concept):** توضیح اصل موضوع بدون پرداختن به جزییات زائد. استفاده از استعاره‌ها و نمودارهای بصری (Mermaid).
3.**جعبه‌های راهنما و هشدار (Admonitions):**
-`> [!NOTE]` برای نکات تکمیلی و پس‌زمینه
-`> [!TIP]` برای ترفندها و پرامپت‌های طلایی
-`> [!IMPORTANT]` برای ملزومات کلیدی
-`> [!WARNING]` برای اشتباهات رایج و توهم‌های هوش مصنوعی (AI Hallucinations)
4.**جعبه پرامپت نمونه (Ready-to-Use Prompt):** پرامپت‌های کپی-پیست آماده برای ادیتورهایی مثل Cursor/Claude Code.
5.**جمع‌بندی و گام بعدی (Summary & Action Item):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش درس بعدی.
2.**شرح مفهوم به زبان ساده (Core Concept):** توضیح اصل موضوع بدون پرداختن به جزییات زائد، همراه با نمودارها و دیاگرام‌های باکیفیت برداری (SVG / پکیج diagrams).
3.**نمایش تصاویر و دیاگرام‌ها (Centered Image Tables):**
*قرارگیری تصویر در جدول تک‌خانه‌ای وسط‌چین مارک‌داون:
```markdown
|  |
| :-: |
| توضیح تفصیلی و آموزنده زیر تصویر. |
```
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):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش و پل ارتباطی به درس بعدی.
## ۴. استعاره‌ها، سناریوهای ملموس و دیاگرام‌ها (Pedagogy & Visuals)
- **داستان/استعاره ملموس:** [تشبیه موضوع به یک کار روزمره برای درک بدون پیش‌نیاز فنی]
- **دیاگرام پیشنهادی (Mermaid):** [شرح فلوچارت یا نمودار مورد نیاز]
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **نکته:** در تدوین مشخصات، نیازی به طراحی پرامپت تصویر یا کد دیاگرام نیست. صرفاً مکان، نام فایل پیشنهادی و شرح کوتاهی از آنچه باید به تصویر کشیده شود مشخص می‌گردد تا ایجنت نویسنده با ابزارهای خود (پکیج diagrams یا قالب SVG) آن را بسازد.
این مهارت راهنمای تبدیل یک سند مشخصات تایید شده (`spec.md`) به متن نهایی و جذاب درس‌نامه (`lesson.md`) است.
این مهارت راهنمای جامع و استاندارد برای ایجنت‌های نویسنده است تا بتوانند یک سند مشخصات تایید شده (`spec.md`) را به یک درس‌نامهٔ کامل، جذاب، استاندارد و آمادهٔ انتشار در کوئرا کالج (`README.md`) تبدیل کنند.
الگو، ساختار و لحن این راهنما دقیقاً بر اساس استانداردهای پیاده‌سازی‌شده در **دورهٔ FastAPI کوئرا کالج** تدوین شده است.
---
## چک‌لیست قبل از نگارش
1. آیا فایل `spec.md` در پوشهٔ درس وجود دارد و اهداف آن مشخص است؟
2. آیا شیوه‌نامه نگارش فارسی کوئرا (`.agents/rules/quera-styleguide.md`) بررسی شده است؟
## ۱. ساختار پوشه‌بندی هر درس‌نامه
---
هر درس‌نامه در پوشهٔ اختصاصی خود درون فصل مربوطه قرار دارد و باید شامل فایل متن درس‌نامه و پوشهٔ تصاویر اختصاصی باشد:
## ساختار نگارشی درس‌نامه (`lesson.md`)
```markdown
# [عنوان درس‌نامه]
[مقدمه جذاب و قلاب داستانی: چرا این موضوع برای کسی که می‌خواهد با هوش مصنوعی محصول بسازد حیاتی است؟]
---
## [عنوان بخش اول: مفهوم اصلی به زبان ساده]
[توضیح شفاف همراه با استعاره‌های روزمره و مقایسه‌های ملموس]
```mermaid
flowchart LR
A[ایده اولیه] --> B[پرامپت ساختاریافته]
B --> C[کد تولید شده با AI]
C --> D[بررسی و تست خروجی]
```text
chapters/ch<XX>-<name>/<YY>-<lesson-slug>/
├── spec.md # سند مشخصات و قرارداد یادگیری درس (ورودی ایجنت)
├── README.md # متن کامل درس‌نامه کوئرا کالج (خروجی نهایی ایجنت)
└── images/ # پوشهٔ اختصاصی تصاویر، نمودارها و دیاگرام‌های درس
[گام‌های عملی استفاده از ادیتور/ابزار به همراه تصویرسازی ذهنی]
ایجنت نویسنده باید این ۵ گام را به ترتیب طی کند:
> [!TIP]
> **پرامپت پیشنهادی برای ادیتور:**
> ```text
> [متن دقیق و تمیز پرامپت آماده استفاده]
> ```
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.**نگارش متن درس بر اساس کالبدشکافی کوئرا:**
* ساختار استاندارد بخش‌ها (قلاب داستانی، نقشه درس، مفاهیم اصلی، جعبه‌های کال‌اوت، کدهای هایلایت‌شده و جمع‌بندی) را پیاده کنید.
* جعبه‌های هشدار، نکته و بیشتر بدانید را با تگ‌های `<details class="...">` پیاده کنید.
* خطوط مهم کد را با تگ‌های `<mark class="...">` هایلایت نمایید.
* تصاویر را در جدول‌های تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج کنید.
5.**بازبینی نهایی و انطباق با معیارهای پذیرش (Acceptance Checklist).**
---
## [عنوان بخش سوم: خطرات و توهم‌های رایج هوش مصنوعی]
## ۳. ساختار و کالبدشکافی استاندارد درس‌نامه (`README.md`)
> [!WARNING]
> **مراقب این تله باشید:**
> [توضیح خطایی که ایجنت‌ها ممکن است در این مرحله مرتکب شوند و نحوه هدایت مجدد آن‌ها]
متن نهایی درس‌نامه باید از این قالب دقیق پیروی کند:
---
````markdown
# [عنوان درس‌نامه به فارسی روان]
[مقدمه و قلاب داستانی (Hook): یک موقعیت ملموس، سناریوی واقعی محصولی یا پرسش کلیدی که انگیزهٔ مطالعه را در دانشجو ایجاد می‌کند. مثلاً: «فرض کنید تغییر کوچکی روی یک اندپوینت پرداخت اعمال کرده‌ایم و می‌خواهیم همان امروز آن را دیپلوی کنیم...»]
| ![کاور درس‌نامهٔ [عنوان]](./images/cover.png) |
| :-: |
[نقشهٔ راه درس‌نامه (Overview): توضیح کوتاه ۲ تا ۳ جمله‌ای از اینکه در این درس قرار است چه مراحلی طی شود، چه ابزارهایی بررسی می‌شوند و در پایان دانشجو به چه خروجی ملموسی می‌رسد.]
## [عنوان بخش اول: مفهوم پایه یا چرایی موضوع]
[توضیح عمیق و شفاف مفهوم همراه با استعاره‌های ملموس و مقایسه‌های روزمره]
|  |
| :-: |
| [توضیح تفصیلی، آموزنده و چندخطی زیر نمودار که پیام کلیدی و ارتباط اجزا را بیان می‌کند.] |
[ادامهٔ شرح درس...]
<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>
## جمع‌بندی و گام بعدی
@@ -69,5 +136,110 @@ flowchart LR
- **نکته ۲:** [خلاصه نکته کلیدی]
- **نکته ۳:** [خلاصه نکته کلیدی]
> در درس بعدی به سراغ **[عنوان درس بعد]** می‌رویم تا یاد بگیریم چگونه ...
[پل ارتباطی به درس بعد]: در درس‌نامهٔ بعدی به سراغ **«[عنوان درس بعد]»** می‌رویم تا یاد بگیریم چطور ...
````
---
## ۴. اجزای خاص رابط کاربری و فرمت‌بندی کوئرا کالج (Quera Custom UI)
### ۱.۴. جدول نمایش تصاویر و دیاگرام‌ها (Centered Image Tables)
در کوئرا کالج، تصاویر مستقیماً رها نمی‌شوند؛ بلکه همیشه درون یک جدول مارک‌داون تک‌خانه‌ای وسط‌چین با کپشن توضیحی قرار می‌گیرند:
```markdown
|  |
| :-: |
| متن توضیح تفصیلی و آموزنده زیر تصویر که پیام نمودار را تشریح می‌کند. |
```
### ۲.۴. جعبه‌های پیام و آکاردئون‌های رنگی (`<details class="...">`)
به جای الرت‌های مرسوم گیت‌هاب، از تگ‌های `<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"`).
* **رعایت دقیق نیم‌فاصله‌ها:** در تمام افعال استمراری («می‌شود»، «می‌دانیم»)، جمع‌ها («درس‌نامه‌ها»، «ایجنت‌ها»)، پسوندهای تفضیلی («سریع‌تر»، «مهم‌ترین») و کلمات ترکیبی («تست‌کیس»، «دست‌نخورده»، «کلمه‌به‌کلمه»).
* **گیومه‌های فارسی:** استفاده از « » برای نقل‌قول‌ها و مفاهیم خاص به جای " ".
* **لحن:** دوستانه، اول‌شخص جمع («می‌بینیم»، «می‌سازیم»)، آموزنده و گام‌به‌گام؛ متناسب با کسی که کدنویس حرفه‌ای نیست اما قصد ساخت یک محصول کامل را دارد.
---
## ۷. چک‌لیست نهایی ایجنت نویسنده (Quality Gate)
قبل از پایان نگارش درس‌نامه، بررسی کنید:
- [ ] آیا تمام موارد **In-Scope** از `spec.md` پوشش داده شده و هیچ مبحث **Out-of-Scope** مطرح نشده است؟
- [ ] آیا کاور (`images/cover.png`) و تمام دیاگرام‌های Placeholder در پوشهٔ `images/` قرار گرفته‌اند؟
- [ ] آیا تصاویر در جدول‌های مارک‌داون تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج شده‌اند؟
- [ ] آیا حداقل دو باکس `<details class="...">` (یکی هشدار `red` و یکی نکته `green`) در متن وجود دارد؟
- [ ] آیا بلوک‌های کد دارای `<mark>` و توضیح تحلیلی در باکس نقل‌قول (`> ...`) هستند؟
- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟
- [ ] آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟
- [ ] آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
