در مخزن Brownfieldِ «booking-platform»، مدیر محصول می‌گوید: «رزرو تکراری را نگذار.» این یک جمله است، اما می‌تواند به تکمیل یک شرط کوچک، گفت‌وگو دربارهٔ قاعده، تغییر چند فایل با ابزار، یا حلقه‌ای محدود برای کشف و راستی‌آزمایی تبدیل شود. تفاوت این چهار حالت، اسم محصول نیست؛ تفاوت در اختیار، بازخورد و مسئولیت است.
## اهداف یادگیری
پس از این درس می‌توانی سطح‌های Autocomplete، Chat، ایجنت و حلقهٔ خودکارِ محدود را از هم جدا کنی؛ برای یک کار، سطح خودمختاری متناسب انتخاب کنی؛ و بفهمی چرا «فایل تغییر کرد» نه معیار پایان است و نه شاهد ایمنی.
## جای درس در چرخهٔ سرتاسری
چرخهٔ دوره با `Elicit → Specify → Slice → Test → Implement → Observe → Verify → Integrate → Learn` پیش می‌رود. این درس هنوز قصد ندارد قاعدهٔ رزرو را کامل Specify کند. جای آن پیش از اجرای ایجنت است: تشخیص بدهیم کدام بخش کار به پیشنهاد، کدام به گفت‌وگو، و کدام به عملِ ابزارمند با توقف انسانی نیاز دارد.
## چهار سطح، چهار قرارداد متفاوت
**Autocomplete** در همان جایی که نشانگر نوشتن است، ادامه‌ای احتمالی پیشنهاد می‌کند. معمولاً فایل دیگر را نمی‌خواند، فرمانی اجرا نمی‌کند و از نتیجهٔ واقعی برنامه خبر ندارد. مزیتش اصطکاک کم است؛ انسان هنوز نویسنده و بازبین خط به خط است. خطرش این است که یک پیشنهاد خوش‌خوان را با فهم رفتار موجود اشتباه بگیریم.
**Chat** پاسخ زبانی می‌دهد: می‌تواند طراحی، Regex، pseudo-code یا فهرست بررسی پیشنهاد کند، اما تا وقتی چیزی را نمی‌خواند یا اجرا نمی‌کند، مشاهده‌ای از مخزن ندارد. Chat برای روشن‌کردن گزینه‌ها و پرسش از تصمیم‌های مبهم مناسب است. پاسخ آن یک فرضیه است، نه Patch.
**ایجنتِ ابزارمند** هدف و Context می‌گیرد، فایل می‌خواند، جست‌وجو می‌کند، تغییر می‌دهد و تست را اجرا می‌کند. این همان معنای عملیِ ایجنت در واژه‌نامه است: مدل به‌اضافهٔ دستور و ابزار در چند گام مشاهده و عمل. ابزار، دقت مدل را تضمین نمی‌کند؛ فقط امکان اثرگذاری و دریافت مشاهده را می‌افزاید. پس Scope، مجوز و فرمان Verification باید از ابتدا معلوم باشند.
**حلقهٔ خودکارِ محدود** همان ایجنت را با تکرار، وضعیت پایدار و توقف صریح می‌سازد. هارنس پس از هر مشاهده تصمیم می‌گیرد ادامه دهد، برای تصمیم انسان مکث کند یا با `COMPLETE`، `BLOCKED` و `DECIDE` تمام کند. «خودکار» به معنی «بی‌نیاز از انسان» نیست: سقف زمان، هزینه، تعداد دور، مسیرهای مجاز و دروازهٔ تأیید، اختیار آن را محدود می‌کنند.
منابع رسمی Cursor، Copilot و Codex سطح‌ها و Surfaceهای محصول را جدا توصیف می‌کنند؛ Anthropic نیز برای کارهای پیچیده‌تر، Workflow و Agent را بر پایهٔ بازخورد واقعی پیشنهاد می‌کند. این‌ها اثبات نمی‌کنند که هر کار با ایجنت بهتر انجام می‌شود؛ فقط قابلیت‌های ابزار و الگوهای طراحی آن‌ها را شرح می‌دهند.
## مقایسهٔ ابزارها: سطح اجرا و مسئولیت ثابت
این مقایسه، وضعیت مستندات رسمیِ بررسی‌شده در ۲۰۲۶-۰۹-۰۵ است، نه رتبه‌بندی ابزار یا وعدهٔ رفتار نسخه‌های آینده. Surface، مجوز و محصول ممکن است تغییر کند؛ Task Contract و Verification محلی باید همراه هر Lab ثبت شوند.
| ابزار | سطح اجرای رایج و حلقهٔ عمل | Artifact و رفتار شاخه | مسئولیت Verification |
|---|---|---|---|
| Cursor | Agent در IDE روی working tree محلی، با جست‌وجو، ویرایش و فرمان ترمینال | Checkpoint محلی برای undo می‌سازد؛ جدا از Git است و branch یا commit شاهد پایان نیست | توسعه‌دهنده Diff، فرمان‌ها و Test Oracle را بازبینی می‌کند |
| Claude Code | عامل CLI با ابزار فایل، جست‌وجو، اجرا و اتصال‌های افزونه‌ای مانند MCP | تغییر در checkout/محیطی است که کاربر در آن اجرا کرده؛ branch، commit و artifact تحویل باید صریحاً خواسته و با Git بررسی شود | کاربر/تیم، Scope ابزار و خروجی فرمان‌های واقعی را می‌پذیرد یا رد می‌کند |
| GitHub Copilot cloud agent | حلقهٔ پس‌زمینه در محیط ephemeralِ GitHub Actions با تحقیق، تغییر، تست و lint | یک branch برای هر task می‌سازد/به‌روزرسانی می‌کند و می‌تواند یک PR باز کند؛ PR هنوز درخواست review است، نه پذیرش خودکار | مالک مخزن Diff، log و PR را بررسی و merge را طبق policy انجام می‌دهد |
| OpenAI Codex | Surfaceهای CLI، IDE و Cloud؛ هارنس، Context و Tool Callها را در thread اجرا می‌کند | در Local ممکن است تغییر در working tree باشد و در App می‌توان worktree جدا انتخاب کرد؛ worktree ایزوله‌سازی runtime یا تأیید Git نیست | انسان باید Definition of Done، فرمان repro، تست دوباره و بازبینی تغییر را تعیین کند |
نتیجهٔ جدول یکسان‌سازیِ رفتار ابزارها نیست. Cursor و Claude Code می‌توانند در محیط محلی اثر بگذارند؛ Copilot cloud agent Artifact شاخه/PR می‌دهد؛ Codex چند Surface دارد. در هر چهار مورد، «Agent اجرا کرد» فقط Observation است. مسئولیت پذیرشِ رفتار، امنیت و Merge با مالک انسانی و دروازه‌های مستقل می‌ماند.
## مثال واقعی: یک درخواست، چهار پاسخ
فرض کن درخواست این است: «اگر یک پزشک در یک بازهٔ زمانی قرار دارد، رزرو جدید نساز.» در Canon دوره، سامانه چندمستأجری است، تاریخ‌ها timezone دارند و دو درخواست هم‌زمان ممکن‌اند. بنابراین عبارت «تکراری» هنوز تصمیم‌های لازم را پنهان می‌کند: هم‌پوشانی بازه یا زمان آغاز برابر؟ Tenant چه نقشی دارد؟ قاعده هنگام Reschedule هم اجرا می‌شود؟ چه چیزی پاسخ Idempotency را از Double booking جدا می‌کند؟
در Autocomplete، توسعه‌دهنده شاید کنار سرویس فعلی بنویسد:
if (existingAppointment) throw new ConflictError("slot unavailable");این پیشنهاد برای تایپ سریع مفید است، اما `existingAppointment`، Query، هم‌زمانی و مرز tenant را انسان باید کشف و بررسی کند. Autocomplete هیچ شاهدی ندارد که Query قبل از Insert در برابر دو تراکنش هم‌زمان کافی است.
در Chat، پرسش بهتر چنین است: «برای PostgreSQL، جلوگیری از هم‌پوشانی رزروِ پزشک در یک Tenant را با قید داده و پاسخ API توضیح بده؛ فرض‌ها را جدا بنویس.» پاسخ می‌تواند گزینهٔ قید پایگاه‌داده، Transaction و تست رقابتی بدهد. هنوز انسان باید تصمیم محصول را بگیرد و پاسخ را با Schema واقعی بسنجد.
در ایجنت محلی، قرارداد کوچک‌تر و قابل‌اجرا است:
Goal: برای create appointment، تعارض بازهٔ یک پزشک در همان tenant را رد کن.
Context: apps/api/src/modules/appointments و packages/database را بخوان.
Constraints: migration تولید نکن؛ فایل خارج از این دو مسیر را تغییر نده؛ شبکه ممنوع.
Done: تست موجود را اجرا کن، یک تست رقابتی اضافه کن و Diff را خلاصه کن.ایجنت ابتدا Schema و تست‌ها را می‌خواند، فرض‌هایش را گزارش می‌کند، Patch پیشنهادی و خروجی تست را می‌دهد. اگر می‌بیند قید لازم است، چون Migration منع شده، باید `DECIDE` کند؛ نباید محدودیت را بی‌صدا نقض کند.
در حلقهٔ خودکارِ محدود، کار به برش‌های قابل‌راستی‌آزمایی تبدیل می‌شود: کشف قرارداد فعلی، نوشتن تست Red، پیاده‌سازی کمینه، اجرای Unit و Integration، سپس توقف برای بازبینی Migration. هارنس حداکثر سه دور یا بیست دقیقه دارد؛ دسترسی نوشتن فقط به worktree آزمایشی است؛ هر شکست تست مشاهده‌ای است که به Context دور بعد برمی‌گردد. پایان معتبر، «Patch ساخته شد» نیست: `COMPLETE` فقط پس از Test Oracle مورد تأیید، خروجی فرمان و Diff قابل‌خواندن مجاز است.
مثال ضعیف و علت شکست
«این باگ رزرو را درست کن، هرچه لازم است انجام بده و وقتی تمام شد بگو تمام شد.» این Prompt هم هدف مبهم دارد، هم Scope باز، هم معیار پایان را به اعلام خود ایجنت واگذار می‌کند. ایجنت ممکن است Query را تغییر دهد، تست را ضعیف کند یا یک Migration خطرناک بسازد و از روی خروجی سبزِ ناقص نتیجه بگیرد. نتیجه ظاهراً سریع است، اما معلوم نیست چه رفتاری برای کاربر، Tenant دیگر یا درخواست هم‌زمان حفظ شده است.
مثال اصلاح‌شده
انسان ابتدا یک تصمیم ثبت می‌کند: «تعریف overlap و رفتار Idempotency باید توسط مالک محصول تأیید شود.» سپس ایجنت فقط facts را کشف می‌کند: مسیر Endpoint، قیدهای موجود و فرمان تست. پس از تأیید Spec، Patch باید حداقل یک تست هم‌زمان، تست جداسازی Tenant و خروجی فرمان را همراه داشته باشد. این مرز، انسان را از کار مکانیکی آزاد می‌کند اما تصمیم ارزش و ریسک را واگذار نمی‌کند.
## راهنمای انتخاب اختیار
| وضعیت کار | سطح مناسب | چرا | شرط عبور به سطح بالاتر |
|---|---|---|---|
| نام‌گذاری محلی یا boilerplate قابل‌دیدن | Autocomplete | اثر کوچک و بازبینی فوری | ندارد |
| انتخاب الگوریتم یا روشن‌کردن Trade-off | Chat | پاسخ برای گفت‌وگو است | تصمیم ثبت شود |
| Refactor تکراری با تست معتبر | ایجنت ابزارمند | Scope و Oracle روشن است | Diff و تست مستقل |
| چند گام مستقل با بازخورد ماشینی | حلقهٔ محدود | تکرار ارزش دارد | Budget، حالت پایدار، stop condition |
| پرداخت، Auth، حذف داده، Production deploy | توقف انسانی/کار محدود | برگشت‌پذیری و Blast radius مهم‌اند | Threat model و approval صریح |
قاعدهٔ سرانگشتی: هرچه ابهام تصمیم، اثر خارجی یا دشواری بازگرداندن بیشتر است، اختیار کمتر و Evidence بیشتر لازم است. این قاعده تضمین ایمنی نیست؛ یک تصمیم مهندسی است که باید با دامنه و سیاست سازمان سازگار شود.
## به زبان ساده
Autocomplete مثل پیشنهاد کلمه هنگام نوشتن است؛ Chat مثل همکار پشت تخته؛ ایجنت مثل همکار با دسترسی به قفسه‌ها و ابزار کار؛ حلقهٔ محدود مثل خط کاری است که فقط تا سه ایستگاه می‌رود، رسید هر ایستگاه را نگه می‌دارد و کنار درِ حساس، منتظر امضای انسان می‌ماند.
## آزمایشگاه: ده کار را طبقه‌بندی کن
**ورودی:** فهرست زیر و یک فایل یادداشت محلی. ۱) کامل‌کردن نام متغیر؛ ۲) توضیح تفاوت Idempotency و Double booking؛ ۳) تغییر متن خطای فرم؛ ۴) یافتن همهٔ مصرف‌کننده‌های یک DTO؛ ۵) Rename داخلی با تست؛ ۶) افزودن قید یکتایی؛ ۷) Migration دادهٔ رزرو؛ ۸) پاسخ به Incident تولید؛ ۹) حذف tenant؛ ۱۰) ساختن ده تست مشابه از مثال‌های تأییدشده.
**گام‌ها:** ۱. برای هر مورد سطح پیشنهادی و دلیل را بنویس. ۲. کنار هر مورد، Scope نوشتن، Evidence لازم و توقف انسانی را مشخص کن. ۳. برای موارد ۶ تا ۹، «چه تصمیمی هنوز انسانی است؟» را اضافه کن. ۴. فرمانی اجرا نکن؛ این آزمایشگاه دربارهٔ قرارداد است، نه تغییر مخزن.
**خروجی مورد انتظار:** موارد ۱ و ۳ معمولاً Autocomplete یا بازبینی دستی‌اند؛ ۲ Chat؛ ۴ و ۵ ایجنت ابزارمند؛ ۱۰ حلقهٔ محدود فقط اگر مثال و تست معتبر است. ۶ تا ۹ باید حداقل به approval و طرح Verification متصل شوند؛ Incident ممکن است برای مشاهده و جمع‌آوری شواهد از ابزار بهره بگیرد، نه اقدام خودکار.
**Recovery:** اگر بین دو سطح مرددی، سطح پایین‌تر را انتخاب کن و یک سؤال یا Artifactِ گمشده را بنویس. با «ایجنت قوی‌تر» ابهام محصول را پنهان نکن.
## خطاهای رایج و نشانه‌ها
- «Agent» را نام هر پنجرهٔ چت دانستن: هیچ Tool Call یا Observation قابل‌دیدن نیست.
- واگذاری تصمیم به جای کشف: Prompt از ایجنت می‌خواهد سیاست لغو یا مالک داده را انتخاب کند.
- پایان‌دادن با پیام موفقیت: خروجی تست، Diff و Scope تغییر وجود ندارد.
- افزایش اختیار برای حل Context ناقص: ایجنت بارها فایل نامرتبط می‌خواند یا چرخه می‌زند.
- تعمیم سرعت: یک Demo کوتاه یا Benchmark، زمان Review و Merge همین مخزن را اندازه نگرفته است.
## چک‌لیست راستی‌آزمایی
- [ ] هدف، Scope و اثر خارجی کار را نوشته‌ام.
- [ ] سطح اختیار با برگشت‌پذیری و ریسک متناسب است.
- [ ] تصمیم‌های محصول را از factهای قابل‌کشف جدا کرده‌ام.
- [ ] برای هر تغییر، Oracle و فرمان بررسی معلوم است.
- [ ] هارنسِ تکرارشونده Budget و خروجی `COMPLETE/BLOCKED/DECIDE` دارد.
- [ ] پیام موفقیت ایجنت را جای Evidence مستقل نگرفته‌ام.
## تمرین مستقل
برای قابلیت «ارسال Reminder قابل‌تکرار برای رزرو فردا»، یک Task Contract کوتاه بنویس و سطح اختیار را انتخاب کن.
**Rubric پاسخ:** پاسخ خوب Goal قابل‌مشاهده، مسیرهای مجاز، ممنوعیت ارسال واقعی، دادهٔ ساختگی، فرمان تست، معیار Idempotency و یک توقف انسانی برای Template یا Provider دارد. اگر «ارسال کن و تمام کن» یا مجوز نامحدود دارد، هنوز قرارداد وظیفه نیست.
## جمع‌بندی
Agentic engineering انتخاب یک نام تجاری یا بیشترین خودمختاری نیست. یک تغییر با سطح مناسب اختیار، Context کوچک و مرتبط، مشاهدهٔ واقعی و Verification مستقل قابل‌اعتمادتر می‌شود. در درس بعد اجزایی را می‌سازیم که این بازخورد و توقف را ممکن می‌کنند.
## منابع مستقیم
- [Anthropic — Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) — گزارش میدانی فروشنده؛ الگوهای Workflow و Agent، نه تضمین بهره‌وری.
- [Cursor Agent overview](https://cursor.com/docs/agent/overview.md) — مستند رسمی قابلیت‌ها؛ جزئیات Surface نسخه‌پذیر است.
- [Claude Code feature overview](https://code.claude.com/docs/en/features-overview) — مستند رسمی ابزار و افزونه‌ها؛ محیط اجرا و مجوزها باید در Lab ثبت شوند.
- [GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) — مستند رسمی؛ سطح Cloud را به IDE یا CLI تعمیم نده.
- [OpenAI Codex workflows](https://developers.openai.com/codex/workflows) و [best practices](https://developers.openai.com/codex/learn/best-practices) — مستند رسمی؛ توصیهٔ محصول جای Evidence محلی نیست.
به زبان ساده
هرچه یک کار ابهام و اثر بیشتری داشته باشد، صرفاً پیشنهاد کد کافی نیست و باید اختیار، ابزار و معیار توقف آن روشن شود. Agent می‌تواند فایل بخواند و تست اجرا کند، اما مسئولیت پذیرش رفتار همچنان با انسان است.
مثال واقعی
در سناریوی فرضی دوره برای `booking-platform`، درخواست جلوگیری از رزرو هم‌پوشان ابتدا به Chat برای روشن‌کردن policy، سپس به Agent محدود برای تغییر مشخص و در پایان به review انسانی سپرده می‌شود.