feat: update general skills/rules to adapt example course styles
This commit is contained in:
@@ -49,9 +49,11 @@ description: >-
|
||||
|
||||
---
|
||||
|
||||
## ۴. استعاره‌ها، سناریوهای ملموس و دیاگرام‌ها (Pedagogy & Visuals)
|
||||
- **داستان/استعاره ملموس:** [تشبیه موضوع به یک کار روزمره برای درک بدون پیش‌نیاز فنی]
|
||||
- **دیاگرام پیشنهادی (Mermaid):** [شرح فلوچارت یا نمودار مورد نیاز]
|
||||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||||
> **نکته:** در تدوین مشخصات، نیازی به طراحی پرامپت تصویر یا کد دیاگرام نیست. صرفاً مکان، نام فایل پیشنهادی و شرح کوتاهی از آنچه باید به تصویر کشیده شود مشخص می‌گردد تا ایجنت نویسنده با ابزارهای خود (پکیج diagrams یا قالب SVG) آن را بسازد.
|
||||
- **تصویر کاور:** `images/cover.png` — [شرح مختصر ایده بصری کاور درس‌نامه]
|
||||
- **نمودار ۱:** `images/[diagram-slug-1].png` — **موضوع:** [شرح مختصر از مفهوم، چرخه، معماری یا فرآیندی که باید ترسیم شود]
|
||||
- **نمودار ۲:** `images/[diagram-slug-2].png` — **موضوع:** [شرح مختصر از مفهوم یا مقایسه بصری]
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,66 +1,133 @@
|
||||
---
|
||||
name: quera-lesson-author
|
||||
description: >-
|
||||
Use this skill when drafting or refining full document-based lessons (lesson.md)
|
||||
from an approved spec.md file, following Quera College pedagogical and formatting rules.
|
||||
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`) به متن نهایی و جذاب درس‌نامه (`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/ # پوشهٔ اختصاصی تصاویر، نمودارها و دیاگرام‌های درس
|
||||
├── cover.png # تصویر کاور استاندارد درس‌نامه (یا cover.svg)
|
||||
├── [diagram-1].png / .svg
|
||||
└── [diagram-2].png / .svg
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> [نکته تکمیلی درباره عملکرد هوش مصنوعی یا پیش‌زمینه مورد نیاز]
|
||||
> **نکتهٔ نام‌گذاری فایل:** فایل اصلی درس‌نامه در کوئرا کالج نامش `README.md` است (نه `lesson.md`).
|
||||
|
||||
---
|
||||
|
||||
## [عنوان بخش دوم: پیاده‌سازی عملی و کار با ابزار]
|
||||
## ۲. گردش‌کار نگارش درس‌نامه (Author Agent Workflow)
|
||||
|
||||
[گام‌های عملی استفاده از ادیتور/ابزار به همراه تصویرسازی ذهنی]
|
||||
ایجنت نویسنده باید این ۵ گام را به ترتیب طی کند:
|
||||
|
||||
> [!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. **نگارش متن درس بر اساس کالبدشکافی کوئرا:**
|
||||
* ساختار استاندارد بخش‌ها (قلاب داستانی، نقشه درس، مفاهیم اصلی، جعبه‌های کال‌اوت، کدهای هایلایت‌شده و جمع‌بندی) را پیاده کنید.
|
||||
|
||||
4. **اعمال استانداردهای فرانت‌اند کوئرا (HTML & CSS Components):**
|
||||
* جعبه‌های هشدار، نکته و بیشتر بدانید را با تگ‌های `<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="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>` و توضیح تحلیلی در باکس نقل‌قول (`> ...`) هستند؟
|
||||
- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟
|
||||
- [ ] آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟
|
||||
- [ ] آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟
|
||||
|
||||
Reference in New Issue
Block a user