vibe-coding-college-specs/chapters/03-workspace-setup/03-lesson-terminal-agents/spec.md

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