درون سازوکار AGENTS.md برای هدایت سلسله‌مراتبی عامل‌های هوش مصنوعی

تصور کنید یک برنامه‌نویس جاوا در یک پروژه عظیم با هزاران فایل کد، دیگر مجبور نباشد استانداردهای هر ماژول را دستی برای هوش مصنوعی کپی کند. با ادغام Spring AI و استاندارد باز AGENTS.md، حالا دستورالعمل‌های هر پوشه به‌طور خودکار توسط عامل‌های هوش مصنوعی شناسایی و اجرا می‌شوند.

به نقل از مستندات این پروژه، انتشار کتابخانه spring-ai-starter-agents-md مکانیزمی را فراهم کرده است که عامل‌های کدنویس را قادر می‌سازد بر اساس مسیر فایل فعلی، راهنمایی‌های خاص هر مخزن را کشف و اعمال کنند. این اقدام مستقیماً «شکاف پرامپت» (Prompting Gap) را هدف قرار می‌دهد؛ وضعیتی که در آن عامل‌های هوش مصنوعی (AI Agents) — شبیه دستیارهای تخصصی که هر کدام وظیفه خاصی دارند — بدون دریافت دستیِ زمینه (Context) محلی، از قوانین معماری هر پوشه بی‌خبرند. این مسئله در مخازن بزرگ‌مقیاس که در آن ماژول‌های مختلف نیازمند استانداردهای کدنویسی یا قوانین معماری متفاوتی هستند، یک نقطه اصطکاک جدی ایجاد می‌کند.

همان‌طور که در تحلیل‌های قبلی ما درباره‌ی پروتکل‌های زمینه مدل اشاره کردیم، استانداردسازی نحوه انتقال دانش به مدل‌ها، کلید خروج از پرامپت‌های طولانی و تکراری است. این رویکرد در راستای یکپارچه‌سازی رفتار عامل‌ها در مخازن کد است تا توسعه‌دهندگان بتوانند بدون تکرار دستورات، محیطی پیش‌بینی‌پذیر ایجاد کنند. بنیاد هوش مصنوعی عامل‌محور (Agentic AI Foundation یا AAIF) با ترویج AGENTS.md، روشی استاندارد برای ذخیره دستورالعمل‌ها مستقیماً در سیستم‌های کنترل نسخه (مانند Git) ارائه داده است.

انگیزه‌ها و اهداف پروژه

این پروژه با دو انگیزه و هدف اصلی پیش رفته است. نخست، نویسنده به عنوان یکی از سفیران AAIF، قصد داشت یک مشارکت عمومی ایجاد کند که مستقیماً به یکی از پروژه‌های این بنیاد متصل باشد تا به توسعه‌دهندگان دیگر کمک کند نحوه ساخت و کار با این استاندارد را درک کنند. در این میان، AGENTS.md بدیهی‌ترین و مناسب‌ترین انتخاب بود.

دوم، نویسنده در حال ساخت عامل‌های سفارشی و چارچوب‌های مدیریت عامل (Agent Harnesses) با استفاده از Spring AI است تا ابزارهایی مشابه "Claude" یا "Codex" خلق کند. هدف او این بود که از ایجاد فرمت‌های دستورالعمل کاملاً متفاوت برای هر عامل اجتناب کند. استاندارد AGENTS.md یک مشخصه ساده و باز را فراهم می‌کند که در محیط‌های مختلف به‌طور یکسان عمل می‌کند.

با قرار دادن یک فایل AGENTS.md در یک پروژه Spring و افزودن یک استارتر، یک ChatClient معمولی در Spring AI می‌تواند به عامل اجازه دهد تا دستورالعمل‌های صحیح مخزن را به‌طور خودکار بازیابی کند. ایده اصلی، پیوند دادن یک مکان پیش‌بینی‌پذیر برای دستورالعمل‌ها (AGENTS.md) با روشی سازگار و استاندارد برای توسعه‌دهندگان جاوا جهت ساخت برنامه‌های هوش مصنوعی (Spring AI) بود.

مکانیزم زمینه سلسله‌مراتبی

هسته این ادغام، یک CallAdvisor است که درخواست‌های Spring AI را رهگیری می‌کند. به جای استفاده از یک پرامپت جهانی و واحد، سیستم منطق «صلاحیت» (Jurisdiction) و «تجمع» (Accumulation) را بر اساس شفاف‌سازی‌های نسخه ۱.۱ استاندارد AGENTS.md پیاده می‌کند:

• صلاحیت: یک فایل AGENTS.md بر پوشه خودش و تمام زیرپوشه‌های موجود در آن حاکم است.
• تجمع: راهنمایی‌ها از ریشه مخزن (Root) به سمت پایین و تا فایل هدف جمع‌آوری می‌شوند. راهنمایی‌های کاربردی از پوشه‌های والد (Ancestor) به صورت تجمعی منتقل می‌شوند.
• اولویت: در صورت تضاد بین دو سند، دستورالعمل‌های نزدیک‌ترین پوشه به فایل هدف اولویت دارند. دستورالعمل‌های موجود در پوشه‌های هم‌سطح (Sibling) اعمال نمی‌شوند.
• جایگزینی: دستورات صریح کاربر همیشه بر راهنمایی‌های موجود در فایل‌ها برتری دارند و در اولویت اول قرار می‌گیرند.

برای مثال، اگر عاملی روی فایل repository/examples/steward/src/RepositoryTools.java کار کند، سیستم به سمت ریشه مخزن حرکت کرده و اسناد را به این ترتیب جمع‌آوری می‌کند: repository/AGENTS.md $ \rightarrow $ repository/examples/AGENTS.md $ \rightarrow $ repository/examples/steward/AGENTS.md. هر سند کامل در یک «پوشش زمینه» (Context Envelope) متعلق به فریم‌ورک حفظ می‌شود که اولویت‌ها را برای مدل توضیح می‌دهد.

پیاده‌سازی فنی

این کتابخانه به عنوان یک استارتر Spring Boot توزیع می‌شود و توسعه‌دهندگان می‌توانند با افزودن وابستگی زیر از آن استفاده کنند:

<dependency>
    <groupId>io.github.spring-ai-community</groupId>
    <artifactId>spring-ai-starter-agents-md</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

این ابزار به‌طور یکپارچه با ChatClient استاندارد ادغام می‌شود. پیکربندی خودکار (Auto-configuration) باعث می‌شود Advisor به Builder متصل شود، به این معنی که هیچ ثبت دستی برای Advisor در برنامه نیاز نیست. توسعه‌دهندگان صرفاً کلاینت را به روش معمول می‌سازند:

@Bean
ChatClient chatClient(ChatClient.Builder builder) {
    return builder.build();
}

از آنجا که کتابخانه با فایل‌های AGENTS.md به عنوان Markdown برخورد می‌کند، هیچ اسکیمای سخت‌گیرانه‌ای ابداع نمی‌کند. این سیستم تمام محتوای سند، شامل تیترها، لیست‌ها، جداول، بلوک‌های کد، فضاهای خالی و پایان خطوط را حفظ می‌کند تا کاربران بتوانند دستورالعمل‌ها را به هر روشی که برای پروژه‌شان مناسب است سازماندهی کنند.

زمانی که برنامه از پیش فایل هدف را می‌شناسد، می‌تواند به‌طور صریح از AgentsMdAdvisorParams.target(Path.of("...")) استفاده کند. علاوه بر این، ابزارهای سیستم فایل می‌توانند مسیری را که به آن دسترسی داشتند منتشر کنند و به Advisor اجازه دهند در دور بعدی حلقه ابزار (Tool Loop)، دستورالعمل‌ها را مجدداً تحلیل کند.

ایمنی و محدودیت‌ها

برای جلوگیری از تزریق پرامپت (Prompt Injection) — شبیه نفوذ یک دستور مخفی برای دور زدن قوانین — و پر شدن پنجره زمینه (Context Window) — که مثل میز کاری مدل است و فضای محدودی دارد — محدودیت‌های سخت‌گیرانه‌ای اعمال شده است. کتابخانه تضمین می‌کند که یک مخزن نتواند مقدار نامحدودی متن به هر درخواست مدل اضافه کند:

• حداکثر پوشه‌های بررسی‌شده: ۳۲ مورد (پیش‌فرض)
• حداکثر اسناد ترکیب‌شده: ۱۶ مورد (پیش‌فرض)
• حداکثر اندازه هر سند: ۶۴ کیلوبایت (پیش‌فرض)
• کل زمینه ترکیب‌شده: ۲۵۶ کیلوبایت (پیش‌فرض)

این محدودیت‌ها قابل پیکربندی هستند. مقادیر نامعتبر در هنگام پیکربندی باعث خطا می‌شوند تا از غافلگیری در زمان اجرا جلوگیری شود. یک سند بیش از حد بزرگ، به جای اینکه به‌طور بی‌صدا قطع (Truncate) شود، به‌طور کامل نادیده گرفته می‌شود. وقتی یک محدودیت لمس شود، ترکیب اسناد متوقف می‌شود در حالی که ترتیب «از گسترده‌ترین به نزدیک‌ترین» حفظ می‌گردد.

به‌طور حیاتی، برنامه از طریق یک رویداد AgentsMdLimitReachedEvent بازخورد دریافت می‌کند. این رویداد شامل هدف نرمال‌سازی شده، محدودیتی که لمس شده، تعداد اسناد پذیرفته شده، اندازه زمینه و محدودیت پیکربندی شده است (اما محتوای اسناد را شامل نمی‌شود). یک برنامه تعاملی می‌تواند از طریق @EventListener این موضوع را مدیریت کرده و به کاربر هشدار دهد که عامل با دستورالعمل‌های ناقص در حال فعالیت است:

@EventListener
void warnAboutAgentsMdLimit(AgentsMdLimitReachedEvent event) {
    System.err.printf(
        "AGENTS.md %s reached for %s; %d documents were applied.\n", 
        event.outcome(), event.target(), event.acceptedDocumentCount());
}

مشاهده‌پذیری و عیب‌یابی

یکی از بزرگترین موانع در جریان‌های کاری عامل‌محور، مشکل «جعبه سیاه» است؛ یعنی ندانستن اینکه آیا مدل به دلیل یک پرامپت بد شکست خورده یا به دلیل نبود یک دستورالعمل. این استارتر از Micrometer و سیستم لاگینگ Spring Boot استفاده می‌کند تا بدون افشای جزئیات حساس مخزن، قابلیت مشاهده فراهم کند:

• لاگینگ: در سطح DEBUG، سیستم مکان منبع انتخاب شده و تعداد کاراکترها را گزارش می‌کند. محتوای واقعی AGENTS.md هرگز در لاگ‌ها نوشته نمی‌شود.
• مشاهدات (Observations): در صورت در دسترس بودن ObservationRegistry، Advisor یک مشاهده متمرکز Micrometer با نام spring.ai.agents.md.advisor صادر می‌کند.
• تگ‌ها: این مشاهده تگ‌های document.state (موجود | خالی)، document.count (صفر | یک | متعدد) و resolution.outcome (کامل | محدودیت عمق | محدودیت سند | محدودیت اندازه) را ردیابی می‌کند.
• متریک‌ها: یک خلاصه توزیع مجزا با نام spring.ai.agents.md.context.size ثبت می‌کند که چه تعداد کاراکتر به پرامپت سیستم اضافه شده است. تگ‌ها با تعداد کم (Low-cardinality) نگه داشته می‌شوند و محتوای اسناد یا مسیر منابع هرگز به عنوان تگ استفاده نمی‌شوند.

اثبات مفهوم: Repository Steward

برای نمایش قدرت این استارتر، یک عامل کدنویسی تعاملی به نام Repository Steward با استفاده از Spring AI و Spring Shell 4.0.3 ساخته شد. Steward می‌تواند فایل‌ها را در یک فضای کاری محدود (Bounded Workspace) لیست، جست‌وجو و مطالعه کند.

معماری آن از یک جریان خاص پیروی می‌کند: دستور steward در Spring Shell $ \rightarrow $ ChatClient در Spring AI + حلقه ابزار $ \rightarrow $ AgentsMdSystemAdvisor (که دستورالعمل‌ها را برای مسیر فعال به‌روز می‌کند) $ \rightarrow $ ابزارهای سیستم فایل (listFiles, searchFiles, readFile) $ \rightarrow $ proposePatch $ \rightarrow $ پیشنهاد تغییر (ChangeProposal) در حالت انتظار $ \rightarrow $ دستورات show-change / apply-change $ \rightarrow $ نوشتن اتمیک در سیستم فایل.

ایمنی با حضور انسان (Human-in-the-Loop)

سیستم Steward برای امنیت به جای تکیه بر پرامپت، از محدودیت‌های سخت‌افزاری و کدنویسی شده در جاوا استفاده می‌کند:

• محدودسازی (Containment): مسیرها باید حتماً داخل فضای کاری پیکربندی شده باقی بمانند. مسیرهای مطلق، خروج با .. (Path Traversal)، لینک‌های نمادین (Symbolic Links) و پوشه‌های محافظت شده (مانند .git و target) رد می‌شوند.
• دسترسی محدود: عملیات خواندن، جست‌وجو، اندازه فایل‌ها، عمق پوشه‌ها و تعداد نتایج همگی دارای سقف هستند.
• نوشتن اتمیک: هوش مصنوعی می‌تواند یک وصله (Patch) را پیشنهاد دهد اما نمی‌تواند تغییرات خود را تایید کند. apply-change یک دستور Spring Shell است، نه یک ابزار مدل. یک انسان باید پیشنهاد را بررسی کرده و دستور را اجرا کند.
• محافظت در برابر تغییرات قدیمی (Stale-Change Protection): هر پیشنهاد، یک Digest (خلاصه) از فایل را ذخیره می‌کند. این Digest درست قبل از نوشتن اتمیک دوباره بررسی می‌شود. اگر فایل پس از بررسی پیشنهاد تغییر کرده باشد، عملیات نوشتن رد می‌شود.

شکاف قابلیت اطمینان مدل‌ها

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

بسیاری از مدل‌ها در این فراخوانی‌های ابزاری ساختاریافته و چندمرحله‌ای شکست خوردند: برخی پس از خواندن فایل متوقف شدند، برخی دیگر به جای فراخوانی واقعی ابزار، متنی شبیه JSON چاپ کردند و برخی دیگر شناسه‌های (ID) خیالی برای پیشنهادها ساختند. حتی یک مدل سعی کرد نام ابزار ثبت شده readFile را به read تغییر دهد که Spring AI به‌درستی آن را رد کرد. این چالش‌ها نشان می‌دهد که برای رسیدن به سطح صنعتی، باید قوانین مهندسی دقیقی برای تبدیل عامل‌ها به ابزارهای قابل‌اعتماد را پیاده کرد تا خطاهای مدل در حلقه‌های ابزاری به حداقل برسد.

تست روی سخت‌افزارهای بزرگ‌تر سرعت را بهبود بخشید اما مدل‌ها را قابل‌اطمینان‌تر نکرد. این ثابت می‌کند که یک عامل مخزن کد، نیازمند مدلی است که در حلقه‌های ابزاری بازگشتی (Recursive Tool Loops) تخصص استثنایی داشته باشد. این مثال بهترین مدرک برای کارکرد استارتر است و نشان می‌دهد که چگونه دستورالعمل‌ها با حرکت عامل در مخزن تغییر می‌کنند و تفاوت بین دستورالعمل‌های مدل و مرزهای ایمنی اعمال شده توسط برنامه چیست.

چرا این موضوع اهمیت دارد؟

این ادغام، مسئولیت مدیریت زمینه (Context Management) را از دوش کاربر و پرامپت‌های او به ساختار مخزن منتقل می‌کند. با تبدیل دستورالعمل‌ها به «کد»، تیم‌ها می‌توانند راهنمایی‌های هوش مصنوعی خود را تحت کنترل نسخه (Version Control) قرار دهند و تضمین کنند که هر عاملی — چه یک ساخت سفارشی Spring AI و چه یک ابزار شخص ثالث — از قوانین یکسانی پیروی می‌کند.

این رویکرد اجازه می‌دهد پروژه‌های تودرتو، زمینه‌های متمرکز خود را بدون تکرار دستورالعمل‌های ریشه ارائه دهند و تضمین کند که ادغام با Spring، حسی شبیه به یک تجربه بومی (Native) در اکوسیستم Spring دارد. این پروژه اکنون عمومی شده، مستند شده و آماده دریافت بازخورد است تا در نهایت به spring-ai-community منتقل شود.

گام بعدی شما

• اگر از Spring AI استفاده می‌کنید، کتابخانه spring-ai-starter-agents-md را برای مدیریت متمرکز دستورالعمل‌های تیم خود امتحان کنید.
• فایل‌های AGENTS.md را در ریشه و زیرپوشه‌های پروژه‌هایتان ایجاد کنید تا رفتار مدل‌های کدنویس را استاندارد کنید.
• در صورت استفاده از مدل‌های کوچک‌تر، محدودیت‌های Context را در تنظیمات استارتر برای بهینه‌سازی مصرف توکن‌ها تغییر دهید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.