انتخاب Ask، Plan، Agent و Debug و نوشتن Task Contract

در گردش‌کار روزانه، سؤال اصلی «کدام دکمه را بزنم؟» نیست؛ «قصد من چیست، چه مقدار اختیار امن است و چه شاهدی پایان کار را ثابت می‌کند؟» است. Ask، Plan، Agent و Debug چهار برچسب قابل‌حمل برای همین تصمیم‌اند. نام منوها و جزئیات ابزارها تغییر می‌کند، اما مرز اختیار، ریسک و Verification باید ثابت بماند.

## اهداف یادگیری

پس از این درس می‌توانی intent را از surface ابزار جدا کنی، برای یک کار میان Ask/Plan/Agent/Debug انتخاب کنی، سطح autonomy را با ریسک و برگشت‌پذیری تنظیم کنی، نگاشت محدود و تاریخ‌دار میان Cursor و معادل‌های دیگر بنویسی، و یک Task Contract کامل با Recovery و Evidence بسازی.

## جایگاه در چرخهٔ سرتاسری

فصل‌های ۴ تا ۶ به‌ترتیب Spec، Slice و Test را ساختند. این درس در مرز `Implement` و `Observe` قرار می‌گیرد: پیش از دادن کار به ایجنت باید بدانیم چه رفتاری مجاز است و پس از کار چه شاهدی می‌خواهیم. در سناریوی `booking-platform` قرارداد فصل ۵ authority است: appointment باید `CONFIRMED` باشد؛ زمان محلی در timezone کلینیک تفسیر و در UTC ذخیره می‌شود؛ deadline دقیقاً ۲۴ ساعت بسته است و پاسخ `409 RESCHEDULE_WINDOW_CLOSED` بدون mutation یا audit تازه است؛ کلید idempotency در scope `tenantId + actorId + operation` نگه‌داری می‌شود. Agent حق اختراع policy تازه ندارد.

## مفهوم: چهار intent، نه چهار محصول

**Ask** برای فهمیدن، مقایسه‌کردن یا کشف fact است. خروجی خوب آن فهرست فایل‌ها، شواهد، ابهام‌ها و گزینه‌هاست؛ هنوز patch لازم نیست. **Plan** وقتی لازم است که چند فایل، dependency، migration، قرارداد یا trade-off داریم. Plan باید مسیر، ترتیب، gate و rollback را بسازد. **Agent** برای اجرای یک کار bounded است: فایل‌های مجاز روشن‌اند، acceptance و فرمان verification وجود دارد و انسان می‌تواند diff را review کند. **Debug** حالت رسیدگی به رفتار خراب یا ناپایدار است؛ از reproduction و evidence شروع می‌شود، نه از حدس و patch.

این intentها قابل ترکیب‌اند: `Ask → Plan → Agent → Debug` یا `Ask → Agent → Verify`. آن‌ها فرمان ثابت نیستند. ممکن است یک ابزار یک سطح را با واژهٔ دیگری عرضه کند یا همه را در یک پنجره ترکیب کند. معیار، رفتار مشاهده‌شده و permission واقعی است، نه label.

مثال بد

«reschedule را درست کن، هر فایلی خواستی تغییر بده و وقتی تست سبز شد تمام است.»

این prompt intent را پنهان، scope را بی‌نهایت و Done را ضعیف می‌کند. Agent شاید deadline را تغییر دهد، تست را حذف کند، mock را جای database بگذارد یا route قدیمی را بشکند. «سبز» بدون دانستن baseline، لایهٔ تست و evidence runtime معیار کافی نیست.

مثال خوب

Intent: Ask سپس Plan؛ هنوز اجرای migration مجاز نیست.
Goal: علت ناسازگاری response reschedule با contract v1 را پیدا کن.
Context: فقط packages/contracts، route و consumer test را بخوان؛ فصل ۵ و ADR-021 authority است.
Allowed: خواندن و پیشنهاد patch در مسیر draft؛ تغییر فایل ممنوع.
Forbidden: network، database واقعی، تغییر status/body، credential و migration.
Done: جدول fact/decision، دو گزینه با trade-off و فرمان verification پیشنهادی.
Evidence: path/line، خروجی baseline و لینک contract.
Recovery: اگر consumer inventory ناقص بود، DECIDE و owner بده.

## انتخاب autonomy بر اساس ریسک

خودمختاری یک کلید روشن/خاموش نیست. چهار بُعد را بسنج: **اثر خطا** (یک فایل یا همهٔ tenantها)، **برگشت‌پذیری** (revert ساده یا mutation داده)، **ابهام** (contract قطعی یا policy باز)، و **قابلیت مشاهده** (تست deterministic یا فقط قضاوت ظاهری). کار کم‌ریسک، محلی، reversible و دارای تست می‌تواند Agent محدود داشته باشد. کار متوسط نیازمند Plan، allowlist، checkpoint و review است. کار پرریسک مانند migration destructive، permission، auth، money، production یا تغییر contract باید Ask/Plan و تأیید انسانی داشته باشد؛ گاهی اصلاً unattended مناسب نیست.

یک ماتریس عملی:

Autonomy را با اندازهٔ diff نسنج؛ یک خط در authorization ممکن است از صد خط documentation پرخطرتر باشد. اگر Agent از Scope خارج شد، stop condition فعال است، حتی اگر patch ظاهراً مفید باشد.

## نگاشت محدود و تاریخ‌دار ابزارها

در تاریخ 2026-09-05، مستند رسمی [Cursor Agent overview](https://cursor.com/docs/agent/overview.md) surface Agent و اجرای tool-using را توضیح می‌دهد. در این درس، Ask برای پرسش و تغییرات پیشنهادیِ کنترل‌شده، Plan برای طراحی قبل از اجرا، Agent برای اجرای bounded و Debug برای رسیدگی به خطاها به‌عنوان intentهای قابل‌حمل استفاده می‌شوند؛ surface دقیق، permission و نام‌گذاری می‌تواند با نسخه عوض شود. این نگاشت دربارهٔ مفهوم است، نه تضمین اینکه هر حساب یا نسخه همان دکمه را دارد.

معادل مفهومی در Claude Code معمولاً از گفت‌وگوی read-only، plan/permission workflow، اجرای ابزار و رسیدگی تعاملی به خطا تشکیل می‌شود. در Codex، best practice بر AGENTS.md، sandbox/approval و اجرای bounded تکیه دارد. Copilot نیز chat، plan-like planning و agentic task surface دارد، اما نام و مرز کنترل را باید در مستند همان محیط بررسی کرد. هیچ‌کدام را یکسان فرض نکن: سطح IDE، CLI، local و cloud می‌تواند permission، filesystem و network متفاوت داشته باشد. برای هر mapping این چهار ستون را ثبت کن: تاریخ، سند مستقیم، capability مشاهده‌شده و تفاوت/هشدار.

## Task Contract کامل

یک قرارداد کار خوب حداقل این بخش‌ها را دارد:

Goal: رفتار قابل مشاهده و محدودهٔ دقیق.
Context: artifact، نسخه، مسیرها و authority.
Constraints: invariantها، سازگاری، performance و privacy.
Allowed: فایل‌ها، فرمان‌ها، ابزارها و محیط مجاز.
Forbidden: migration destructive، network، credential، تغییر تست/contract بدون approval.
Input: acceptance example، baseline و دادهٔ آزمایشی.
Done: معیارهای pass/fail، تست‌ها و stop condition.
Evidence: diff، command/output، log، screenshot یا trace لازم.
Recovery: در failure یا ambiguity چه چیزی حفظ و به چه کسی ارجاع شود.

سناریوی booking-platform

برای S3، Goal «replay ایمن reschedule با همان idempotency key» است. Context شامل Spec v1، جدول idempotency و تست A-10/A-11 است. Constraints همان scope کلید، fingerprint و audit یکتا هستند. Allowed فقط service، repository و integration fixture در database ephemeral است. Forbidden تغییر contract، چاپ raw key، استفاده از staging و حذف assertion است. Done یعنی retry با fingerprint برابر همان status/body durable و یک mutation/audit بدهد؛ fingerprint متفاوت `409 IDEMPOTENCY_KEY_REUSED` و بدون mutation بگیرد. Evidence شامل migration additive، تست concurrent claim، log privacy scan و diff است. Recovery در ابهام scope یا failure migration، توقف و نگه‌داشتن schema است؛ نه retry نامحدود.

## آزمایشگاه گام‌به‌گام

**ورودی:** Spec v1.0، ADR-021، acceptanceهای A-09 تا A-11، مسیرهای فصل ۵ و یک تغییر محدود در mapper.

۱. قصد را بنویس و فقط factها را کشف کن:

rg -n "RESCHEDULE|IDEMPOTENCY|tenantId|actorId" packages/contracts apps/api

**Expected:** مسیر contract، service و تست‌های مرتبط پیدا شود؛ اگر مسیر وجود ندارد، فرض نساز.

۲. برای کار کوچک، Contract را در `evidence/task-contract.md` draft کن و مسیرها را allowlist کن. ۳. baseline را با فرمان پروژه اجرا کن:

pnpm exec vitest run apps/api/src/modules/appointments/reschedule.int.test.ts

**Expected:** خروجی baseline با زمان، revision و environment ثبت شود. ۴. Agent را فقط برای patch mapper اجرا کن؛ سپس targeted test، typecheck و `git diff --check` را بگیر. ۵. **Recovery:** اگر patch به policy timezone، API یا migration رسید، اجرا را متوقف، diff را نگه‌دار، وضعیت `DECIDE` و owner ثبت کن و به Plan برگرد. هرگز برای عبور از خطا assertion یا timeout را شل نکن.

## خطاهای رایج و نشانه‌ها

• ابزار را به‌جای intent انتخاب می‌کنی؛ نشانه‌اش promptی است که فقط نام یک mode دارد و Done ندارد.
• autonomy را با token یا سرعت می‌سنجی؛ نشانه‌اش دسترسی network برای یک refactor محلی است.
• mapping را timeless می‌نویسی؛ نشانه‌اش عبارت «Cursor همیشه همین‌طور است» بدون تاریخ و URL است.
• Task Contract ناقص است؛ نشانه‌اش recovery یا forbidden ندارد.
• baseline ثبت نشده؛ نمی‌دانی شکست تازه است یا قبلی.
• Agent به contract دست می‌زند؛ نشانه‌اش تغییر هم‌زمان تست، API و implementation بدون approval است.

## Verification

• [ ] intent، risk و autonomy در سه خط اول Task ثبت شده‌اند.
• [ ] authority فصل ۵ و invariantهای tenant، timezone، deadline و idempotency ذکر شده‌اند.
• [ ] Allowed و Forbidden فایل، فرمان، شبکه و credential را محدود کرده‌اند.
• [ ] Done به رفتار و evidence وصل است، نه فقط «تست سبز».
• [ ] mapping ابزار با تاریخ، سطح surface و منبع رسمی ثبت شده است.
• [ ] recovery برای ambiguity، baseline failure و scope creep وجود دارد.

## تمرین مستقل

برای اضافه‌کردن فیلتر «فقط وقت‌های آزاد همان doctor» به صفحهٔ booking، intent و autonomy را انتخاب کن و Contract بنویس؛ سپس دو نقطهٔ توقف تعیین کن.

**پاسخ نمونه و Rubric:** پاسخ خوب با Ask، مسیر query و contract را کشف می‌کند و اگر API یا privacy نامعلوم باشد Plan می‌دهد؛ Agent محدود را فقط پس از تعیین tenant/doctor authority مجاز می‌داند. Contract باید Goal، Context، Constraints، Allowed، Forbidden، Input، Done، Evidence و Recovery داشته باشد. توقف اول وقتی query به cross-tenant یا auth می‌رسد؛ توقف دوم وقتی contract یا تست موجود نیست. تغییر مستقیم database، استفاده از production و حذف تست مردود است.

## جمع‌بندی

Ask، Plan، Agent و Debug زبان مشترک برای قصد‌اند، نه وعدهٔ محصول. خودمختاری باید متناسب با اثر خطا، برگشت‌پذیری، ابهام و کیفیت evidence باشد. Task Contract مرز را اجرایی می‌کند و mapping تاریخ‌دار جلوی ادعای نادرست دربارهٔ ابزارها را می‌گیرد. در booking-platform، invariants فصل ۵ از سرعت Agent مهم‌ترند.

## منابع مستقیم

• [Cursor Agent overview](https://cursor.com/docs/agent/overview.md) — surface و قابلیت‌های Cursor؛ نام‌ها و permissionها نسخه‌پذیرند.
• [Cursor Rules](https://cursor.com/docs/rules.md) — مرز instruction و project context.
• [Claude Code best practices](https://www.anthropic.com/engineering/claude-code-best-practices) — توصیهٔ فروشنده، نه تضمین نتیجه.
• [OpenAI Codex best practices](https://developers.openai.com/codex/learn/best-practices) — قرارداد context و اجرای bounded.
• [GitHub Copilot custom agents](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents) — معادل رسمیِ محدود در Copilot CLI؛ قابلیت‌ها وابسته به surface و تاریخ‌اند و جایگزین mapping ابزارخنثی نیست.

به زبان ساده

Ask برای فهم و کشف، Plan برای طراحی وابستگی، Agent برای اجرای bounded و Debug برای کاهش عدم‌قطعیت failure است. انتخاب برچسب ابزار نیست؛ باید با ریسک، برگشت‌پذیری و کیفیت Evidence جور باشد.

مثال واقعی

برای تغییر API و migration در سناریوی فرضی دوره، ابتدا Ask/Plan و approval لازم است؛ refactor کوچک mapper با تست هدفمند می‌تواند Agent محدود داشته باشد.