diff --git a/.agents/rules/quera-styleguide.md b/.agents/rules/quera-styleguide.md index 44f6361..ef6d16c 100644 --- a/.agents/rules/quera-styleguide.md +++ b/.agents/rules/quera-styleguide.md @@ -19,14 +19,22 @@ هر درس‌نامه متنی باید ساختار زیر را رعایت کند: 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 + | ![عنوان تصویر](./images/diagram.png) | + | :-: | + | توضیح تفصیلی و آموزنده زیر تصویر. | + ``` +4. **جعبه‌های راهنما و هشدار (Quera Collapsible Details):** + * `
` با `**هشدار: ...**` برای تله‌ها و خطاهای رایج هوش مصنوعی + * `
` با `**نکته: ...**` برای نکات کلیدی و Best Practiceها + * `
` با `**بیشتر بدانید: ...**` برای مباحث عمیق‌تر +5. **بلوک‌های کد و هایلایت خطوط (``):** + * استفاده از `` روی خطوط کلیدی + * درج بلافاصلهٔ پاراگراف نقل‌قول (`> ...`) زیر هر بلوک کد برای تشریح خط‌به‌خط +6. **جمع‌بندی و گام بعدی (Summary & Bridge):** خلاصه در ۳-۴ بالت پوینت کوتاه به همراه پیش‌نمایش و پل ارتباطی به درس بعدی. --- diff --git a/.agents/rules/sdd-workflow.md b/.agents/rules/sdd-workflow.md index 16a6710..6dd83bc 100644 --- a/.agents/rules/sdd-workflow.md +++ b/.agents/rules/sdd-workflow.md @@ -31,7 +31,7 @@ هر درس‌نامه یا تمرین در پوشهٔ اختصاصی خود در ساختار زیر قرار می‌گیرد: - **درس‌نامه:** `chapters/ch-/-/` - `spec.md` (مشخصات و اهداف یادگیری) - - `lesson.md` (متن نهایی درس‌نامه کوئرا) + - `README.md` (متن نهایی درس‌نامه کوئرا کالج) - **تمرین داوری:** `chapters/ch-/-/` - `spec.md` (مشخصات ورودی/خروجی، سناریو، سنجه‌های داوری) - `problem.md` (صورت مسئله برای دانشجو) diff --git a/.agents/skills/course-sdd-planner/SKILL.md b/.agents/skills/course-sdd-planner/SKILL.md index f49ab67..2672c91 100644 --- a/.agents/skills/course-sdd-planner/SKILL.md +++ b/.agents/skills/course-sdd-planner/SKILL.md @@ -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` — **موضوع:** [شرح مختصر از مفهوم یا مقایسه بصری] --- diff --git a/.agents/skills/quera-lesson-author/SKILL.md b/.agents/skills/quera-lesson-author/SKILL.md index 79883df..56e2ffe 100644 --- a/.agents/skills/quera-lesson-author/SKILL.md +++ b/.agents/skills/quera-lesson-author/SKILL.md @@ -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-/-/ +├── 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):** + * جعبه‌های هشدار، نکته و بیشتر بدانید را با تگ‌های `
` پیاده کنید. + * خطوط مهم کد را با تگ‌های `` هایلایت نمایید. + * تصاویر را در جدول‌های تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج کنید. + +5. **بازبینی نهایی و انطباق با معیارهای پذیرش (Acceptance Checklist).** --- -## [عنوان بخش سوم: خطرات و توهم‌های رایج هوش مصنوعی] +## ۳. ساختار و کالبدشکافی استاندارد درس‌نامه (`README.md`) -> [!WARNING] -> **مراقب این تله باشید:** -> [توضیح خطایی که ایجنت‌ها ممکن است در این مرحله مرتکب شوند و نحوه هدایت مجدد آن‌ها] +متن نهایی درس‌نامه باید از این قالب دقیق پیروی کند: ---- +````markdown +# [عنوان درس‌نامه به فارسی روان] + +[مقدمه و قلاب داستانی (Hook): یک موقعیت ملموس، سناریوی واقعی محصولی یا پرسش کلیدی که انگیزهٔ مطالعه را در دانشجو ایجاد می‌کند. مثلاً: «فرض کنید تغییر کوچکی روی یک اندپوینت پرداخت اعمال کرده‌ایم و می‌خواهیم همان امروز آن را دیپلوی کنیم...»] + +| ![کاور درس‌نامهٔ [عنوان]](./images/cover.png) | +| :-: | + +[نقشهٔ راه درس‌نامه (Overview): توضیح کوتاه ۲ تا ۳ جمله‌ای از اینکه در این درس قرار است چه مراحلی طی شود، چه ابزارهایی بررسی می‌شوند و در پایان دانشجو به چه خروجی ملموسی می‌رسد.] + +## [عنوان بخش اول: مفهوم پایه یا چرایی موضوع] + +[توضیح عمیق و شفاف مفهوم همراه با استعاره‌های ملموس و مقایسه‌های روزمره] + +| ![عنوان یا توضیح کوتاه نمودار](./images/concept-diagram.png) | +| :-: | +| [توضیح تفصیلی، آموزنده و چندخطی زیر نمودار که پیام کلیدی و ارتباط اجزا را بیان می‌کند.] | + +[ادامهٔ شرح درس...] + +
+**هشدار: [عنوان هشدار درباره خطای رایج، تله یا توهم هوش مصنوعی]** + +[شرح خطای رایج یا توهم ایجنت و نحوهٔ پیشگیری و مهار آن. توضیح اینکه چرا این خطا رخ می‌دهد و چطور باید رفتار صحیح را ارزیابی کرد.] + +
+ +## [عنوان بخش دوم: پیاده‌سازی عملی، ابزارها یا کُد] + +[توضیح شیوهٔ استفاده از ابزار یا پیاده‌سازی گام‌به‌گام] + +```python app.py python +from fastapi import FastAPI + +app = FastAPI() + +@app.get("/") +def read_root(): + return {"service": "online", "status": "ok"} +``` + +> [باکس نقل‌قول بلافاصله پس از بلوک کد: تشریح خط‌به‌خط و دقیق کدهای بالا، کارکرد هر تابع، متغیرها و رفتاری که خروجی تولید می‌کند. هرگز کد بدون توضیح رها نمی‌شود.] + +
+**نکته: [قانون طلایی یا بهترین الگو (Best Practice)]** + +[توضیح ترفند یا الگوی حرفه‌ای که کارایی را بالا می‌برد یا از اتلاف وقت دانشجو جلوگیری می‌کند.] + +
+ +## [عنوان بخش سوم: مقایسه، سناریوهای خطا یا حالت‌های پیشرفته] + +[بررسی حالت‌های خطا، تست یا مقایسهٔ گزینه‌های مختلف] + +| معیار | روش الف | روش ب | +| :-: | :-: | :-: | +| سرعت اجرا | سریع | کند | +| انعطاف‌پذیری | بالا | محدود | +| هزینه | کم | بالا | + +
+**بیشتر بدانید: [مبحث تکمیلی و معماری عمیق‌تر]** + +[مطالعهٔ عمیق‌تر برای دانشجویانی که می‌خواهند از پشت‌صحنه یا تاریخچه و معماری مطلع شوند.] + +
## جمع‌بندی و گام بعدی @@ -69,5 +136,110 @@ flowchart LR - **نکته ۲:** [خلاصه نکته کلیدی] - **نکته ۳:** [خلاصه نکته کلیدی] -> در درس بعدی به سراغ **[عنوان درس بعد]** می‌رویم تا یاد بگیریم چگونه ... +[پل ارتباطی به درس بعد]: در درس‌نامهٔ بعدی به سراغ **«[عنوان درس بعد]»** می‌رویم تا یاد بگیریم چطور ... +```` + +--- + +## ۴. اجزای خاص رابط کاربری و فرمت‌بندی کوئرا کالج (Quera Custom UI) + +### ۱.۴. جدول نمایش تصاویر و دیاگرام‌ها (Centered Image Tables) +در کوئرا کالج، تصاویر مستقیماً رها نمی‌شوند؛ بلکه همیشه درون یک جدول مارک‌داون تک‌خانه‌ای وسط‌چین با کپشن توضیحی قرار می‌گیرند: + +```markdown +| ![متن جایگزین کوتاه](./images/filename.png) | +| :-: | +| متن توضیح تفصیلی و آموزنده زیر تصویر که پیام نمودار را تشریح می‌کند. | ``` + +### ۲.۴. جعبه‌های پیام و آکاردئون‌های رنگی (`
`) +به جای الرت‌های مرسوم گیت‌هاب، از تگ‌های `
` با کلاس‌های رنگی کوئرا استفاده می‌شود: + +* **کلاس قرمز (`class="red"`) — هشدارها، تله‌ها و توهم‌های هوش مصنوعی:** + ```html +
+ **هشدار: [عنوان هشدار]** + + متن هشدار و راه‌های پیشگیری از خطا... + +
+ ``` + +* **کلاس سبز (`class="green"`) — نکات طلایی و شیوه‌های بهینه (Best Practices):** + ```html +
+ **نکته: [عنوان نکته]** + + متن نکته و توصیهٔ کلیدی... + +
+ ``` + +* **کلاس بنفش (`class="violet"`) — مباحث عمیق‌تر و بیشتر بدانید:** + ```html +
+ **بیشتر بدانید: [مبحث تکمیلی]** + + توضیحات پیشرفته و لینک به مستندات رسمی... + +
+ ``` + +* **کلاس آبی (`class="blue"`) — یادداشت‌ها و پس‌زمینه‌ها.** + +### ۳.۴. بلوک‌های کد و هایلایت خطوط (``) +بلوک‌های کد به صورت سه‌تکه تعریف می‌شوند: +````markdown +```<زبان> <نام_فایل> <زبان> +def example(): + کد مورد نظر برای جلب توجه +``` +```` +* رنگ‌های مجاز برای `class`: `blue`، `green`، `violet`، `yellow`، `red`. +* ویژگی `title`: توضیحی کوتاه که هنگام قرار گرفتن ماوس روی خط هایلایت‌شده ظاهر می‌شود. +* **الزام حتمی:** بلافاصله زیر هر بلوک کد، یک پاراگراف نقل‌قول (`> ...`) قرار می‌گیرد که کدها را به زبان ساده تشریح می‌کند. + +--- + +## ۵. راهنمای تولید و استایل دیاگرام‌ها (Visuals & SVG Styleguide) + +نمودارها و دیاگرام‌های درس‌نامه باید از نظر بصری فوق‌العاده باکیفیت و حرفه‌ای باشند (مانند خروجی پکیج `diagrams` یا فایل‌های SVG اختصاصی دوره FastAPI): + +1. **ابعاد و ساختار پایه SVG:** + * عرض ثابت: `width="1100"` و `viewBox="0 0 1100 "` (ارتفاع معمولاً بین `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 + + + + ``` + +--- + +## ۶. نگارش فارسی و قواعد زبانی (Persian Typography) + +* **اصطلاحات فنی دو زبانه:** در اولین مواجهه، واژهٔ فارسی پررنگ و انگلیسی ایتالیک داخل پرانتز می‌آید: + `**تست خودکار (*Automated Testing*)**` | `**مهندسی پرامپت (*Prompt Engineering*)**` +* **رعایت دقیق نیم‌فاصله‌ها:** در تمام افعال استمراری («می‌شود»، «می‌دانیم»)، جمع‌ها («درس‌نامه‌ها»، «ایجنت‌ها»)، پسوندهای تفضیلی («سریع‌تر»، «مهم‌ترین») و کلمات ترکیبی («تست‌کیس»، «دست‌نخورده»، «کلمه‌به‌کلمه»). +* **گیومه‌های فارسی:** استفاده از « » برای نقل‌قول‌ها و مفاهیم خاص به جای " ". +* **لحن:** دوستانه، اول‌شخص جمع («می‌بینیم»، «می‌سازیم»)، آموزنده و گام‌به‌گام؛ متناسب با کسی که کدنویس حرفه‌ای نیست اما قصد ساخت یک محصول کامل را دارد. + +--- + +## ۷. چک‌لیست نهایی ایجنت نویسنده (Quality Gate) + +قبل از پایان نگارش درس‌نامه، بررسی کنید: +- [ ] آیا تمام موارد **In-Scope** از `spec.md` پوشش داده شده و هیچ مبحث **Out-of-Scope** مطرح نشده است؟ +- [ ] آیا کاور (`images/cover.png`) و تمام دیاگرام‌های Placeholder در پوشهٔ `images/` قرار گرفته‌اند؟ +- [ ] آیا تصاویر در جدول‌های مارک‌داون تک‌خانه‌ای وسط‌چین همراه با کپشن تفصیلی درج شده‌اند؟ +- [ ] آیا حداقل دو باکس `
` (یکی هشدار `red` و یکی نکته `green`) در متن وجود دارد؟ +- [ ] آیا بلوک‌های کد دارای `` و توضیح تحلیلی در باکس نقل‌قول (`> ...`) هستند؟ +- [ ] آیا اصطلاحات انگلیسی به همراه معادل فارسی مصوب آورده شده‌اند؟ +- [ ] آیا نیم‌فاصله‌ها و گیومه‌های فارسی به طور کامل رعایت شده‌اند؟ +- [ ] آیا در پایان درس، خلاصهٔ نکات و پیش‌نمایش درس بعدی درج شده است؟