# مشخصات درس‌نامه: ابزارهای خط فرمان و ایجنت‌های ترمینال (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`) به درستی آموزش داده شوند.