feat: add chapter 03-workspace-setup specs

chapters/03-workspace-setup/03-lesson-terminal-agents/spec.md

@@ -0,0 +1,106 @@
+# مشخصات درس‌نامه: ابزارهای خط فرمان و ایجنت‌های ترمینال (Terminal Agents: Claude Code & Codex CLI)
+- **شناسه در سیلابس:** `L3.4`
+- **فصل:** فصل ۳: راه‌اندازی محیط کار (Ch 3)
+- **نوع محتوا:** 📘 درس‌نامه متنی
+- **زمان تقریبی مطالعه:** ۱۵ دقیقه
+- **پیش‌نیازهای مستقیم:** `L3.3` (ابزارهای دسکتاپ)
+
+---
+
+## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
+دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
+- [ ] **درک کند (Understand):** ایجنت‌های خط فرمان (CLI Agents) نظیر Claude Code و Codex CLI چگونه با دسترسی مستقیم به شل، فایل‌ها و دستورات سیستمی، کارهای فراتر از ادیتور معمولی انجام می‌دهند.
+- [ ] **به‌کار ببندد (Apply):** ابزار Claude Code را با استفاده از npm روی سیستم‌عامل خود (ویندوز، مک یا لینوکس) با راهنماهای کشویی مجزا نصب کند.
+- [ ] **به‌کار ببندد (Apply):** فرایند احراز هویت اولیه و اجرای نخستین فرمان در محیط ترمینال را با موفقیت پشت سر بگذارد.
+- [ ] **تحلیل/ارزیابی کند (Evaluate):** خطرات و مرزهای امنیتی اجرای دستورات شل توسط هوش مصنوعی را بشناسد و فرآیند تایید انسانی (Approval Prompts) را مدیریت کند.
+- [ ] **به‌کار ببندد (Apply):** دستورات کلیدی کنترل سشن ترمینال (توقف اضطراری با `Ctrl+C`، فشرده‌سازی بافت چت با `/compact` و خروج با `/exit`) را به کار گیرد.
+
+---
+
+## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
+
+### آنچه باید پوشش داده شود (In-Scope):
+1. **چرایی قدرت خارق‌العاده ایجنت‌های ترمینال:**
+   * ایجنت ترمینال تنها یک پیشنهاددهنده کد نیست؛ خودش می‌تواند تست‌ها را اجرا کند، خطاهای خروجی را بخواند، پکیج‌های گم‌شده را نصب نماید و تغییرات را مستقیماً کامیت کند.
+2. **معرفی دو غول اصلی حوزه ایجنت‌های خط فرمان:**
+   * **Claude Code (ساخت شرکت Anthropic):** ایجنت پیشرو مبتنی بر مدل‌های قدرتمند خانواده Claude با درک عمیق از کل ساختار پروژه.
+   * **Codex CLI / GitHub Copilot CLI:** ابزارهای تعاملی خط فرمان برای تولید و اجرای دستورات ترمینال به زبان طبیعی.
+   * اشاره کوتاه به سایر ابزارهای متن‌باز این حوزه مانند Aider و OpenCode.
+3. **مراحل گام‌به‌گام نصب Claude Code در سراسر سیستم‌عامل‌ها (در قالب منوهای کشویی جداگانه):**
+   * `<details><summary>راهنمای نصب و اجرا در ویندوز (Windows PowerShell / Terminal)</summary> ... </details>`:  
+     دستور `npm install -g @anthropic-ai/claude-code` و نحوه حل هشدارهای احتمالی مسیر (Path).
+   * `<details><summary>راهنمای نصب و اجرا در مک‌اواس (macOS Terminal / iTerm2)</summary> ... </details>`:  
+     دستور نصب npm و تنظیم پرمیژن‌های احتمالی.
+   * `<details><summary>راهنمای نصب و اجرا در لینوکس (Linux Bash / Zsh)</summary> ... </details>`:  
+     دستور نصب سراسری و مجوزهای کاربری بدون نیاز به sudo بی‌مورد.
+4. **احراز هویت و اولین ورود (Authentication & First Run):**
+   * تایپ دستور `claude` در ترمینال.
+   * ورود به حساب Anthropic و تایید توکن دسترسی.
+5. **جریان کاری استاندارد یک ایجنت ترمینال (The CLI Loop):**
+   * کاربر مسئله را می‌گوید $\rightarrow$ ایجنت فایل‌ها را بررسی می‌کند $\rightarrow$ پیشنهاد ادیت می‌دهد $\rightarrow$ کاربر تایید می‌کند $\rightarrow$ ایجنت تست یا بیلد را اجرا می‌کند.
+6. **امنیت در خط فرمان و کنترل کاربر:**
+   * چرا هوش مصنوعی برای اجرای دستورات شل (مانند حذف، جابجایی یا نصب) از شما اجازه (Prompt Approval) می‌خواهد؟
+   * پرهیز جدی از فلگ‌های خودکارساز خطرناک مانند رد کردن تایید دستورات، به ویژه در کارهای پرخطر.
+7. **کال‌اوت‌های Quera:**
+   * `<details class="red">`: هشدار بسیار جدی: خطرات دستورات تخریبی در شل (`rm -rf` یا پاک کردن فایل‌ها) و الزام بررسی دستور پیش از فشردن Enter.
+   * `<details class="violet">`: کلیدهای کنترل و نجات در ترمینال (`Ctrl+C` برای توقف آنی هوش مصنوعی و دستور `/compact` برای سبک‌سازی حافظه سشن).
+
+### آنچه نباید وارد آن شویم (Out-of-Scope):
+- توسعه اسکریپت‌های پیچیده بش یا اتوماسیون CI/CD با خط فرمان (مربوط به فصول انتهایی).
+- بررسی تئوریک مدل‌های زبانی (که در فصل ۲ تدریس شده است).
+
+---
+
+## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
+
+| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
+| :--- | :--- | :--- |
+| CLI Agent | ایجنت خط فرمان | هوش مصنوعی که در محیط ترمینال اجرا شده و توانایی ویرایش فایل و اجرای دستورات سیستمی را دارد |
+| Claude Code | کلود کد | ابزار خط فرمان رسمی آنتروپیک برای هدایت هوشمند کارهای توسعه در سطح کل ریپازیتوری |
+| Command Execution Loop | چرخه اجرای دستورات | فرایند پیوسته خواندن، ویرایش، اجرا در ترمینال و ارزیابی نتیجه توسط ایجنت |
+| Approval Prompt | تاییدیه اجرای دستور | سوال امنیتی ایجنت از کاربر پیش از اعمال تغییرات حساس یا اجرای دستورات شل |
+| Compact Command | دستور فشرده‌سازی سشن | دستوری مانند `/compact` در ایجنت‌های ترمینال برای خلاصه کردن تاریخچه و باز کردن فضا در پنجره بافت |
+
+---
+
+## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
+> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` قرار گرفته و در قالب جدول تک‌خانه‌ای وسط‌چین با کپشن تفصیلی درج شوند:
+
+1. **تصویر کاور درس:** `images/cover.png`
+   * **موضوع:** کاور مدرن نمایش‌دهنده پنجره سیاه ترمینال با تایپوگرافی سبز/نئونی و لوگوی Claude Code در حال اجرای خودکار وظایف سیستمی.
+2. **چرخه کاری ایجنت در ترمینال:** `images/terminal-agent-loop.png`
+   * **موضوع:** اینفوگرافیک گام‌به‌گام: دریافت پرامپت $\rightarrow$ خواندن کدبیس $\rightarrow$ ایجاد تغییرات $\rightarrow$ اجرای کامند در ترمینال $\rightarrow$ بررسی خروجی $\rightarrow$ گزارش به کاربر.
+3. **اجرای واقعی Claude Code در ترمینال:** `images/claude-code-demo.png`
+   * **موضوع:** اسکرین‌شات تمیز از محیط واقعی اجرای Claude Code، شامل درخواست بررسی یک خطا و پاسخ با جزئیات رنگی.
+4. **مرزهای امنیتی و پنل تایید کاربر:** `images/cli-safety-approval.png`
+   * **موضوع:** تصویر درخواست تایید ایجنت برای اجرای یک دستور شل به همراه دکمه‌های تایید (Yes) یا رد (No) توسط توسعه‌دهنده.
+
+---
+
+## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
+
+1. **تیتر اصلی:** `# ابزارهای خط فرمان: قدرت خارق‌العاده ایجنت‌های ترمینال`
+2. **مقدمه ملموس:** چرا ترمینال میدان اصلی بازی برای توسعه‌دهندگان قدرتمند هوش مصنوعی است؟
+3. **جدول کاور درس**
+4. **تفاوت ایجنت ترمینال با ادیتور گرافیکی:** استقلال عمل، اجرای دستورات و دیباگ خودکار.
+5. **معرفی Claude Code و Codex CLI:** پرچم‌داران دستیاران ترمینالی در جهان.
+6. **نصب گام‌به‌گام ابزارها با منوهای کشویی سیستم‌عامل‌ها:**
+   * منوی کشویی ویندوز (PowerShell).
+   * منوی کشویی مک‌اواس (Terminal / Zsh).
+   * منوی کشویی لینوکس (Bash).
+7. **احراز هویت و نخستین مکالمه در ترمینال:** راه‌اندازی سشن اول با دستور `claude`.
+8. **باکس هشدار امنیتی Quera (`<details class="red">`):** مراقبت در تایید دستورات ترمینال و پرهیز از دستورات مخرب.
+9. **کلیدهای طلایی کنترل سشن در خط فرمان:**
+   * توقف فوری با `Ctrl+C`.
+   * سبک‌سازی بافت با `/compact`.
+   * خروج تمیز با `/exit`.
+10. **باکس نکته پیشرفته Quera (`<details class="violet">`):** چه زمان از Cursor استفاده کنیم و چه زمان به ترمینال برویم؟
+11. **جمع‌بندی درس‌نامه:** تسلط بر دو بال اصلی محیط کار: ادیتور محلی و ایجنت خط فرمان.
+
+---
+
+## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
+- [ ] مراحل نصب با `npm` و دستورات بررسی برای ویندوز، مک و لینوکس در منوهای کشویی مجزا درج شده باشد.
+- [ ] مفهوم ایجنت ترمینال و تفاوت آن با چت‌بات‌های متنی به روشنی تفهیم شده باشد.
+- [ ] جنبه‌های امنیتی تایید دستورات شل و هشدارهای مربوط به خطرات فایل‌های حساس مورد تاکید قرار گیرد.
+- [ ] دستورات میانبر و کنترلی (`Ctrl+C`، `/compact`) به درستی آموزش داده شوند.