مروری بر Cursor و Agent AI

Overview

این جلسه به معرفی و کار عملی با Cursor (فورک VS Code) و برنامه‌نویسی Agentic AI می‌پردازد. تمرکز بر تاریخچه ابزارها، تفاوت LLM و Agent، مدیریت کانتکست، گردش‌کار مؤثر، و ساخت یک پروژه FastAPI با کمک Cursor است.

تاریخچه و مسیر تکامل ابزارهای کدنویسی با AI

• شروع با Auto-complete ساده در ادیتورها؛ ابزار اولیه: Kite (تا حدود 2021).
• GitHub Copilot قبل از جهش LLMها عرضه شد؛ بهبود نسبت به Kite ولی غیر-LLM.
• فراگیر شدن LLMها (ChatGPT، اواخر 2022) و تغییر تجربه کدنویسی.
• VS Code کند در ادغام LLM و Agentic AI؛ Cursor به‌عنوان فورک VS Code سریع و محبوب شد.
• Cursor با دیفالت‌های خوب، Agent داخلی و یکپارچگی مدل‌ها رشد سریعی در درآمد و پذیرش داشت.

تفاوت LLM و Agent و نقش ابزارها

• LLM: پاسخ به سوالات؛ اکشن روی فایل‌ها انجام نمی‌دهد؛ مشابه حالت Ask.
• Agent: LLM با Function Calling؛ می‌تواند فایل بسازد، ویرایش کند، جابجا کند.
• ابزارها با امضا (signature) تعریف می‌شوند؛ Agent تصمیم می‌گیرد کِی کدام را فراخوانی کند.
• جست‌وجوی وب و افزودن شواهد می‌تواند به‌صورت اکستنشن انجام شود.

ویژگی‌ها و محیط Cursor

• فورک VS Code؛ منحنی یادگیری جدید ندارد؛ همه تنظیمات VS Code قابل استفاده است.
• شورتکات‌ها:
  • Command+B: نمایش/پنهان‌سازی سایدبار
  • Command+J یا Control+`: ترمینال
  • Command+L: حالت Ask
  • Command+I: حالت Agent
  • تب‌ها مانند مرورگر؛ مدیریت هیستوری گفتگوها
• افزودن کانتکست:
  • افزودن فایل، بخش از فایل (line ranges) و خروجی ترمینال به کانتکست.
  • انتخاب مدل (Auto/Max/مدل‌های خاص)؛ Auto بر اساس نیاز کیفیت انتخاب می‌کند.
• بررسی و اعمال تغییرات:
  • نمایش diff فایل‌ها؛ Accept/Reject فایل یا خط به خط.
  • Review Next File برای مرور تغییرات چندفایلی.
  • Undo/Restore checkpoint/Revert برای بازگشت تغییرات.
• قوانین (Rules):
  • Global/Project rules؛ مثال: keep it simple، don’t add unnecessary code، پرهیز از trailing spaces، انتهای هر فایل newline.
• مدل‌ها و هزینه:
  • پلن 20 دلاری محدودیت دارد؛ Max و Tool Calling پرمیوم هزینه را افزایش می‌دهد.
  • امکان استفاده از API Key شخصی (OpenAI/OpenRouter) برای کاهش هزینه Cursor.
• ایندکسینگ:
  • ایندکس سریع کدبیس؛ جست‌وجوی هدفمند بخش‌های مرتبط به‌جای خواندن کل پروژه.
  • فایل‌های حجیم (مثل datasets) نادیده گرفته می‌شود؛ قابل پیکربندی.`

مدیریت کانتکست و بهترین شیوه‌ها

• کانتکست کوچک و هدفمند نگه دارید؛ فقط بخش‌های ضروری را اضافه کنید.
• از افزودن کل فایل/پروژه خودداری کنید؛ محدوده خطوط مفید را بدهید.
• اگر گفتگو طولانی و آشفته شد، در تب جدید از ابتدا با پرامپت شفاف شروع کنید.
• قبل از درخواست‌های پیچیده، قواعد ساده‌سازی را به‌عنوان Rule بدهید.
• کد تولیدی را بخوانید، سوال‌های نقطه‌ای بپرسید، سپس اصلاح کنید؛ صرفاً Accept نکنید.

گردش‌کار Ask و Agent

• Ask: پرسش‌های مفهومی/محدود؛ توضیح یک بخش کد، معنی یک کلاس/فانکشن.
• Agent: اجرای کارهای کدنویسی؛ ایجاد/ویرایش فایل‌ها، ساختار پروژه، اسکریپت‌ها.
• بین Ask و Agent هوشمندانه سوئیچ کنید؛ اجرای زودهنگام Agent بدون فهم کافی، ریسک پیچیدگی دارد.

ساخت اسکریپت ساده خواندن فایل با Cursor

• درخواست: خواندن فایل متنی myfile.txt و ساخت اسکریپت.
• Agent: ساخت فولدر scripts، تولید read_file.py با آرگ‌پارسینگ و مثال اجرا.
• بازبینی/ساده‌سازی:
  • حذف پیچیدگی غیرضروری (formatter class، try/except اضافی).
  • افزودن Rule برای حذف trailing spaces و افزودن newline انتهایی.
  • اجرای اسکریپت در ترمینال، اصلاح تدریجی، بررسی diff و Accept خطی.

ساخت پروژه FastAPI با Cursor

• تعریف نیازمندی‌ها:
  • دو endpoint: health check و query_llm
  • production ready، ایجاد requirements.txt و فایل‌های لازم
• خروجی Agent:
  • ایجاد ساختار پروژه: app، routers، schemas، config
  • جداسازی main و include_router، بهبود خوانایی
  • تولید README با راه‌اندازی و مستندات API
• بهبود ساختار:
  • کاهش کد بیش از حد در main با استفاده از router
  • یکپارچه‌سازی main.py در ریشه پروژه
  • اجتناب از دو main.py؛ rename/move و بروزرسانی README/ساختار
• اجرا:
  • تنظیم .env و OPENROUTER_API_KEY
  • انتخاب مدل OpenRouter (مثلاً gpt-4o-mini)
  • uvicorn main.py --reload و تست در /docs
  • Health check OK؛ Query نیازمند API Key معتبر و model پارامتر

مستندسازی و مزایای Agent

• README همواره به‌روز می‌ماند: setup، اجرا، مثال cURL، مدل‌ها، تنظیمات.
• بروزرسانی خودکار ساختار پروژه در README پس از تغییرات فایل‌ها.
• افزایش بهره‌وری و کاهش فراموشی در حذف/تغییر فایل‌ها و داکیومنت‌ها.

راهبردهای استفاده حرفه‌ای از AI در کدنویسی

• کد تولیدی را سریع و دقیق ریویو کنید؛ سوال‌های نقطه‌ای بپرسید.
• پرهیز از لید کردن مدل در پرسش‌ها؛ سوال‌های Open-ended برای کشف بهتر راه‌حل.
• هنگام ندانستن، حالت Ask را افزایش دهید؛ برای معماری جدید بارها پرسش و مقایسه کنید.
• در استخدام، نحوه استفاده از LLM مهم است: پذیرش بی‌فکر کد رد فلگ محسوب می‌شود.
• برای جونیورها: ابتدا زیاد کار کنید (just work)؛ سپس کار هوشمندانه را شناسایی کنید.

نکات کاربردی و ترفندها

• اجتناب از trailing spaces؛ استفاده از اکستنشن نمایش آن.
• افزودن Ruleهای کیفیت کد (newline انتهایی، لاگینگ با loguru).
• اگر خروجی ضعیف است، رن مجدد/تکرار پرامپت؛ نتایج بین ران‌ها متفاوت است.
• هزینه‌ها را کنترل کنید: مدل Auto برای تعادل کیفیت/هزینه؛ استفاده از API Key شخصی.
• بعد از چند دور پیچیده شدن گفتگو، خلاصه‌سازی و شروع تمیز در تب جدید.

جدول: شورتکات‌ها، مودها و کاربرد

جدول: راهنمای مدیریت کانتکست

Key Terms & Definitions

• LLM: مدل زبانی بزرگ برای پاسخ به پرسش‌ها؛ بدون اجرای اکشن روی فایل‌ها.
• Agent: LLM با توانایی Function Calling و انجام اکشن‌های فایل/پروژه.
• MCP (Model Context Protocol): پروتکل استاندارد دسترسی Agentها به ابزارها/سرویس‌ها روی سرور.
• Indexing: ایندکس‌سازی کدبیس برای جست‌وجوی سریع و افزودن کانتکست مرتبط.
• OpenRouter: لایه واسط برای فراخوانی مدل‌های متنوع LLM با API واحد.

Action Items / Next Steps

• نصب Cursor و تنظیم شورتکات‌ها؛ آشنایی با Ask/Agent.
• تعریف Global/Project Rules: سادگی، حذف کد اضافه، newline، trailing spaces.
• تمرین افزودن کانتکست هدفمند: رنج خطوط، ترمینال، فایل‌های کلیدی.
• ساخت یک پروژه کوچک FastAPI با دو endpoint و OpenRouter؛ ریویو دقیق کد.
• مدیریت هزینه: استفاده از Auto، افزودن API Key شخصی در صورت نیاز.
• تمرین پرسش‌های Open-ended و پرهیز از لید کردن مدل؛ تقویت مهارت ریویو.