پروژه‌ی پایانی: ساخت بسته‌ی میزکار چندبارمصرف برای ایجنت‌ها

وقتی راه‌اندازی ایجنت هوش مصنوعی در هر پروژه به کپی‌پیست دستورالعمل‌ها، اسکریپت‌های ناقص و تاریخچه‌ی چت‌ها وابسته باشد، با هر ریفکتور یا تغییر فصل ناچارید همه‌چیز را از صفر سرهم کنید. این پراکندگی، قابلیت اعتماد به ایجنت‌ها را از بین می‌برد و همکاری تیمی را مختل می‌کند.

در این پروژه‌ی پایانی، یاد می‌گیرید چطور هفت سطح تعامل میزکار مهندسی ایجنت را در قالب یک بسته‌ی مستقل (Drop-in Pack) و دارای نسخه‌گذاری استاندارد بسته‌بندی کنید؛ بسته‌ای که با یک دستور ساده و به‌صورت پایا (Idempotent) روی هر مخزنی می‌نشیند و از همان روز اول کار می‌کند.

این بخش با بسته‌ای تمام می‌شود که می‌توانید آن را به هر مخزنی اضافه کنید. 11 درس درباره‌ی سطوح تعامل را در پوشه‌ای فشرده کرده‌ایم که با یک cp -r ساده کپی می‌شود تا صبح روز بعد، ایجنتی داشته باشید که با اطمینان کار می‌کند. این پروژه‌ی پایانی، همان دست‌سازه‌ای است که اعتبار کل این دوره روی آن بنا شده.

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

• بسته‌بندی هفت سطح میزکار در قالب یک پوشه‌ی مستقل و آماده‌ی استفاده.
• تثبیت نسخه‌ی اسکیماتیک‌ها، اسکریپت‌ها و قالب‌ها، تا هر مخزن جدید کارش را با یک خط مبنای مطمئن و آزموده‌شده آغاز کند.
• افزودن یک اسکریپت نصب‌کننده که بسته را به‌صورت پایا (idempotent) مستقر کند.
• تصمیم‌گیری آگاهانه درباره‌ی اینکه چه مواردی داخل بسته بمانند و چه مواردی کنار گذاشته شوند، همراه با دفاع فنی از این مرزبندی.
• پیاده‌سازی یک تغییر به کمک ایجنت روی یک مخزن و ارائه‌ی شواهدی که بازبین بتواند عیناً آن‌ها را بازتولید کند.

صورت مسئله

میزکاری که در یک Google Doc، تاریخچه‌ی پیام‌ها و سه اسکریپت نصفه‌نیمه پراکنده باشد، میزکاری است که باید هر فصل از نو ساخته شود. چاره‌ی کار، یک بسته‌ی نسخه‌گذاری‌شده است: مخزن یا پوشه‌ای شامل سطوح تعامل، اسکیماتیک‌ها، اسکریپت‌ها و یک اسکریپت نصب تک‌دستوری.

در پایان این درس، بسته‌ی نهایی را در پوشه‌ی outputs/agent-workbench-pack/ روی دیسک تحویل می‌گیرید و با اسکریپت bin/install.sh آن را به هر مخزن مقصدی منتقل می‌کنید.

مفهوم

ساختار پوشه‌های بسته

outputs/agent-workbench-pack/
├── AGENTS.md
├── docs/
│   ├── agent-rules.md
│   ├── reliability-policy.md
│   ├── handoff-protocol.md
│   └── reviewer-rubric.md
├── schemas/
│   ├── agent_state.schema.json
│   ├── task_board.schema.json
│   └── scope_contract.schema.json
├── scripts/
│   ├── init_agent.py
│   ├── run_with_feedback.py
│   ├── verify_agent.py
│   └── generate_handoff.py
├── bin/
│   └── install.sh
└── README.md

چه چیزهایی داخل بسته می‌مانند و چه چیزهایی بیرون؟

داخل بسته:

• اسکیماتیک‌های سطوح تعامل: این‌ها قرارداد کار هستند.
• چهار اسکریپت بالا: این‌ها محیط اجرا به شمار می‌روند.
• چهار سند: این‌ها قوانین و شیوه‌نامه‌ی نمره‌دهی هستند.

بیرون بسته:

• تسک‌های خاص پروژه: جای تسک‌ها روی برد مخزن مقصد است، نه داخل این بسته.
• فراخوانی SDKهای شرکت‌های ارائه‌دهنده: بسته به هیچ فریم‌ورکی وابسته نیست.
• راهنماهای متنی آشناسازی اعضای جدید (onboarding): این بسته کنار فرآیند آشناسازی فعلی تیم قرار می‌گیرد، نه داخل آن.

نصب‌کننده

یک اسکریپت کوتاه در مسیر bin/install.sh (یا bin/install.py):

1. اگر بسته قبلاً نصب شده باشد، بدون فلگ --force از بازنویسی روی آن خودداری می‌کند.
2. بسته را داخل مخزن مقصد کپی می‌کند.
3. در صورت وجود پوشه‌ی .github/workflows/، تنظیمات CI را متصل می‌کند.
4. گام‌های بعدی را چاپ می‌کند: پر کردن برد، مشخص کردن دستورهای پذیرش و اجرای اسکریپت راه‌اندازی اولیه.

نسخه‌گذاری

این بسته یک فایل VERSION دارد. تغییرات در اسکیماتیک‌ها و اسکریپت‌ها که نیازمند مهاجرت داده‌ها (migration) باشند، شماره نسخه‌ی اصلی (major) را بالا می‌برند. تغییراتی که صرفاً به اسناد مربوط باشند، شماره نسخه‌ی تکه (patch) را تغییر می‌دهند. فایل agent_state.json در مخزن مقصد ثبت می‌کند که کارش را بر پایه‌ی کدام نسخه‌ی بسته شروع کرده است.

پیاده‌سازی از صفر

اسکریپت code/main.py این بسته را در مسیر outputs/agent-workbench-pack/ کنار همین درس سرهم می‌کند؛ با داده‌های اولیه‌ای متشکل از اسکیماتیک‌ها و اسکریپت‌های درس‌های قبلی این بخش و اسنادی که از قبل نوشته‌اید.

آن را اجرا کنید:

python3 code/main.py

اسکریپت، سطوح تعامل را کپی و نسخه‌ی آن‌ها را تثبیت می‌کند، فایل README را می‌نویسد، ساختار درختی بسته را چاپ می‌کند و با کد صفر خارج می‌شود. اجرای مجدد آن کاملاً پایا است و تداخلی ایجاد نمی‌کند.

الگوهای محیط عملیاتی در عمل

یک بسته تنها زمانی ارزش دارد که در برابر فورک‌ها، به‌روزرسانی‌ها و تغییرات ناسازگار مخزن اصلی تاب بیاورد. چهار الگو ضامن این موفقیت هستند:

فایل VERSION یک قرارداد است، نه یک ترفند بازاریابی. ارتقای نسخه‌ی اصلی نیازمند مهاجرت وضعیت است. ارتقای نسخه‌ی فرعی (minor) نیازمند اجرای مجدد بررسی‌کننده‌ها است. تغییرات تکه فقط به اسناد اختصاص دارند. نصب‌کننده در هر بار اجرا، فایل .workbench-version را در مخزن مقصد می‌نویسد؛ اگر فایل قفلِ مخزن مقصد با VERSION بسته همخوانی نداشته باشد، lint_pack.py از تحویل بسته خودداری می‌کند. npm، Cargo و pyproject.toml هم 10 سال تغییرات مداوم را با همین منطق مدیریت کرده‌اند؛ ورود ایجنت‌ها هم قوانین بازی را عوض نمی‌کند.

یک منبع واحد برای توزیع روی تمام ابزارها. تیم Nx فرمانی به نام nx ai-setup ارائه می‌دهد که فایل‌های AGENTS.md، CLAUDE.md، .cursor/rules/، .github/copilot-instructions.md و یک سرور MCP را از دل یک پیکربندی واحد می‌سازد. بسته‌ی شما هم باید همین رویه را پیش بگیرد؛ نصب‌کننده پیوندهای نمادین (symlinks) را ایجاد می‌کند (ln -s AGENTS.md CLAUDE.md) تا یک منبع واحد حقیقت در اختیار تمام ایجنت‌های کدنویسی قرار گیرد. فورک کردن بسته برای پشتیبانی از یک ابزار خاص در مقایسه با ابزاری دیگر، رویکردی اشتباه و محکوم به شکست است.

اسکریپت uninstall.sh که در مواجهه با وضعیت‌های مهم متوقف می‌شود. فرآیند حذف بسته نباید فایل‌های agent_state.json، task_board.json یا پوشه‌ی outputs/ کاربر را پاک کند. حذف‌کننده فقط اسکیماتیک‌ها، اسکریپت‌ها، اسناد و فایل AGENTS.md را حذف می‌کند (با گزینه‌ی اختیاری --keep-agents-md برای نگه‌داشتن آن) و اگر فایل‌های وضعیت تغییرات commitنشده داشته باشند، متوقف می‌شود. وضعیت متعلق به کاربر است؛ بسته مالکیتی روی آن ندارد.

مهارت به‌مثابه‌ی یک بسته‌ی قابل انتشار؛ توزیع به سبک SkillKit. این بسته در قالب یک مهارت SkillKit عرضه می‌شود: دستور skillkit install agent-workbench-pack آن را از یک منبع واحد روی 32 ایجنت هوش مصنوعی پیاده می‌کند. مخزن بسته، منبع واحد حقیقت و SkillKit کانال توزیع آن است. وابستگی به یک ارائه‌دهنده‌ی خاص از بین می‌رود و آن هفت سطح تعامل دست‌نخورده باقی می‌مانند.

استفاده از ابزارهای واقعی

این بسته را به سه روش می‌توان تحویل داد:

• به‌عنوان پوشه‌ای آماده که در یک مخزن کپی می‌شود: cp -r outputs/agent-workbench-pack /path/to/repo.
• به‌عنوان یک مخزن قالب (Template Repo) عمومی: با الگوی fork-and-customize، به‌طوری که VERSION مانع از انحراف و تغییرات کنترل‌نشده شود.
• به‌عنوان یک مهارت SkillKit: متصل به محصول ایجنتی شما، تا با یک دستور روی پروژه پیاده شود.

این بسته مثل یک دستور پخت است؛ هر بار نصب، یک وعده‌ی آماده از آن را به شما تحویل می‌دهد.

خروجی این درس

فایل outputs/skill-workbench-pack.md بسته‌ای متناسب با نیازهای پروژه تولید می‌کند: قوانینی که بر اساس سابقه‌ی تیم دقیق‌تر شده‌اند، الگوهای دامنه‌ای که با ساختار مخزن هماهنگ هستند، و ابعاد شیوه‌نامه‌ی نمره‌دهی که با یک مورد اختصاصیِ دامنه‌ی پروژه گسترش یافته‌اند.

تمرین‌ها

1. تصمیم بگیرید کدام سند پنجمِ اختیاری شایستگی ورود به بسته‌ی رسمی را دارد. از انتخاب خود دفاع کنید.
2. نصب‌کننده را با Python بازنویسی کنید و فلگ --dry-run را به آن بیفزایید. راحتی کار با آن را در مقایسه با bash بررسی کنید.
3. یک اسکریپت bin/uninstall.sh اضافه کنید که بسته را با ایمنی حذف کند و اگر فایل‌های وضعیت تاریخچه‌ی مهمی دارند، مانع حذف شود. چه مواردی تاریخچه‌ی مهم به حساب می‌آیند؟
4. اسکریپت lint_pack.py را بسازید تا در صورت هرگونه مغایرت بسته با فایل VERSION، خطا بدهد. آن را به CI مخزن خودِ بسته متصل کنید.
5. راهنمای گام‌به‌گام مهاجرت از یک میزکار دست‌ساز به این بسته را بنویسید. ترتیب عملیات برای به حداقل رساندن توقف کار چیست؟

تمرین شغلی: اثبات یک تغییر روی مخزن

دموی بسته‌بندی فقط نشان می‌دهد که اسکریپتِ سرهم‌کننده اجرا می‌شود و فایل‌ها را تولید می‌کند. این کار ثابت نمی‌کند ایجنت شما می‌تواند تسک جدیدی را به پایان برساند، یا اعتبارسنجی‌های تولیدشده درستی تسک را اثبات می‌کنند، یا سیستم مستقرشده کارایی دارد. این ادعاها را کاملاً از هم تفکیک کنید.

یک تسک کوچک و واقعی در مخزنی انتخاب کنید که مالک آن هستید یا اجازه‌ی تغییرش را دارید. از یک ایجنت کدنویسی استفاده کنید که در حال حاضر به آن دسترسی دارید. یک رفع باگ، قابلیتی با دامنه‌ی محدود، یا یک بهبود عملیاتی کفایت می‌کند؛ نیازی به نصب چند ایجنت مختلف نیست.

برای این کار یک نشست کاری جداگانه، فراتر از تمرین بسته‌بندی در نظر بگیرید. قالب ثبت شواهد را که پیوند آن در ادامه آمده، داخل پوشه‌ی learning-artifacts/ خود کپی کنید. قالب و بسته‌ی commitشده را به‌عنوان مرجع نگه دارید.

1. چارچوب تسک را مشخص کنید و سطح خودمختاری را برگزینید

از چارچوب تسک درس 43 و برنامه‌ی شواهد درس 44 استفاده کنید. نسخه‌ی شروع، هدف قابل مشاهده، مواردی که هدف نیستند (non-goals)، مسیرهای مجاز و شواهد پذیرش را ثبت کنید. کاربر یا اپراتور واقعی را که به این رفتار نیاز دارد، مشخص کنید.

یک حالت کاری انتخاب کنید: گام‌های هدایت‌شده، پیاده‌سازیِ همراه با چک‌پوینت، یا اجرای خودمختار محدود. توضیح دهید که چرا سطح نااطمینانی، پیامدها و برگشت‌پذیری کار، انتخاب شما را توجیه می‌کنند. یک ریفکتور محلیِ کوچک احتمالاً به چک‌پوینت‌های کمتری نسبت به تغییر در سیستم کنترل دسترسی نیاز دارد.

اگر ایجنت معیارهای مصرف را نشان می‌دهد، یک بودجه‌ی زمانی و سقف توکن یا هزینه تعیین کنید. اگر اندازه‌گیری این موارد ممکن نیست، صادقانه آن را ثبت کنید. یک شرط توقف برای خطاهای مکرر، درخواست دسترسی‌های جدید، اتمام بودجه یا تصمیمی مبهم در قرارداد کاری تعریف کنید؛ مشخص کنید چه کسی حق دارد درباره‌ی این شرط تصمیم بگیرد.

2. کوچک‌ترین محیط مفید را آماده کنید

کدهای پیاده‌سازی مرتبط، بخش‌های فراخواننده، تست‌ها و دستورالعمل‌های محلی را استخراج کنید. ثبت کنید که چرا هر منبع باید در کانتکست قرار بگیرد و چه شواهد به‌روزی می‌توانند یک یادداشت قدیمی را باطل کنند. کل مخزن را به‌صورت پیش‌فرض بارگذاری نکنید.

برای هر افزونه‌ی مرتبط، یک انتخاب صریح داشته باشید: مهارت یک رویه‌ی تکرارپذیر ارائه می‌دهد؛ ابزار MCP دسترسی ایجاد می‌کند؛ هوک بررسی قطعی انجام می‌دهد؛ پلاگین قابلیت‌ها را بسته‌بندی می‌کند. افزونه را فقط در صورتی نگه دارید که تسک واقعاً به آن نیاز داشته باشد و حداقل دسترسی‌های لازم را به آن بدهید.

هزینه‌ی کانتکست یا نگهداری یک مورد پیشنهادی را که رد کرده‌اید، ثبت کنید. یک دستورالعمل یا حافظه‌ی قدیمی را بازبینی کنید؛ اگر شواهد تایید کردند، آن را از محیط اختصاصی خود بازنشسته یا جایگزین کنید. بررسیِ مربوطه را دوباره اجرا کنید تا مطمئن شوید حذف آن باعث از دست رفتن محدودیتی ضروری نشده است.

3. خط مبنا را ثبت و پیاده‌سازی را آغاز کنید

قبل از اعمال تغییرات، نزدیک‌ترین بررسی موجود را اجرا کنید و وضعیت فعلی رفتار مورد نظر را نشان دهید. دستور، نسخه، نتیجه و مسیر شواهد را نگه دارید. حتی قابلیتی که هنوز وجود ندارد هم خط مبنا دارد: پاسخ دریافت‌شده یا عملیات پشتیبانی‌نشده را ثبت کنید.

اجازه دهید ایجنت در چارچوب قرارداد کار را پیاده کند. یک گزارش مداخله نگه دارید و علت هر اصلاح، تغییر دسترسی یا بازنگری در برنامه را ثبت کنید. واگذاری کار به ایجنت دیگر اختیاری است؛ در صورت نیاز، پیش از افزودن کارگر دیگر، قرارداد مالکیت و ادغام درس 45 را به کار بگیرید.

4. شواهد را به چالش بکشید

اثباتی را انتخاب کنید که سطح تغییریافته را ارزیابی کند. برای رابط کاربری، پروژه را از نو بسازید و مسیر کاربر را در عرض‌های مختلف صفحه بررسی کنید. برای API، درخواست و پاسخ سریالی‌شده را بسنجید. برای CLI، دستور ساخته‌شده را اجرا کرده و کد خروج و خروجی آن را کنترل کنید. بررسی‌های لازم برای تسک خود را انتخاب و محدودیت‌های آن‌ها را بیان کنید.

یک نتیجه‌ی مورد انتظار را مستقل از پیاده‌سازی ایجنت و بر اساس قرارداد تسک بنویسید. در یک نسخه‌ی موقت، عمداً یک خطای مشخص وارد کنید؛ مثلاً پذیرش یک مقدار نامعتبر یا حذف فیلدی اجباری از پاسخ. همان بررسی پذیرش را اجرا کنید: بررسی باید دقیقاً به همان دلیل با شکست مواجه شود.

اگر تست همچنان سبز ماند، پیش از اعتماد به آن، گزاره‌ی آزمون یا مشاهده را تقویت کنید. پیاده‌سازی درست را بازگردانید و تست را با موفقیت اجرا کنید. هر دو مدرک را نگه دارید. خطای نحوی (syntax error) یا خرابیِ راه‌اندازی تست، شناسایی رگرسیون محسوب نمی‌شود.

تغییرات نهایی (diff) را به‌همراه تست‌های تغییریافته، با هدف اولیه و مسیرهای مجاز مطابقت دهید. از یک طرف ارتباط یا در قالب یک نشست بازبینی جداگانه بخواهید ضعیف‌ترین اثبات را به چالش بکشد، بدون اینکه دست به کد پیاده‌سازی بزند. قضاوت نهایی همچنان با شما است؛ تایید یک ایجنت دیگر، شواهد اجرا به حساب نمی‌آید.

5. بهره‌برداری و بازیابی را تمرین کنید

دست‌سازه‌ی تغییریافته را در یک محیط محلی موقت یا محیط آزمایشی (staging) اجرا کنید. هر مشاهده را با برچسب local، staging یا live، همراه با نسخه‌ی دقیق یا شناسه‌ی دست‌سازه مشخص کنید. یک تمرین محلی فقط از یک ادعای محلی پشتیبانی می‌کند؛ برای این تمرین نیازی به استقرار روی محیط عملیاتی (production) نیست.

یک نشانه‌ی خطا مرتبط با تسک، یک آستانه، یک پنجره‌ی مشاهده و یک مسئول برای آن تعیین کنید. واکنش سیستم هنگام عبور از این آستانه را شرح دهید. این نشانه را در محیط تمرینی به‌شکلی ایمن فعال کنید و لاگ، متریک یا پاسخ مشاهده‌شده را ثبت نمایید.

بازگشت به عقب (rollback) به یک دست‌سازه‌ی سالم را تمرین کنید و مطمئن شوید رفتار قبلی بازگشته است. در صورت وجود داده‌های پایدار، آن‌ها را در نظر بگیرید؛ تعویض فایل باینری به‌تنهایی شاید تغییرات داده را بازنگرداند. هر گام بازیابی را که نتوانستید راستی‌آزمایی کنید، ثبت نمایید.

6. اجرای بعدی را بهبود دهید و کار را تحویل دهید

نتیجه را با خط مبنا مقایسه کنید؛ از جمله زمان سپری‌شده، داده‌های مصرف در دسترس و دخالت‌های انسانی. یک تسک فقط نشان می‌دهد روی همان تسک چه گذشته است؛ این موضوع ثابت نمی‌کند که یک ایجنت به‌طور کلی سریع‌تر یا قابل‌اعتمادتر است.

با استفاده از درس 46، یکی از اصلاحاتِ مشاهده‌شده را به یک تست، یک محدوده‌ی دسترسی کوچک‌تر، یک خودکارسازی یا مثالی واضح‌تر تبدیل کنید. بررسیِ تغییریافته را مجدداً اجرا نمایید. تغییرات موقت را حذف کنید و وضعیت شاخه‌ی نهایی، فایل‌های تغییریافته، ریسک‌های باقی‌مانده و اقدام بعدی را به‌صورت شفاف برای نشست کاری بعد به جا بگذارید.

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

از بازبین بخواهید فایل‌های شواهد را بررسی کند و حداقل ضعیف‌ترین بررسی پذیرش را بازتولید نماید. برای هر ردیف از وضعیت‌های demonstrated (اثبات‌شده)، needs revision (نیازمند بازنگری) یا unverified (تاییدنشده) همراه با ارجاع به شواهد و ذکر دلیل استفاده کنید. فیلدهای پرشده و اسکریپت‌های موفقِ بسته‌بندی، جایگزین این مشاهدات واقعی نمی‌شوند.

پیش از آنکه ادعای پایان تسک را مطرح کنید، موارد needs revision را برطرف نمایید. شواهدی را که در دسترس نیستند در وضعیت unverified بگذارید و دامنه‌ی ادعای خود را محدودتر کنید. این پورتفولیو، قضاوت مهندسی شما را روی یک تسک مشخص نشان می‌دهد؛ این مدرک تضمینی برای استخدام یا استقرار عملیاتی نیست.

دست‌سازه‌ی تحویلی

بسته‌ی قابل استفاده‌ی مجدد و نسخه‌ی تکمیل‌شده‌ی خود از فایل career-agent-evidence.md را نگه دارید. این قالب، چارچوب تسک، برنامه‌ی اجرا، رسیدهای محیط اجرا، بازبینی، تمرین بازیابی و تحویل کار را در قالب یک مطالعه‌ی موردی قابل ارزیابی به هم پیوند می‌دهد.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• بخش‌های 14 · 31 تا 14 · 41 — تمامی سطوح تعاملی که این بسته درون خود دارد
• SkillKit — نصب این مهارت روی 32 ایجنت هوش مصنوعی
• وبلاگ Nx: به ایجنت هوش مصنوعی خود یاد بدهید چطور در یک Monorepo کار کند — تولیدکننده‌ی منبع واحد برای شش ابزار مختلف
• agents.md — مشخصات باز — آنچه مسیریاب بسته‌ی شما باید پیاده‌سازی کند
• HKUDS/OpenHarness — پیاده‌سازی مرجع از یک معادل بسته
• Augment Code: یک فایل AGENTS.md خوب مثل ارتقای مدل است — استاندارد کیفی اسناد بسته
• Anthropic: بسترهای آزمایشی موثر برای ایجنت‌های بلندمدت
• Anthropic: طراحی بستر آزمایشی برای توسعه‌ی بلندمدت نرم‌افزار
• بخش 14 · 30 — توسعه‌ی ایجنت بر پایه‌ی ارزیابی که از درگاه راستی‌آزمایی بسته استفاده می‌کند
• بخش 14 · 41 — بنچمارک مقایسه‌ی قبل و بعد که این بسته عملکرد آن را بهبود می‌دهد