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