هنگامی که یک ایجنت هوش مصنوعی کار خود را در یک نشست جدید شروع میکند، معمولاً رفتاری شبیه به توسعه‌دهنده‌ای تازه‌وارد دارد که بدون مطالعه‌ی مستندات وارد پروژه شده است: نسخه‌ی پایتون را حدس می‌زند، دستور اجرای تست‌ها را جستجو میکند، ساختار پوشه‌ها را بارها می‌خواند و در نهایت بسته‌ای را فراخوانی میکند که اصلاً نصب نشده است. این فرآیند علاوه بر تلف کردن زمان، هزاران توکن باارزش پنجره‌ی زمینه (Context Window) را پیش از اعمال هرگونه تغییر واقعی می‌سوزاند.
حل این معضل نیازمند تفویض بررسی‌های زیرساختی به یک اسکریپت راهاندازی (Init Script) سریع، قطعی و مستقل از هوش مصنوعی است. این اسکریپت پیش از شروع به کار ایجنت، سلامت محیط، متغیرهای محیطی، مسیرها و وابستگی‌ها را بررسی کرده و خروجی را در فایلی مشخص ذخیره میکند تا ایجنت مستقیماً سراغ اصل وظیفه برود.
اگر توسعه‌دهنده در محیطی کار کند که دسترسی به بسته‌ها یا سرویس‌ها پایدار نیست، کشف خطای نصب یا کمبود پیش‌نیاز در اواسط کار ایجنت هزینه‌ای چندبرابر خواهد داشت. بررسی پیش‌دستانه‌ی محیط به‌کمک آزمونهای محلی باعث می‌شود هر نقصی فوراً مشخص شود و بار اضافه به نشست تحمیل نگردد.
هر نشستی که بدون آمادگی اولیه (Cold start) شروع شود، تاوان دارد. ایجنت مدام فایل‌های تکراری را می‌خواند، آزمونهای مشابه را دوباره اجرا میکند و همان مسیرهای قبلی را از نو کشف میکند. یک اسکریپت راهاندازی (Init script) این هزینه را فقط یک بار می‌پردازد و پاسخ‌ها را درون وضعیت (State) ذخیره میکند.
اهداف یادگیری
- کارهایی را که ایجنت هرگز نباید در هر نشست از نو انجام دهد، شناسایی کنید.
- یک اسکریپت راهاندازی قطعی (Deterministic) بسازید که محیط اجرا، وابستگی‌ها و سلامت مخزن کد را ارزیابی کند.
- نتایج ارزیابی را ذخیره کنید تا ایجنت به‌جای اجرای مجدد بررسی‌ها، نتیجه را بخواند.
- هنگام شکست راهاندازی، با صدایی رسا، سریع و با ارائه‌ی یک نقطه‌ی مشخص برای بررسی خطا متوقف شوید (Fail loud).
صورت مسئله
نشستی را باز می‌کنید. ایجنت نسخه‌ی Python را حدس می‌زند. دستور اجرای تست‌ها را حدس می‌زند. پنج بار ریشه‌ی مخزن را فهرست میکند تا نقطه‌ی ورود برنامه را بیابد. بسته‌ای را فراخوانی میکند که اصلاً نصب نشده است. از کاربر می‌پرسد فایل تنظیمات کجاست. تا زمانی که ایجنت بخواهد اولین ویرایش واقعی را انجام دهد، 10000 توکن صرف کارهای اولیه‌ای شده که می‌شد همگی را در یک اسکریپت ساده خلاصه کرد.
راهکار، داشتن یک اسکریپت راهاندازی است؛ اسکریپتی که پیش از هر کار دیگری اجرا می‌شود و فایل init_report.json را می‌نویسد تا ایجنت در بدو شروع، آن را بخواند.
مفاهیم کلیدی
اسکریپت راهاندازی چه چیزهایی را بررسی میکند؟
| آزمون (Probe) | چرا اهمیت دارد؟ |
|---|---|
| نسخه‌های محیط اجرا | نسخه‌ی نادرست Python یا Node یعنی خطاهای پنهانی ناشی از ناسازگاری نسخه |
| در دسترس بودن وابستگی‌ها | هزینه‌ی پیدا نشدن یک بسته در ادامه، ده برابر شناسایی آن در همین لحظه است |
| دستور تست | ایجنت باید بداند چطور کارش را اعتبارسنجی کند؛ نبود این دستور یعنی میز کار خراب است |
| مسیرهای مخزن | مسیرهای هاردکدشده تغییر می‌کنند؛ آن‌ها را یک‌بار شناسایی و تثبیت کنید |
| متغیرهای محیطی | نبود OPENAI_API_KEY نقطه‌ی شکست است، نه یک معمای مبهم در زمان اجرا |
| تازگی وضعیت + بُرد وظایف | وضعیتِ کهنه و مانده از نشستی که کرش کرده، یک دام خطرناک است |
| آخرین کامیت سالم تاییدشده (LKG) | نقطه‌ی اتکا برای مقایسه‌ی تغییرات (Diff) در پایان نشست و هنگام تحویل کار |
با صدایی رسا، سریع و در یک نقطه‌ی مشخص متوقف شوید
شکست در هر آزمون یعنی توقف کامل و ارجاع موضوع به انسان. جمله‌ی «خود ایجنت راهش را پیدا میکند» اینجا جایی ندارد. اصلاً تمام هدف راهاندازی این است که وقتی میز کار خراب است، از شروع کار جلوگیری کند.
خاصیت بی‌اثر بودن تکرار (Idempotent)
اسکریپت را دو بار پشت سر هم اجرا کنید. اجرای دوم، به‌جز به‌روزرسانی برچسب زمانی (Timestamp)، نباید هیچ تغییر دیگری در سیستم ایجاد کند. همین ویژگی تکرارپذیری بدون عوارض جانبی است که اجازه میدهد اسکریپت را در CI، هوک‌ها یا دستورات خط فرمان قبل از تسک قرار دهید.
تفاوت اسکریپت راهاندازی با قوانین شروع کار
قوانین (فاز 14 · 33) تعیین می‌کنند چه شرایطی باید برقرار باشد تا بتوان اقدامی انجام داد. راهاندازی اسکریپتی است که اطمینان میدهد این قوانین واقعاً قابل بررسی هستند یا نه. قوانین بدون اسکریپت راهاندازی، صرفاً در حد توصیه‌ی «مراقب باش» باقی می‌مانند. راهاندازی بدون قوانین هم فقط شکستی پر زرق‌وبرق رقم می‌زند.
پیاده‌سازی از صفر
فایل code/main.py اسکریپت init_agent.py را پیاده‌سازی میکند:
- پنج آزمون: نسخه‌ی Python، وابستگی‌های ثبت‌شده از طریق
importlib.util.find_spec، در دسترس بودن دستور تست، متغیرهای محیطی الزامی، و تازگی فایل وضعیت. - هر آزمون مقادیر
(name, status, detail)را برمی‌گرداند. - این اسکریپت فایل
init_report.jsonرا با مجموعه‌ی کامل نتایج می‌نویسد و اگر آزمونی با سطح بحرانی مسدودکننده (Block) شکست بخورد، با خروجی غیر صفر خارج می‌شود.
اجرای آن:
python3 code/main.pyاسکریپت جدول آزمون‌ها را چاپ میکند، init_report.json را می‌نویسد و در صورت موفقیت با کد صفر و در صورت بروز خطا همراه با فهرستی از آزمونهای ناموفق با کدی غیر صفر خارج می‌شود.
الگوهای محیط عملیاتی در دنیای واقعی
سه الگو وجود دارد که یک اسکریپت راهاندازی کاربردی را از یک کار تشریفاتی و بیهوده متمایز میکند:
تثبیت بر پایه‌ی آخرین کامیت سالم تاییدشده. کامیت فعلی را با فایل LKG که در آخرین merge موفق ثبت شده مقایسه کنید. اگر تفاوت (Diff) از حد مجاز فراتر رفت (به‌طور پیش‌فرض 50 فایل)، از شروع کار خودداری کرده و تایید خط مبنای (Baseline) جدید را به یک انسان واگذار کنید. این همان روشی است که سیستم بررسی کد مبتنی بر هوش مصنوعی Cloudflare برای تعیین دامنه‌ی (scope) ایجنت‌های بازبین به کار می‌برد: هر نشست بازبینی به همان آخرین کامیت سالم متکی است و هرگز انحراف‌ها را در طول نشست‌ها انباشته نمی‌کند.
فایل‌های قفل به همراه زمان اعتبار (TTL). پس از اولین گذر موفق آزمون‌ها، یک فایل prereqs.lock بسازید. در اجراهای بعدی، برای N ساعت (به‌طور پیش‌فرض 24 ساعت) به این فایل اعتماد کنید و آزمونهای سنگین را نادیده بگیرید. اسکریپت راهاندازی ابتدا فایل قفل را بررسی میکند؛ اگر معتبر بود و هش مانیفستِ (Manifest) وابستگی‌ها مطابقت داشت، مسیر را کوتاه میکند. این همان الگویی است که Docker برای کش لایه‌ها استفاده میکند: آزمون تکرارپذیر + هش محتوا = عبور بدون پردازش اضافه.
بدون شبکه، بدون LLM، بدون غافلگیری در مسیر اصلی. آزمونهای راهاندازی، زیرساخت‌هایی کاملاً قطعی و پیش‌بینی‌پذیر هستند. آزمونی که برای تحلیل یک خطا LLM فراخوانی کند یا برای بررسی لایسنس سراغ سرویسی خارجی برود، دیگر آزمون نیست؛ بلکه یک جریان کاری مستقل است. اگر اجرای آزمایشی (Dry run) یک آزمون بیشتر از 3 ثانیه طول بکشد، نشانه‌ی مشکل در میز کار است؛ باید آن را از اسکریپت راهاندازی خارج کنید یا نتیجه‌اش را کش نمایید.
استفاده از ابزارهای واقعی
در محیط عملیاتی:
- هوک‌های Claude Code. هوک
pre-taskاسکریپت راهاندازی را فراخوانی میکند و در صورت شکست آن، اجازه‌ی اجرای ایجنت را نمی‌دهد. - گیت‌هاب اکشنز (GitHub Actions). جاب
setup-agentاسکریپت راهاندازی را اجرا میکند و جاب ایجنت به پایان موفقیت‌آمیز آن وابسته می‌شود. - نقطه‌ی ورود داکر (Docker entrypoint). کانتینر ایجنت قبل از اجرای محیط اجرای (Runtime) ایجنت، اسکریپت راهاندازی را اجرا میکند؛ لاگ‌ها در صورت خرابی فوراً نمایش داده می‌شوند.
این اسکریپت راهاندازی کاملاً مستقل و قابل‌حمل است، چرا که به فریم‌ورک خاصی وابسته نیست. می‌توانید آن را درون Bash، Make یا فایل‌های Task قرار دهید.
خروجی این درس
فایل outputs/skill-init-script.md وضعیت پروژه را ارزیابی میکند، کارهای آماده‌سازی آن را در قالب چند آزمون دسته‌بندی می‌نماید و یک فایل init_agent.py اختصاصی همراه با ورک‌فلوی CI برای اجرای آن پیش از مراحل ایجنت تولید میکند.
تمرین‌ها
- آزمونی اضافه کنید که تفاوت کامیت فعلی با آخرین کامیت سالم تاییدشده را بسنجد و در صورتی که بیش از 50 فایل تغییر کرده بود، مانع از شروع کار شود.
- اسکریپت را طوری تنظیم کنید که فایل
prereqs.lockرا بسازد و اگر عمر این قفل بیش از 7 روز بود، از شروع به کار جلوگیری کند. - فلگ
--fixرا اضافه کنید تا وابستگی‌های محیط توسعه به‌طور خودکار نصب شوند، اما هرگز وابستگی‌های زمان اجرا بدون تایید کاربر دستکاری نشوند. - آزمون‌ها را از توابع هاردکدشده به یک رجیستری YAML منتقل کنید. مزایا و معایب این کار را توضیح دهید.
- برای هر آزمون بودجه‌ی زمانی تعیین کنید. آزمونی که بیش از 3 ثانیه زمان ببرد، نشانه‌ی ضعف در ساختار میز کار است.
اصطلاحات کلیدی
| اصطلاح | در گفتار عمومی | معنای دقیق فنی |
|---|---|---|
| آزمون (Probe) | «یک بررسی ساده» | تابعی قطعی که مقادیر (name, status, detail) را برمی‌گرداند |
| گزارش راهاندازی (Init report) | «خروجی مرحله‌ی ستاپ» | فایلی با فرمت JSON در کنار فایل وضعیت که نتایج آزمون‌ها را نگه می‌دارد |
| بی‌اثر در تکرار (Idempotent) | «قابل اجرای دوباره بدون خطر» | دو بار اجرای متوالی، نتیجه‌ی یکسانی تولید کند و صرفاً برچسب زمانی تغییر کند |
| توقف با صدای رسا (Fail loud) | «خطا را لاپوشانی نکن» | توقف فوری و نمایش صریح به انسان؛ بدون راهکارهای جایگزینِ خاموش |
| تاوان آماده‌سازی (Setup tax) | «هزینه‌ی تخمین اولیه (بوت‌استرپ)» | توکن‌هایی که ایجنت در ابتدای هر نشست هدر میدهد تا بدیهیات را دوباره کشف کند |
برای مطالعه‌ی بیشتر
- Anthropic, Effective harnesses for long-running agents
- GitHub Actions, composite actions for setup
- microservices.io, GenAI dev platform: guardrails — بررسی‌های pre-commit و CI در قالب راهاندازی اولیه
- Augment Code, How to Build Your AGENTS.md (2026) — انتظارات راهاندازی
- Codex Blog, Codex CLI Context Compaction — آغاز نشست به عنوان راهاندازی آگاه از فشرده‌سازی زمینه
- فاز 14 · 33 — مجموعه‌قوانینی که این اسکریپت امکان اجرای آن‌ها را فراهم میکند
- فاز 14 · 34 — فایل وضعیتی که این اسکریپت داده‌های اولیه‌اش را ثبت میکند
- فاز 14 · 38 — گیت اعتبارسنجی که از اسکریپت راهاندازی تغذیه می‌شود
- فاز 14 · 40 — فرآیند تحویل کار که از آخرین کامیت سالم ثبت‌شده در گزارش راهاندازی استفاده میکند