تصور کنید تیمی از توسعه‌دهنداران هستید که هر تغییر کوچک در رفتار یک عامل هوش مصنوعی، آن‌ها را مجبور می‌کند ساعت‌ها رشته‌های متنی طولانی در دل کد پایتون را ویرایش کنند. اگر هنوز دستورالعمل‌های عامل‌های خود را به‌صورت سخت‌کد (Hard-coded) در پرامپت‌های سیستمی قرار می‌دهید، با یک «دیوار مقیاس‌پذیری» مواجه هستید؛ وضعیتی که در آن رشد پرامپت‌ها منجر به سقوط شدید خوانایی کد شده و مدیریت تیمی پروژه را غیرممکن می‌کند.
به نقل از وب‌سایت dev.to، در ۲ ژوئیه ۲۰۲۶ چارچوبی عملیاتی و مفصل معرفی شد که نشان می‌دهد چگونه می‌توان رفتار عامل‌ها را از منطق برنامه در سرویس‌های FastAPI جدا کرد و از فایل‌های قوانین اختصاصی برای این منظور استفاده نمود. این رویکرد، مشکل «پرامپت‌های متورم» (Bloated Prompts) را حل می‌کند، زیرا از فایل‌هایی بهره می‌برد که ابزارهایی مانند Claude Code، Cursor و OpenAI Agents SDK هنگام شروع به کار به‌طور خودکار بارگذاری می‌کنند. در این مدل، به‌جای به‌روزرسانی یک رشته متنی (String) در کدبیس، توسعه‌دهنده یک فایل متنی ساده را ویرایش می‌کند. این بدان معناست که هر تغییر رفتاری از طریق Git ردیابی می‌شود و بازرسی‌ها (Audits) و بررسی‌های همتا (Peer Reviews) را بسیار ساده می‌کند. این متدولوژی در واقع تکامل یافته‌ی رویکردهای سیستمی برای هم‌ترازی استانداردهای کدنویسی AI با معماری پروژه است که پیش‌تر برای محیط‌های توسعه بررسی شده بود.
همان‌طور که در تحلیل‌های پیشین ما درباره‌ی امنیت مدل‌های بازمتن اشاره کردیم، شفافیت در دستورالعمل‌ها اولین قدم برای جلوگیری از رفتارهای پیش‌بینی‌نشده است. در این معماری پیشنهادی، برای حفظ سازگاری، قوانین به سه سطح و نقش متمایز تقسیم می‌شوند:
- CLAUDE.md: توسط Claude Code CLI برای اعمال قراردادهای کدنویسی و تعریف عملیات‌های ممنوعه در کل کدبیس استفاده می‌شود.
- .cursorrules: مخصوص Cursor IDE طراحی شده است تا سبک تکمیل خودکار کد (Completions) و استایل تولید محتوا را هدایت کند.
- AGENTS.md: برای OpenAI Agents SDK طراحی شده تا قوانین سطح بالا را بین دسته‌ای از عامل‌ها (Multi-agent swarms) به اشتراک بگذارد.
برای یک پروژه معمولی FastAPI، توصیه می‌شود فایل CLAUDE.md در ریشه (Root) مخزن قرار گیرد. طبق مستندات این راهنما، این فایل باید استک فنی و محدودیت‌های عملیاتی صریح را به‌طور دقیق تعریف کند.
در جزئیات فنی، یک قالب استاندارد برای CLAUDE.md پیشنهاد شده است تا کیفیت بالای کد تضمین شود. این فایل باید محیط دقیق و استانداردهای کدنویسی را به شرح زیر بیان کند:
- تعاریف استک فنی: الزام استفاده از پایتون ۳.۱۲، FastAPI ۰.۱۱۵ و Pydantic v2. تمام پردازش‌های غیرهمزمان باید به‌صورت یکپارچه از طریق
async/awaitمدیریت شوند و استفاده از ماژولthreadingبه‌طور اکید ممنوع است. دسترسی به دیتابیس نیز باید محدود به نشست‌های غیرهمزمان (Async Sessions) در SQLAlchemy 2.0 باشد. - قراردادهای کدنویسی: تمامی نقاط انتهایی (Endpoints) باید در مسیر
src/api/v1/قرار گیرند. مدل‌های پاسخ (Response models) باید در پوشهschemas/تعریف شوند و به‌جای استفاده ازorm_mode=True(در نسخه‌های قدیمی)، از متدmodel_validate()استفاده شود. همچنین، استثناها (Exceptions) نباید مستقیماً باHTTPExceptionایجاد شوند، بلکه باید از طریق زیرکلاس‌هایAppErrorدر فایلsrc/exceptions.pyمدیریت گردند. - عملیات‌های ممنوعه: فراخوانی مستقیم توابع
os.system()یاsubprocessممنوع است. انجام عملیات‌های مستقیمDROPیاTRUNCATEبر روی دیتابیس‌های محیط عملیاتی (Production) ممنوع است و محتویات فایل.envهرگز نباید در لاگ‌ها چاپ شوند. - استانداردهای تست: هر نقطه انتهایی جدید باید یک تست pytest متناظر در مسیر
tests/api/داشته باشد. توسعه‌دهندگان باید به‌جایunittest.mockازmockerمربوط به کتابخانهpytest-mockاستفاده کنند. - محدودیت‌های خاص عامل: حداکثر توکن‌های مجاز برای فراخوانی ابزار (Tool call) روی ۴۰۹۶ تنظیم شده است. در صورتی که عامل در مورد اقدامی عدم قطعیت داشته باشد، باید حتماً از ابزار
ask_humanاستفاده کند. همچنین، هرگونه عملیات نوشتن (POST/PUT/DELETE) در APIهای خارجی نیازمند تأیید صریح کاربر است.
در بحث هماهنگی چندعاملی، زمانی که از OpenAI Agents SDK (v2) استفاده می‌شود، فایل AGENTS.md به عنوان لایه رفتاری مشترک برای زیر-عامل‌ها (Sub-agents) عمل می‌کند. منطق این فایل بر تعریف دقیق مرزها تمرکز دارد تا از «انحراف عامل» (Agent Drift) جلوگیری شود.
برای مثال، این چارچوب مرزهای نقش را به‌صورت صریح تعریف می‌کند: یک research_agent تنها به جمع‌آوری اطلاعات محدود است و از نوشتن فایل‌ها منع شده است؛ یک writer_agent فقط مجاز به تولید فایل‌های Markdown است و دسترسی به APIهای خارجی ندارد؛ و یک publish_agent تنها اجازه دارد محتوای تأییدشده را پست کند و انتشار خودکار پیش‌نویس‌ها (Drafts) برای او ممنوع است.
علاوه بر این، برای جلوگیری از شکست‌های هزینه‌بر یا ایجاد حلقه‌های بی‌نهایت (Infinite Loops)، حفاظ‌های عملیاتی سخت‌گیرانه‌ای اضافه شده است. این موارد شامل «قانون تشخیص حلقه» است که اگر یک ابزار سه بار متوالی فراخوانی شود، فرآیند را متوقف می‌کند. همچنین یک «سقف بودجه» تعریف شده که اگر هزینه یک تسک واحد از ۰.۱۰ دلار فراتر رود، پردازش را متوقف می‌سازد.
به باور نویسندگان این راهنما، فایل‌های قوانین نباید صرفاً «لیستی از نه» یا فهرستی از ممنوعیات باشند. اضافه کردن دلیل و منطق (Reasoning) پشت هر محدودیت — برای مثال ذکر اینکه حذف دیتابیس در محیط عملیاتی غیرقابل بازگشت است — به‌طور قابل توجهی نرخ پیروی عامل از قوانین را افزایش می‌دهد. این کار باعث می‌شود عامل از «اطاعت کورکورانه» به «پایبندی مبتنی بر بستر» (Context-aware adherence) برسد.
برای حفظ یکپارچگی و سلامت این فایل‌ها، سه استراتژی مدیریتی پیشنهاد می‌شود:
- یکپارچگی با Git: فایل‌های قانون باید در همان Pull Request (PR) همراه با تغییرات مربوط به کد ارسال شوند تا از عدم همزمانی (Desynchronization) بین مشخصات فنی و رفتار عامل جلوگیری شود.
- اعتبارسنجی CI: ادغام ابزار
markdownlintدر خط‌لوله‌های CI. این کار تضمین می‌کند که فضاهای خالی تصادفی یا ساختارهای لیست شکسته منجر به تفسیر غلط مدل‌های زبانی بزرگ (LLM) نشود — شبیه کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن جواب می‌دهد اما ممکن است یک علامت نادرست او را گمراه کند. - بازنویسی محلی (Overrides): استفاده از فایلی به نام
CLAUDE.local.md(که در.gitignoreقرار می‌گیرد) تا توسعه‌دهندگان بتوانند پیش‌فرض‌های تیمی را برای نیازهای شخصی خود بازنویسی کنند، بدون اینکه مخزن مشترک را آلوده سازند.
این رویکرد، مدیریت عامل‌ها را از یک تکلیف پیکربندی استاتیک به یک چرخه تکرارشونده تبدیل می‌کند. تیم‌ها می‌توانند با شروع از یک مجموعه قوانین حداقلی و افزودن محدودیت‌ها بر اساس گزارش‌های واقعی از شکست‌ها، قابلیت اطمینان عامل را بدون بازنویسی کد اصلی برنامه ارتقا دهند.
گام بعدی شما
- دستورالعمل‌های پراکنده در پرامپت‌های سیستمی خود را استخراج کرده و در یک فایل
.mdمتمرکز کنید. - برای هر محدودیت فنی در فایل قوانین، یک دلیل کوتاه (Reasoning) بنویسید تا نرخ خطای مدل کاهش یابد.
- ابزار
markdownlintرا به CI/CD خود اضافه کنید تا ساختار دستورات عامل‌ها همواره استاندارد بماند.
اما اثر این جداسازی بر روی سرعت استنتاج و هزینه توکن‌ها در مقیاس بالا، ابعاد دیگری دارد — به تحلیل ما درباره‌ی بهینه‌سازی هزینه‌های GPU مراجعه کنید.
گفتگو