بسیاری از تیم‌ها هنگام ساخت ایجنت‌های هوش مصنوعی با یک فایل قطور پر از توصیه‌های اخلاقی مثل «دقت کن» یا «پیش از ادغام، خوب تست کن» شروع میکنند. این توصیه‌ها شبیه اسناد راهنمای پرسنل جدید هستند؛ ایجنت‌ها بعد از چند نوبت گفت‌وگو یا به دلیل پر شدن پنجرهی کانتکست آن‌ها را نادیده می‌گیرند یا اساساً مرز مشخصی برای سنجش آن نصیحت‌ها ندارند. نتیجه، تحویل کدهای پر از باگ و ویرایش فایل‌های حساس است.
این درس به شما نشان می‌دهد چطور مرز میان هدایت مسیر و قوانین سفت‌وسخت را جدا کنید. با تبدیل قوانین مبهم به محدودیت‌های قابل اجرا و ماشین‌سنج در پنج دسته‌ی راهاندازی، اقدامات ممنوعه، تعریف اتمام کار، ابهام و تأیید انسانی، رفتار ایجنت را در زمان اجرا به تست‌های قطعی گره می‌زنید تا در خط لوله‌ی توسعه غافلگیر نشوید.
دستورالعمل‌هایی که به شکل نثر نوشته می‌شوند، صرفاً آرزو هستند. دستورالعمل‌هایی که در قالب محدودیت تعریف می‌شوند، تست به‌شمار می‌روند. میز کار (workbench) هر قانون را به چیزی تبدیل میکند که ایجنت در زمان اجرا (runtime) بررسی کند و بازبین بعد از اتمام کار، درستی‌اش را بسنجد.
اهداف یادگیری
- تفکیک متنِ مسیریابی از قوانین عملیاتی.
- بیان قوانین راهاندازی، اقدامات ممنوعه، تعریف اتمام کار (definition of done)، مدیریت ابهام و مرزهای تأیید در قالب محدودیت‌های ماشین‌سنج.
- پیاده‌سازی یک بررسی‌کننده‌ی قانون (rule checker) که اجرای ایجنت را بر اساس مجموعهقوانین ارزیابی و امتیازدهی کند.
- سازگار کردن مجموعهقوانین با diff تا بازبین بتواند تغییرات را به‌وضوح ببیند.
صورت مسئله
یک فایل معمولی AGENTS.md بیشتر شبیه مستندات توجیهی نیروهای تازه‌وارد (onboarding) است. به ایجنت می‌گوید «مراقب باش»، «کامل تست کن» و «اگر مطمئن نیستی بپرس». سه روز بعد، ایجنت تغییری را بدون هیچ تستی تحویل می‌دهد، در دایرکتوری ممنوعه‌ای فایل می‌نویسد و هرگز چیزی نمی‌پرسد؛ چون هیچ‌وقت مرزها را نمی‌دانسته است.
دستورالعمل‌ها وقتی عملیاتی باشند قدرتمندند و وقتی جنبه‌ی آرزو و نصیحت داشته باشند، ضعیف و ناکارآمدند. چاره‌ی کار نوشتن قوانینی است که میز کار بتواند تفسیرشان کند و بازبین هم بتواند به آن‌ها امتیاز بدهد.
مفهوم اصلی
جای قوانین در docs/agent-rules.md است، نه در مسیریاب (router) کوتاه ریشه. هر قانون یک نام، یک دستهبندی و یک تابع ارزیابی دارد.
پنج دستهبندی که بیشتر قوانین را پوشش میدهند
| دستهبندی | پرسشی که قانون به آن پاسخ می‌دهد | مثال |
|---|---|---|
| راهاندازی (Startup) | قبل از شروع کار، چه چیزی باید برقرار باشد؟ | «فایل وضعیت وجود داشته باشد و به‌روز باشد» |
| ممنوعه (Forbidden) | چه کاری هرگز نباید رخ دهد؟ | «اسکریپت scripts/release.sh را ویرایش نکن» |
| تعریف اتمام کار (Definition of done) | چه چیزی نشان می‌دهد کار کامل شده است؟ | «کد خروج pytest برابر 0 باشد و تست پذیرش پاس شود» |
| ابهام (Uncertainty) | ایجنت وقتی نامطمئن است چه میکند؟ | «به‌جای حدس زدن، یک یادداشت سوال ثبت کن» |
| تأیید (Approval) | چه چیزی به تأیید انسان نیاز دارد؟ | «هر وابستگی جدید، هرگونه نوشتن روی محیط پروداکشن» |
قانونی که در یکی از این پنج دسته جا نمی‌گیرد، معمولاً حاصل ادغام دو قانون است؛ بنابراین حتماً تفکیکش کنید.
قوانین ماشین‌خوان هستند
هر قانون یک اسلاگ (slug)، یک دستهبندی، یک خط توضیح و فیلدی به نام check دارد که نام تابعی را در rule_checker.py مشخص میکند. افزودن یک قانون یعنی افزودن یک تابع ارزیابی؛ در نتیجه، بررسیکننده همراه با میز کار رشد میکند.
قوانین با diff سازگارند
قوانین در یک فایل markdown واحد قرار دارند و هر قانون زیر یک سرتیتر مجزا می‌نشیند. تغییر نام‌ها در diffها کاملاً دیده می‌شوند. قوانین جدید در بالای دستهبندی خود می‌نشینند. قوانین کهنه هم حذف می‌شوند، نه اینکه کامنت شوند؛ زیرا مرجع حقیقت، میز کار است، نه لاگ گفت‌وگوهای مربوط به حس‌وحال اعضای تیم در فصل گذشته.
قوانین در برابر گاردریلهای فریمورک
گاردریلهای فریمورک (مانند گاردریلهای OpenAI Agents SDK یا وقفه‌های LangGraph) قوانین را در سطح محیط اجرا اعمال میکنند. مجموعهقوانین این درس، در واقع قرارداد خواندنی و بازبینی‌پذیر برای انسان است که آن گاردریلها پیاده‌سازیش میکنند. به هر دو نیاز دارید: محیط اجرا تخلف‌ها را حین یک نوبت گفت‌وگو شناسایی میکند و مجموعهقوانین هم ثابت میکند محیط اجرا کار درست را انجام می‌دهد.
افشای تدریجی: یک نقشه، نه یک دایره‌المعارف
دلیل رشد مداوم AGENTS.md این است که در هر حادثه قانونی به آن اضافه میشود، اما هیچ حادثه‌ای قانونی را حذف نمی‌کند. بعد از یک سال، فایل به 2000 خط می‌رسد و ایجنت هم فقط صفحه‌ی اول را می‌خواند، بودجه‌ی اتنشن (attention) آن تمام میشود و بر اساس بخش ناچیزی از دستورات عمل میکند. یک فایل دستورالعمل غول‌پیکر دقیقاً به همان دلیلی شکست می‌خورد که یک سند توجیهی 40 صفحه‌ای شکست می‌خورد: خواننده یک بار روزنامه‌وار نگاهش میکند و دیگر سراغ بخشی که واقعاً مهم بود نمی‌رود.
چاره‌ی کار کوچک‌تر کردن فایل نیست، بلکه لایه‌بندی آن است. مسیریاب ریشه آن‌قدر کوچک می‌ماند که در هر سشن به‌طور کامل خوانده شود و در آن جز اشاره‌گر چیزی قرار نمی‌گیرد. عمق کار در فایل‌های موضوعی قرار دارد و ایجنت تنها زمانی آن‌ها را بارگذاری میکند که کارش به آن موضوع مربوط شود. به ایجنت یک نقشه بدهید، نه کل دایره‌المعارف را؛ بگذارید خودش سراغ صفحه‌ای برود که نیاز دارد.
AGENTS.md # router, < 50 lines: what this repo is, where to look, the 5 hard rules
docs/
agent-rules.md # the full rule set (this lesson)
architecture.md # loaded when the task touches module boundaries
testing.md # loaded when the task writes or runs tests
deploy.md # loaded only for release work, gated behind an approval rule
feature_list.json # the backlog (Phase 14 · 36)| لایه | محل قرارگیری | زمان خواندن | بودجه‌ی حجم |
|---|---|---|---|
| مسیریاب | AGENTS.md |
در هر سشن، همیشه | کمتر از حدود 50 خط |
| قوانین | docs/agent-rules.md |
در هر سشن، هنگام راهاندازی | یک صفحه اسکرول به ازای هر دسته |
| اسناد موضوعی | docs/<topic>.md |
فقط وقتی تسک به آن موضوع می‌رسد | به میزان نیاز |
دو آزمون، ساختار لایه‌ای را دقیق و سالم نگه می‌دارند. آزمون دسترسی‌پذیری: ایجنت باید حداکثر با 2 گام لغزش (hop) از مسیریاب به هر قانونی برسد، بنابراین مسیریاب باید به هر سند موضوعی از طریق مسیر (path) لینک دهد، نه اینکه با توضیحات متنی آن را شرح دهد. آزمون تازگی: مسیریاب آن‌قدر کوتاه است که بازبین در هر PR دوباره آن را می‌خواند؛ همین ویژگی جلوی تبدیل بی‌صدای آن را به دایره‌المعارفی که جایش را گرفته بود می‌گیرد. اشاره‌گری که مقصدش نامعتبر باشد، شکستی بدتر از نبودن قانون است؛ بنابراین وجود لینکی خراب در مسیریاب، خودش تخلف از بررسی‌های راهاندازی به‌شمار می‌رود.
پیاده‌سازی از صفر
فایل code/main.py شامل بخش‌های زیر است:
- پارسر
agent-rules.mdکه قوانین را در یک dataclass لود میکند. - توابع بررسیکننده به سبک
rule_checker.py؛ یک تابع به ازای هر ارجاعcheck. - اجرای نمایشی یک ایجنت که دو قانون را نقض میکند، به‌همراه گام بررسی که این تخلفات را ثبت میکند.
اجرای آن:
python3 code/main.pyخروجی: مجموعهقوانین پارس‌شده، ردگیری محاسبات (trace) اجرا، وضعیت قبولی/ردی به ازای هر قانون، و یک فایل rule_report.json ذخیره‌شده در کنار اسکریپت.
الگوهای واقعی در محیط پروداکشن
سه الگو مجموعه‌قانونی را که یک فصل دوام می‌آورد، از مجموعه‌ای که ظرف یک هفته از کار می‌افتد جدا میکنند.
برچسب‌گذاری شدت در زمان نگارش. هر قانون برچسب severity دارد: block، warn یا info. بررسیکننده هر سه را گزارش میکند، اما محیط اجرا فقط جلوی block می‌ایستد. اغلب تیم‌ها در ابتدا شدت قوانین را بالا می‌برند و بعداً زیر فشار موعد تحویل بی‌سر‌و‌صدا آن‌ها را ضعیف میکنند؛ برچسب‌گذاری در زمان نوشتن باعث میشود کالیبراسیون از همان ابتدا به‌درستی انجام شود. این رویکرد را با گیت اعتبارسنجی (فاز 14 · درس 38) ترکیب کنید که هرگونه نادیده گرفتن قانون block را در یک لاگ حسابرسی overrides.jsonl ثبت و امضا میکند.
تاریخ انقضا به‌مثابه سازوکار الزام‌آور. هر قانون یک تاریخ expires_at دارد (پیش‌فرض 90 روز بعد از نگارش). اگر قانونی منقضی نشده باشد و در 60 روز متوالی هیچ تخلفی از آن ثبت نشود، بررسیکننده هشدار می‌دهد؛ در بازبینی فصلی بعدی، یا دلیلی برای نگه‌داشتنش ارائه میشود، یا سطح آن به info کاهش می‌یابد، یا حذف میشود. داده‌های بازبینی کد هوش مصنوعی در پروداکشن Cloudflare (آوریل 2026، با 131,246 اجرای بازبینی در 5,169 مخزن طی 30 روز) نشان داد مجموعه‌قوانینی که انقضای صریح داشتند زیر 30 قانون برای هر مخزن باقی ماندند؛ درحالی‌که مجموعه‌های بدون انقضا به بیش از 80 قانون رسیدند که بیشترشان هرگز اجرا نمی‌شدند.
مارک‌داون به‌عنوان مبدا، جیسون به‌عنوان کِش. فایل agent-rules.md فایلی است که نوشته و ویرایش میشود؛ agent-rules.lock.json کِشی است که بررسیکننده در مسیر اجرای سریع (hot path) می‌خواند. این فایل قفل با یک pre-commit hook دوباره تولید میشود. diffهای مارک‌داون به‌راحتی بررسی می‌شوند و پارس کردن مارک‌داون هم از هر نوبت گفت‌وگو بیرون می‌ماند، چون بررسیکننده فقط فایل کوچک JSON پیش‌ساخته را بارگذاری میکند. ساختاری دقیقاً مثل package.json / package-lock.json و Cargo.toml / Cargo.lock.
استفاده از ابزارهای واقعی
در محیط پروداکشن:
- ابزارهای Claude Code، Codex و Cursor قوانین را در شروع سشن می‌خوانند و موقع رد درخواست‌ها به آن‌ها ارجاع میدهند. بررسیکننده هم آن‌ها را دوباره در CI اجرا میکند تا جلوی تغییرات تدریجی و بی‌صدا (drift) را بگیرد.
- گاردریلهای OpenAI Agents SDK همین بررسی‌ها را به‌عنوان گاردریلهای ورودی و خروجی ثبت میکنند. مارک‌داون لایه‌ی اسناد است؛ SDK لایه‌ی زمان اجراست.
- وقفه‌های LangGraph زمانی که گره‌ای در حال اجرا قانونی را نقض کند فعال می‌شوند. مدیریت‌کننده‌ی وقفه قانون را می‌خواند، از انسان سوال می‌پرسد و سپس کار را از سر می‌گیرد.
مجموعهقوانین در هر سه مورد قابل‌استفاده است، چون فقط از مارک‌داون و نام توابع تشکیل شده است.
خروجی این درس
فایل outputs/skill-rule-set-builder.md با مالک پروژه مصاحبه میکند، دستورالعملهای متنی موجود را در پنج دسته می‌چیند، و یک agent-rules.md نسخه‌دار به‌همراه اسکلت کدهای بررسیکننده تحویل می‌دهد.
تمرین‌ها
- اگر محصول شما واقعاً نیاز دارد، دسته‌ی ششمی اضافه کنید. دلیل بیاورید که چرا نمی‌توان آن را در یکی از پنج دسته‌ی قبلی ادغام کرد.
- بررسیکننده را طوری توسعه دهید که هر قانون بتواند سطح شدت (
block،warn،info) داشته باشد و گزارش هم بر اساس آن تجمیع شود. - بررسیکننده را به CI وصل کنید: اگر در آخرین اجرای ایجنت، قانونی با شدت block نقض شد، بیلد باید fail شود.
- فیلد «تاریخ انقضا» به هر قانون بیفزایید. قانونی که 90 روز بدون هیچ خطایی بماند، باید وارد فرآیند بازبینی شود.
- یک فایل
AGENTS.mdواقعی پیدا کنید و آن را بر اساس قوانین پنج‌گانه بازنویسی کنید. چند خط از آن واقعاً عملیاتی بود؟ چند خط از جنس آرزو بود؟
اصطلاحات کلیدی
| اصطلاح | چیزی که افراد می‌گویند | معنای واقعی آن |
|---|---|---|
| قانون عملیاتی (Operational rule) | «یک دستورالعمل واقعی» | قانونی که میز کار بتواند در زمان اجرا آن را بررسی کند |
| قانون آرزویی (Aspirational rule) | «مراقب باش» | قانونی بدون تست مشخص؛ یا حذفش کنید یا ارتقایش دهید |
| تعریف اتمام کار (Definition of done) | «پذیرش» | سندی عینی و متکی به فایل که نشان می‌دهد کار تمام است |
| شدت توقف (Block severity) | «قانون سخت‌گیرانه» | نقض آن اجرا را متوقف میکند؛ بدون اپراتور نمی‌توان نادیده‌اش گرفت |
| انقضای قانون (Rule expiry) | «پاکسازی قوانین کهنه» | قانونی که پس از N روز تخلفی نداشته، آماده‌ی بازنشستگی است |
برای مطالعه‌ی بیشتر
- گاردریلهای OpenAI Agents SDK
- وقفه‌های LangGraph
- Anthropic، ساخت ایجنت‌های اثربخش
- ریک های‌تاور، Agent RuleZ: موتور پالیسی قطعی — شدت block/warn/info در پروداکشن
- کلودفلر، مدیریت بازبینی کد هوش مصنوعی در مقیاس بزرگ — 131 هزار اجرای بازبینی، درس‌هایی درباره‌ی ترکیب قوانین
- microservices.io، پلتفرم توسعه GenAI — بخش 1: گاردریلها — دفاع چندلایه میان قوانین و CI
- انطباق بررسی‌شده با سیستم تایپ: گاردریلهای قطعی (arXiv 2604.01483) — استفاده از Lean 4 به‌عنوان بالاترین حد تبدیل قانون به ارزیابی
- logi-cmd/agent-guardrails — پیاده‌سازی گیت merge: دامنه (scope)، تست جهش، بودجه‌ی تخلف
- فاز 14 · درس 32 — میز کار حداقلی که این مجموعهقوانین درونش قرار می‌گیرد
- فاز 14 · درس 38 — گیت اعتبارسنجی که گزارش قوانین را پردازش میکند
- فاز 14 · درس 39 — ایجنت بازبین که انطباق با قوانین را امتیازدهی میکند