قرارداد ورودی و خروجی دستیار
قالب خروجی ثابتی تعریف کن که هر بار مستقیم قابل استفاده باشد، برای فیلد خالی و نامطمئن رفتار بگذار، و قبل از هر کار ورودی را بسنج تا تغییر ستون یا واحد بیصدا گزارش غلط نسازد.
بعد از این درس میتوانی
- برای یک دستیار، قالب خروجی ثابت با فیلد، نوع، واحد و رفتار فیلد خالی یا نامطمئن تعریف کند.
- قرارداد ورودی بنویسد: چه چیزی لازم است، چه چیزی بررسی میشود و در چه شرایطی دستیار متوقف میشود و میپرسد.
- تغییر ساختار ورودی (نام ستون، واحد پول، ردیف خلاصه، خانهٔ خالی) را با «گام صفر» قبل از محاسبه تشخیص دهد.
- عدد را به ابزار محاسبه یا صفحهگسترده بسپارد و از دستیار فقط متن مبتنی بر عددهای محاسبهشده بخواهد.
چرا این درس مهم است
گزارش هفتگی برگ سبز هر هفته شکل دیگری داشت: یک بار جدول، یک بار سه پاراگراف، یک بار با درصد و یک بار بدون آن. مدیر نمیتوانست دو هفته را کنار هم بگذارد. بدتر، هفتهای که صندوق فروشگاه ستون مبلغ را به ریال برگرداند، دستیار نوشت «رشد فروش ۹۴۰٪»؛ رشد واقعی ۴٪ بود.
دستیاری که ورودی را نمیسنجد و خروجی ثابت ندارد، هر بار باید از نو بازبینی شود و صرفهجوییاش از بین میرود. این درس دو قرارداد میسازد: چه چیزی میگیرد و چه چیزی تحویل میدهد.
مفاهیم کلیدی
یادآوری: در درس «خروجی ساختاریافته: جدول، JSON و Schema» قالب خروجی یک درخواست را تعریف کردی، و در درس «از ادعا تا منبع» دیدی چرا عدد و ادعا بررسی میخواهند. اینجا همانها را به قرارداد ماندگار یک دستیار تبدیل میکنی.
- Output Contract (قرارداد خروجی): بخشهای ثابت خروجی، ترتیبشان، و برای هر فیلد نوع، واحد و قاعده.
- Empty / Uncertain Field (فیلد خالی یا نامطمئن): وقتی اطلاعات نیست یا مطمئن نیست، دستیار چه بنویسد؛ مثلاً «نامعلوم» یا «نیاز به تأیید»، نه حدس.
- Input Contract (قرارداد ورودی): ورودی لازم، شکل مورد انتظار و شرطهای توقف.
- Step Zero (گام صفر): بررسی ورودی قبل از هر کار: ستونها هستند؟ واحد معلوم است؟ ردیف خلاصه و ناقص جدا شده؟
- Safe Stop (توقف ایمن): اگر شرط لازم برقرار نیست، دستیار خروجی اصلی نمیدهد و دقیقاً میگوید چه چیزی کم است.
- Review Queue (صف بررسی): فهرست ردیفها یا مواردی که دستیار کنار گذاشته و انسان باید ببیند؛ هیچ چیز بیصدا حذف نمیشود.
- Computed vs Written (محاسبه در برابر نگارش): عدد را ابزار محاسبه یا صفحهگسترده حساب کند؛ مدل از روی عدد محاسبهشده متن بنویسد.
مدل ذهنی
قرارداد ورودی و خروجی را مثل فرم تحویل کالا در انبار ببین: انباردار قبل از امضا، تعداد و واحد را با برگهٔ حمل میسنجد؛ اگر کارتنها «بسته» نوشته شده ولی برگه «عدد» گفته، امضا نمیکند و میپرسد. رسید هم همیشه یک شکل دارد تا حسابدار بتواند هر ماه با ماه قبل مقایسه کند.
این تشبیه کجا غلط است؟ انباردار تجربه دارد و وقتی عدد عجیب است خودش شک میکند. دستیار فقط وقتی شک میکند که قرارداد گفته باشد چه چیزی را بسنجد. «۶۵۵ میلیون» برای مدل عدد عجیبی نیست، مگر اینکه بداند واحد باید تومان باشد و از ستون، واحد را بخواند.
گامبهگام
گام ۱: قالب خروجی را از نیاز گیرنده بنویس
راهنمای Anthropic توصیه میکند قالب و معیار خروجی را صریح و مشخص بگویی، نه اینکه مدل حدس بزندsrc-claude-prompting. از گیرنده بپرس خروجی را چطور استفاده میکند. مدیر برگ سبز گزارش را هر دوشنبه در جلسه با هفتهٔ قبل مقایسه میکند؛ پس همیشه همان بخشها با همان ترتیب.
مسیر محتوا: دستیار ایدهٔ پست
| فیلد | قاعده | اگر نبود یا مطمئن نبود |
|---|---|---|
| روز پیشنهادی | یکی از شنبه تا جمعه | «آزاد» |
| قالب | پست یا استوری | — |
| ستون محتوا | یکی از چهار ستون راهنمای لحن | — |
| عنوان | حداکثر ۸ واژه | — |
| متن پیشنویس | پست ۴۰ تا ۸۰ واژه؛ استوری یک جمله و یک پرسش | — |
| اطلاعات از فایل | عنوان، قیمت یا موجودی با نام فایل منبع | «از فایل نیامده»؛ قیمت ننویس |
| نیاز به تأیید | بله اگر ادعا، قیمت یا مناسبت دارد | پیشفرض: بله |
مسیر داده: دستیار گزارش هفتگی
- شناسنامهٔ ورودی: هفته، تعداد ردیف کل، ردیف معتبر، ردیف ناقص، ردیف خلاصه، واحد مبلغ و منبع واحد، وضعیت (کامل / متوقف).
- کارت شاخصها: تعداد فروش، مبلغ فروش (با واحد)، تعداد مرجوعی، نرخ مرجوعی٪.
- سهم دستهها و کانالها: مبلغ و درصد از کل.
- صف بررسی: هر ردیف کنارگذاشته با علت؛ هر نرخ مرجوعی بیش از ۵٪ در یک دسته با برچسب هشدار.
- سه جملهٔ خلاصه برای مدیر: فقط از عددهای بالا، بدون علتتراشی.
گام ۲: قرارداد ورودی و شرط توقف
برای مسیر داده، گام صفر قبل از هر محاسبه:
- ستونهای لازم با همین نامها هستند؟ اگر نامی عوض شده، فقط با نگاشت تأییدشده در فرهنگ داده قبول کن؛ وگرنه بپرس.
- واحد مبلغ از نام ستون یا فرهنگ داده معلوم است؟ از بزرگی عدد حدس نزن.
- ردیف «جمع کل» از ردیفهای فروش جدا شده؟ جمع کل فقط برای کنترل است.
- ردیف با خانهٔ خالی یا مقدار خارج از بازه به صف بررسی رفته؟
- اگر واحد معلوم نیست یا با شواهد تعارض دارد: هیچ عدد مالی نده؛ فقط شناسنامهٔ ورودی و یک پرسش مشخص.
برای مسیر محتوا، قرارداد ورودی سادهتر است: فهرست تازهرسیدههای همین هفته و مناسبتهای هفته (اگر هست). اگر فهرست تاریخگذشته است، ایده بدون قیمت بده و بگو فهرست کهنه است.
گام ۳: عدد را چه کسی حساب کند؟
| حالت | عدد را چه کسی حساب میکند | دستیار چه میکند |
|---|---|---|
| محیطت تحلیل فایل یا اجرای کد دارد | ابزار محاسبهٔ داخل محیط | محاسبه را با ابزار انجام میدهد و متن مینویسد؛ تو با صفحهگسترده یک بار مقایسه میکنی |
| محیطت ابزار محاسبه ندارد یا مطمئن نیستی | خودت در صفحهگسترده | عددهای محاسبهشده را از تو میگیرد و فقط گزارش را مینویسد |
در هر دو حالت، قاعده یکی است: دستیار عدد را با حدس یا محاسبهٔ ذهنی نمیسازد. ابزار محاسبه خطای حسابی را کم میکند، ولی فرض غلط (مثل واحد اشتباه) را درست نمیکند؛ برای همین گام صفر قبل از محاسبه است.
گام ۴: قرارداد را به دستورالعمل اضافه کن
## قالب خروجی (همیشه همین چهار بخش، با همین ترتیب)
۱. شناسنامهٔ ورودی ۲. کارت شاخصها ۳. سهم دستهها و کانالها ۴. صف بررسی
سپس حداکثر سه جملهٔ خلاصه، فقط از عددهای همین گزارش.
## گام صفر (قبل از هر محاسبه)
- ستونها را با فرهنگ داده مقایسه کن. نام تازه فقط با نگاشت تأییدشده.
- واحد مبلغ را از نام ستون یا فرهنگ داده بخوان؛ از بزرگی عدد حدس نزن.
- ردیف «جمع کل» را جدا کن؛ ردیف با خانهٔ خالی را به صف بررسی ببر.
- اگر واحد معلوم نیست یا تعارض دارد: هیچ عدد مالی نده. فقط شناسنامهٔ ورودی و یک پرسش.
## محاسبه
عددها را با ابزار محاسبه حساب کن. اگر ابزار محاسبه در دسترس نیست، بگو و منتظر عددهای من بمان.مثالها
ورودی هفتهٔ ۳۲: فایل assets/barg-sabz-weekly-sales.csv. خروجی درست (عددها با صفحهگسترده محاسبه و کنترل شدهاند):
| بخش | خروجی درست |
|---|---|
| شناسنامه | هفته 1405-W32؛ ۱۰ ردیف؛ ۸ معتبر؛ ۱ ناقص (کودک، سایت، ۱۲ قلم، مبلغ خالی)؛ ۱ ردیف جمع کل؛ واحد: تومان (از نام ستون)؛ وضعیت: کامل با یک مورد بررسی |
| کارت شاخصها | تعداد فروش ۲۷۹ قلم؛ مبلغ ۶۲٬۹۹۰٬۰۰۰ تومان؛ مرجوعی ۷ قلم؛ نرخ مرجوعی ۲٫۵۱٪ |
| سهم دستهها | کمکآموزشی ۴۸٫۵٪، داستان ۲۸٫۸٪، کودک ۱۵٫۱٪، لوازمالتحریر ۷٫۷٪ |
| سهم کانالها | سایت ۵۸٫۷٪، فروشگاه ۴۱٫۳٪ |
| صف بررسی | ردیف «کودک، سایت» مبلغ ندارد؛ تعداد ۱۲ قلم آن در شاخصها نیامده. تعداد ردیف جمع کل (۲۹۱) با جمع ردیفهای معتبر (۲۷۹) به اندازهٔ همین ۱۲ قلم فرق دارد. |
دقت کن دستیار ردیف ناقص را نه صفر کرده و نه بیصدا حذف؛ کنار گذاشته و گفته. اختلاف ۲۹۱ و ۲۷۹ هم خودش یک کنترل است.
ورودی هفتهٔ ۳۳: فایل assets/barg-sabz-weekly-sales-next.csv. ستون مبلغ حالا «مبلغ_ریال» است.
| دستیار | رفتار | نتیجه |
|---|---|---|
| بدون گام صفر | ستون مبلغ را مثل هفتهٔ قبل تومان فرض میکند | «رشد فروش ۹۴۰٫۵٪» ❌ |
| با گام صفر و نگاشت تأییدشده «مبلغ_ریال ← ریال، تقسیم بر ۱۰» | واحد را از نام ستون میخواند و تبدیل را اعلام میکند | ۶۵٬۵۴۰٬۰۰۰ تومان؛ رشد ۴٫۰٪ ✅ |
| با گام صفر و بدون نگاشت | نام ستون در فرهنگ داده نیست | هیچ عدد مالی؛ پرسش: «ستون مبلغ_ریال تازه است؛ واحدش ریال است و باید بر ۱۰ تقسیم شود؟» ✅ |
پیادهسازی
مسیر محتوا: دستیار ایدهٔ پست
- جدول قالب خروجی گام ۱ را در بخش ۳ برگهٔ مشخصات بنویس.
- قاعدهٔ ورودی را اضافه کن: «اگر فهرست تازهرسیدهها تاریخگذشته است، ایده بدون قیمت و با اعلام کهنهبودن».
- قالب را به دستورالعمل اضافه کن (نسخهٔ ۳) و ایدههای هفته را بخواه.
- بررسی کن: همهٔ هفت فیلد هست؟ هر قیمت نام فایل منبع دارد؟ «نیاز به تأیید» برای هر ادعا بله است؟
- یک بار دیگر، با فهرستی که تاریخش را عمداً به هفتهٔ ۲۸ عوض کردهای، امتحان کن.
مسیر داده: دستیار گزارش هفتگی
- قرارداد چهاربخشی و گام صفر را به دستورالعمل اضافه کن (نسخهٔ ۳).
- عددهای هفتهٔ ۳۲ را خودت در صفحهگسترده حساب کن (جمع مبلغ ردیفهای معتبر، تعداد، مرجوعی، نرخ).
- فایل هفتهٔ ۳۲ را به دستیار بده و خروجی را با عددهای خودت و جدول مثال مقایسه کن.
- فایل هفتهٔ ۳۳ را بده بدون افزودن نگاشت ریال. انتظار: توقف و پرسش.
- نگاشت «مبلغ_ریال ← ریال، تقسیم بر ۱۰» را به فرهنگ داده اضافه کن (نسخهٔ ۴) و دوباره بده. انتظار: ۶۵٬۵۴۰٬۰۰۰ تومان و رشد ۴٫۰٪.
اشتباههای رایج
| اشتباه | نتیجه | کار درست |
|---|---|---|
| «گزارش خوب بنویس» بدون قالب | هر هفته شکل دیگر؛ مقایسهناپذیر | بخشهای ثابت با ترتیب ثابت |
| حدس واحد از بزرگی عدد | ریال و تومان قاطی؛ رشد ۹۴۰٪ | واحد از نام ستون یا فرهنگ داده؛ وگرنه توقف |
| صفرکردن یا حذف بیصدای ردیف ناقص | عدد غلط بدون اینکه کسی بفهمد | صف بررسی با علت |
| جمعزدن ردیف «جمع کل» با بقیه | مبلغ دو برابر | جدا کردن ردیف خلاصه و استفاده از آن فقط برای کنترل |
| اعتماد به عددی که مدل «حساب کرده» | خطای حسابی یا فرض غلط | محاسبه با ابزار یا صفحهگسترده؛ مقایسهٔ مستقل |
| نبودن رفتار فیلد خالی | دستیار جای خالی را با حدس پر میکند | «نامعلوم» یا «از فایل نیامده» |
| خلاصه با علتتراشی («بهخاطر شروع مدرسهها») | ادعای بیپشتوانه در گزارش مدیر | خلاصه فقط از عددهای همین گزارش |
عیبیابی
رشد فروش ناگهان چند صد درصد گزارش شده.
واحد یک ستون عوض شده (مثلاً ریال) و دستیار آن را تومان فرض کرده.
نام ستونها و چند مقدار را با هفتهٔ قبل مقایسه کن.
گام صفر را اضافه کن: واحد از نام ستون یا فرهنگ داده؛ نگاشت تازه فقط با تأیید.
مبلغ کل گزارش دقیقاً دو برابر صندوق است.
ردیف «جمع کل» با ردیفهای فروش جمع شده.
در شناسنامهٔ ورودی ببین ردیف خلاصه جدا شده یا نه.
قاعدهٔ جداکردن ردیف خلاصه را به گام صفر و فرهنگ داده اضافه کن.
دستیار برای هر فایل کوچکترین تفاوتی متوقف میشود.
شرط توقف خیلی سخت است؛ مثلاً تفاوت فاصله یا ترتیب ستون را هم تغییر ساختار میداند.
کدام تفاوتها واقعاً معنا یا واحد را عوض میکنند؟
فقط برای ستون لازمِ غایب، نام ناشناخته و واحد نامعلوم توقف؛ ترتیب ستون مهم نیست.
در یک محیط عدد درست است و در محیط دیگر غلط.
یکی ابزار محاسبه را اجرا کرده و دیگری عدد را با متن ساخته.
در هر خروجی دنبال نشانهٔ اجرای ابزار بگرد و با صفحهگسترده مقایسه کن.
در محیطی که محاسبه قابل اتکا نیست، عدد را خودت بده و دستیار فقط بنویسد.
تمرین کوتاه
تمرین · 10 دقیقه
موقعیت (ساختگی): فایل فروش این هفتهٔ برگ سبز این تفاوتها را با فرهنگ داده دارد: (الف) ترتیب ستون «کانال» و «دسته» جابهجا شده؛ (ب) ستون «تعداد_مرجوعی» نیست؛ (ج) ستون مبلغ نامش «مبلغ» است، بدون واحد؛ (د) یک ردیف «تعداد_فروش» منفی دارد.
گامها: برای هر مورد بنویس دستیار با گام صفر چه کند: ادامه، صف بررسی، یا توقف و پرسش. یک دلیل کوتاه بیاور.
راهحل نمونه
- الف: ادامه؛ ترتیب ستون معنا را عوض نمیکند.
- ب: شاخصهای مرجوعی را «نامعلوم» بنویس و در شناسنامه اعلام کن؛ بقیهٔ گزارش ممکن است. اگر قرارداد مرجوعی را لازم میداند، توقف.
- ج: توقف برای عددهای مالی؛ واحد معلوم نیست. پرسش: «ستون مبلغ تومان است یا ریال؟»
- د: آن ردیف به صف بررسی؛ در محاسبه نیاید.
چالش
تمرین · 30 دقیقه
موقعیت: قرارداد ورودی و خروجی دستیار خودت را بنویس.
- از گیرندهٔ خروجی (یا خودت در نقش او) بپرس خروجی را چطور استفاده میکند؛ بخشها و ترتیب را از جوابش دربیاور.
- برای هر فیلد قاعده و رفتار خالی یا نامطمئن بنویس.
- قرارداد ورودی با دستکم سه شرط بررسی و یک شرط توقف بنویس.
- دو ورودی بساز: یکی سالم، یکی با یک تغییر ساختاری واقعی برای کار تو. هر دو را امتحان کن.
- اگر خروجی عدد دارد، یک بار با صفحهگسترده مقایسه کن.
معیار پذیرش: خروجی سالم همهٔ فیلدها را با قالب ثابت دارد؛ ورودی تغییرکرده به توقف یا صف بررسی رسیده، نه خروجی غلط؛ هیچ عددی بدون محاسبهٔ قابل بررسی نیست؛ دفتر نسخه بهروز است.
خودسنجی
جمعبندی
- قالب خروجی ثابت را از نیاز گیرنده بنویس؛ همان بخشها با همان ترتیب، تا خروجیها مقایسهپذیر باشند.
- برای فیلد خالی یا نامطمئن رفتار صریح بگذار؛ دستیار جای خالی را با حدس پر نکند.
- گام صفر قبل از هر کار: ستون، واحد، ردیف خلاصه و ردیف ناقص.
- واحد از نام ستون یا فرهنگ داده خوانده میشود، نه از بزرگی عدد؛ اگر معلوم نیست، توقف و پرسش.
- عدد را ابزار محاسبه یا صفحهگسترده حساب کند؛ هیچ ردیفی بیصدا حذف نشود.
پرسشهای سنجش
گزارش دستیار برگ سبز میگوید مبلغ فروش هفته ۱۲۵٬۹۸۰٬۰۰۰ تومان است، ولی صفحهگستردهٔ تو ۶۲٬۹۹۰٬۰۰۰ تومان میدهد. محتملترین علت و اصلاح چیست؟
پاسخ نمونه و معیار ارزیابی
مبلغ دقیقاً دو برابر است؛ ردیف «جمع کل» با ردیفهای فروش جمع شده. اصلاح: در گام صفر و فرهنگ داده، ردیف خلاصه را جدا کن و فقط برای کنترل استفاده کن؛ این مورد را به آزمونها اضافه کن.
- دو برابر بودن را به ردیف جمع کل نسبت میدهد (2 امتیاز)
- اصلاح در گام صفر یا فرهنگ داده (1 امتیاز)
ستون مبلغ این هفته «مبلغ_ریال» نام دارد و در فرهنگ داده نگاشتی برایش نیست. رفتار درست دستیار کدام است؟
- چون عددها بزرگاند، ریال فرض کن و بر ۱۰ تقسیم کن.
- مثل هفتهٔ قبل تومان فرض کن.
- هیچ عدد مالی نده؛ شناسنامهٔ ورودی و یک پرسش دربارهٔ واحد و تبدیل.
- ستون را نادیده بگیر و گزارش را بدون مبلغ کامل اعلام کن.
پاسخ نمونه و معیار ارزیابی
- a ← بزرگی عدد اثبات واحد نیست؛ حدس است.
- b ← نام ستون عوض شده؛ فرض هفتهٔ قبل خطرناک است.
- d ← گزارش بدون مبلغ را «کامل» نامیدن پنهانکاری است.
دستیار گزارش هفتگی در خلاصه نوشته: «افزایش فروش کمکآموزشی بهخاطر نزدیکشدن امتحانات است.» این جمله کدام قاعدهٔ قرارداد را نقض میکند و نسخهٔ درستش چیست؟
پاسخ نمونه و معیار ارزیابی
قاعدهٔ «خلاصه فقط از عددهای همین گزارش، بدون علتتراشی» را نقض میکند؛ علت در داده نیست. نسخهٔ درست: «کمکآموزشی با ۴۸٫۵٪ بیشترین سهم فروش هفته را داشت.» اگر علت لازم است، بهعنوان پرسش برای مدیر بیاید، نه ادعا.
- علتتراشی بیپشتوانه را تشخیص میدهد (1 امتیاز)
- نسخهٔ عددی بدون علت مینویسد (1 امتیاز)
- پیشنهاد پرسش بهجای ادعا (1 امتیاز)
برای دستیار ایدهٔ پست برگ سبز، رفتار فیلد «قیمت» را در سه حالت بنویس: قیمت در فهرست معتبر هست؛ کتاب در فهرست نیست؛ فهرست تاریخگذشته است.
پاسخ نمونه و معیار ارزیابی
هست: قیمت با نام فایل منبع. نیست: «از فایل نیامده» و هیچ قیمتی نوشته نشود. تاریخگذشته: قیمت ننویس، «فهرست قیمت کهنه است» را اعلام کن و «نیاز به تأیید: بله».
- حالت موجود با منبع (1 امتیاز)
- حالت ناموجود بدون حدس (1 امتیاز)
- حالت کهنه با اعلام و تأیید (1 امتیاز)
محیطی که داری تحلیل فایل دارد ولی یک بار عددی داد که با صفحهگسترده نمیخواند. از این به بعد عددها را چطور تولید میکنی؟ مزیت و هزینهٔ تصمیمت را بگو.
پاسخ نمونه و معیار ارزیابی
یا (۱) عددها را خودم در صفحهگسترده حساب میکنم و دستیار فقط گزارش را مینویسد: مطمئنتر، ولی چند دقیقه کار دستی هر هفته؛ یا (۲) محاسبهٔ دستیار را نگه میدارم ولی هر هفته یکی دو عدد کلیدی را با صفحهگسترده کنترل میکنم و مورد ناهمخوان را به آزمونها اضافه میکنم: سریعتر، با ریسک باقیمانده. در هر دو، عدد ساختهٔ ذهن مدل قبول نیست.
- یک گزینهٔ مشخص با مزیت و هزینه (2 امتیاز)
- کنترل مستقل یا افزودن به آزمون (1 امتیاز)
فایلهای درس
فروش هفتهٔ ۳۲؛ یک ردیف ناقص و یک ردیف جمع کل
barg-sabz-weekly-sales.csvفروش هفتهٔ ۳۳ با ستون مبلغ به ریال و نام تازه
barg-sabz-weekly-sales-next.csvفهرست تازهرسیدهها و قیمت ساختگی
barg-sabz-new-arrivals.mdقالب برگهٔ مشخصات دستیار
assistant-spec-template.mdابزارها و جایگزینها
- ویرایشگر متن — نوشتن برگهٔ مشخصات دستیار — Google Docs — Notepad
- یک محیط دستیار ثابت — ساختن و اجرای دستیار — ChatGPT Projects — Claude Projects — Gemini Skills — یک چت معمولی با چسباندن دستورالعمل در پیام اول
- صفحهگسترده — محاسبهٔ مستقل عددها برای مقایسه — Google Sheets — Excel — LibreOffice Calc
منابع
Prompting best practices (Be clear and direct) Anthropic docs 2026-10