وقتی پروژه‌ای بزرگ می‌شود، بسیاری از توسعه‌دهندگان تلاش می‌کنند با نوشتن فایلهای حجیم و چند هزار خطیِ راهنما، رفتار ایجنت‌های کدنویسی را کنترل کنند. نتیجه معمولاً ناامیدکننده است: مدل زبان طبیعی بخش زیادی از متن را نادیده میگیرد، با تمام شدن پنجره‌ی کانتکست سوابق را فراموش می‌کند و کارهای نیمه‌کاره را در نشستهای بعدی از دست می‌دهد.
راه‌حل این چالش، پیچیده‌تر کردن پرامپت‌ها نیست؛ بلکه پیاده‌سازی یک معماری حداقلی و ساختاریافته است. در این درس یاد می‌گیرید که چگونه با تنها 3 فایل—یک مسیریاب ریشهای (Router)، یک فایل وضعیت (State) و یک صف تسک‌ها (Task Board)—یک میز کار پایدار و سبک بسازید که بین ابزارهای مختلف مثل Cursor و Claude Code قابل حمل باشد و اتکا به تاریخچهی ناپایدار چت را از بین ببرد.
کوچک‌ترین میز کار کاربردی تنها از سه فایل تشکیل می‌شود: یک مسیریاب ریشه‌ایِ دستورالعمل‌ها، یک فایل وضعیت، و یک تابلوی تسک‌ها. هر چیز دیگری روی همین‌ها سوار می‌شود. اگر مخزنی نتواند این سه فایل را نگه‌داری کند، هیچ مدلی نجاتش نخواهد داد.
اهداف یادگیری
- تعریف سه فایلی که کمینه‌ی میز کار کاربردی را می‌سازند.
- توضیح این‌که چرا یک مسیریاب ریشه‌ایِ کوتاه از یک فایل یکپارچه و طولانی
AGENTS.mdبهتر عمل می‌کند. - ساخت یک فایل وضعیت که ایجنت بتواند در هر نوبت گفت‌وگو بخواند و در پایان به‌روزرسانی کند.
- ساخت یک تابلوی تسک‌ها که کار در چندین نشست کاری را بدون تاریخچهی چت زنده نگه دارد.
صورت مسئله
بیشتر تیم‌ها کار را با نوشتن یک فایل AGENTS.md سه‌هزارخطی شروع می‌کنند و فکر می‌کنند کار تمام است. مدل آن را بارگذاری می‌کند، بخش‌هایی را که نمی‌تواند خلاصه کند نادیده میگیرد، و در نهایت باز هم در همان جاهایی شکست می‌خورد که همیشه شکست می‌خورد.
شما به نقطه‌ی مقابل این رویکرد نیاز دارید: یک فایل ریشهای بسیار کوچک که ایجنت را فقط در صورت لزوم به فایلهای عمیقتر هدایت کند؛ یک وضعیت پایدار (Durable state) که ایجنت پیش از اقدام بخواند و پس از اقدام در آن بنویسد؛ و یک تابلوی تسک‌ها که مشخص کند چه کاری در جریان است، چه چیزی مسدود شده و تسک بعدی چیست.
سه فایل. هر کدام با وظیفه‌ای مشخص. هر کدام به‌اندازه‌ی کافی ماشین‌خوان، تا بعداً بتواند به سیستمی واقعی تکامل پیدا کند.
مفاهیم پایه
فایل AGENTS.md یک مسیریاب است، نه دفترچه‌ی راهنما
یک فایل AGENTS.md خوب، کوتاه است. این فایل ایجنت را به این بخش‌ها ارجاع می‌دهد:
- فایل وضعیت (اکنون کجای کار هستید).
- تابلوی تسک‌ها (چه کارهایی باقی مانده است).
- قوانین عمیقتر (زیرمسیر
docs/agent-rules.md). - دستور اعتبارسنجی (چطور متوجه شویم کار درست انجام شده است).
هر نکته‌ی طولانی‌تری باید به مستندات عمیقتر برود و تنها در صورت نیاز بارگذاری شود. راهنماهای طولانی نادیده گرفته می‌شوند؛ اما مسیریاب‌های کوتاه رعایت می‌شوند.
فایل agent_state.json مرجع رسمی سوابق است
وضعیت شامل این موارد است: شناسه‌ی تسک فعال، فایلهای دستخورده، فرضیات در نظر گرفته‌شده، موانع و اقدام بعدی. ایجنت این فایل را در هر نوبت گفت‌وگو می‌خواند. نشست بعدی هم به‌جای بازپخش چت، همین فایل را مطالعه می‌کند.
وضعیت در قالب یک فایل ذخیره می‌شود، چون تاریخچهی چت قابل اعتماد نیست. نشست‌ها بسته می‌شوند و مکالمات خلاصه یا کوتاه می‌شوند؛ اما فایل سر جای خود می‌ماند.
فایل task_board.json همان صف کاری است
تابلوی تسک‌ها تمام کارها را با یکی از وضعیت‌های todo | in_progress | done | blocked نگه میدارد. وقتی وضعیت خالی است، ایجنت کار بعدی را از این صف برمی‌دارد؛ هر زمان هم که بخواهید بدانید آیا ایجنت در مسیر درست پیش می‌رود یا نه، همین صف را بررسی می‌کنید.
هر تسک روی تابلو یک شناسه، یک هدف، یک مسئول (builder، reviewer یا human) و معیارهای پذیرش دارد. کوچک بودن این تابلو تعمدی است: اگر حجم آن از یک صفحه فراتر برود، مشکل شما در برنامه‌ریزی است، نه در ساختار تابلو.
سه فایل، کفِ کار است نه سقف آن
در درس‌های آینده مواردی مثل قراردادهای دامنه (Scope contracts)، اجراکننده‌های بازخورد، درگاه‌های اعتبارسنجی، چک‌لیست‌های مرور و بسته‌های تحویل کار به این الگو اضافه می‌شوند. همه‌ی این مباحث بر پایه‌ی همین سه فایل اولیه بنا شده‌اند.
پیاده‌سازی از صفر
اسکریپت code/main.py این میز کار کمینه را در یک مخزن خالی می‌سازد و یک نوبت گفت‌وگوی ایجنت را نمایش می‌دهد که:
- فایل
agent_state.jsonرا می‌خواند. - اگر وضعیت خالی بود، تسک بعدی را از
task_board.jsonبرمی‌دارد. - یک فایل منفرد درون دامنه را دستکاری می‌کند.
- وضعیت به‌روزشده را دوباره ذخیره می‌کند.
اجرای اسکریپت:
python3 code/main.pyاین اسکریپت پوشه‌ی workdir/ را در کنار خود ایجاد می‌کند، سه فایل را درون آن می‌گذارد، یک نوبت کاری را اجرا می‌کند و تفاوت‌ها (Diff) را نمایش می‌دهد. با اجرای مجدد، خواهید دید که نوبت دوم کار را دقیقاً از نقطه‌ی پایان نوبت اول ادامه می‌دهد.
استفاده در ابزارهای واقعی
در ابزارهای عملیاتی ایجنت‌محور، همین سه فایل با نام‌های متفاوتی ظاهر می‌شوند:
- Claude Code: فایل
AGENTS.mdیاCLAUDE.mdنقش مسیریاب، فضاهای ذخیره‌سازی مانند.claude/state.jsonنقش وضعیت، و قلاب‌ها (Hooks) نقش تابلو را بازی می‌کنند. - Codex / Cursor: قوانین فضای کاری (Workspace rules) نقش مسیریاب، حافظه‌ی نشست (Session memory) نقش وضعیت، و تسک‌های صف‌بندی‌شده در نوار کناری چت نقش تابلو را دارند.
- ایجنت سفارشی پایتون: دقیقاً همین فایل‌هایی که نوشتید.
نام‌ها تغییر می‌کنند؛ اما ساختار دست‌نخورده باقی می‌ماند.
الگوهای محیط تولید در عمل
این میز کار کمینه زمانی در برابر مواجهه با مونو‌ریپوهای واقعی دوام می‌آورد که سه الگو روی آن سوار شوند. این الگوها مستقل هستند؛ هر کدام را که نیاز واقعی مخزن شماست انتخاب کنید.
فایلهای تودرتوی AGENTS.md با اولویت نزدیک‌ترین فایل. شرکت OpenAI تعداد 88 فایل AGENTS.md مختلف در سراسر مخزن اصلی خود دارد؛ یعنی برای هر زیرمؤلفه یک فایل. ابزارهای Codex، Cursor، Claude Code و Copilot مسیر فایل کاری را تا ریشه‌ی مخزن بالا می‌روند و تمام فایلهای AGENTS.md موجود در مسیر را با هم ترکیب می‌کنند. فایلهای درون زیرپوشه‌ها، فایل ریشه را بسط میدهند. Codex فایلی به نام AGENTS.override.md برای جایگزین کردن فایل ریشه (به‌جای بسط دادن آن) اضافه کرده است؛ اما این سازوکار مختص Codex است و بهتر است برای کارهای چندابزاری از آن دوری کنید. بررسی‌های شرکت Augment Code نکته‌ی کلیدی را مشخص می‌کند: بهترین فایلهای AGENTS.md جهشی در کیفیت ایجاد می‌کنند که معادل ارتقای مدل از Haiku به Opus است؛ درحالی‌که فایلهای ضعیف، خروجی را حتی از حالتی که اصلاً فایلی وجود ندارد هم بدتر می‌کنند.
ضدالگوهایی که حتی با وجود ظاهرِ کامل باید رد شوند. دستورالعمل‌های متناقض بی‌صدا ایجنت را از حالت تعاملی خارج و به حالت حریصانه (Greedy) می‌برند (در بنچمارک ICLR 2026 AMBIG-SWE نرخ حل مسئله از 48.8% به 28% سقوط کرد)؛ اولویت‌ها را شماره‌گذاری کنید و آن‌ها را به‌شکل یک‌دست و بدون سلسله‌مراتب روی هم نچینید. قوانین غیرقابل‌سنجش سبک کدنویسی (مثل «پیروی از راهنمای سبک پایتون گوگل») بدون هیچ دستور اجرایی مشخص، دست ایجنت را باز می‌گذارند تا تطابق را از خودش ابداع کند؛ در کنار هر قانون نگارشی، دستور دقیق لینتر (Linter) را بیاورید. آوردن قواعد نگارشی در ابتدا به‌جای دستورها، مسیر اعتبارسنجی را مدفون می‌کند؛ همیشه اول دستورها، در آخر سبک کدنویسی. نوشتن متن برای انسان به‌جای ایجنت، بودجهی کانتکست را هدر می‌دهد؛ مختصرنویسی در اینجا یک مزیت است.
پیوندهای نمادین (Symlinks) بین‌ابزاری. داشتن یک فایل ریشهای واحد با پیوندهای نمادین (ln -s AGENTS.md CLAUDE.md، ln -s AGENTS.md .github/copilot-instructions.md، ln -s AGENTS.md .cursorrules) تمام ایجنت‌های کدنویسی را روی یک منبع واحدِ حقیقت نگه میدارد. ابزار nx ai-setup از فریم‌ورک Nx این فرآیند را روی Claude Code، Cursor، Copilot، Gemini، Codex و OpenCode از طریق یک پیکربندی واحد خودکار می‌کند.
خروجی نهایی
فایل outputs/skill-minimal-workbench.md این میز کار سه‌فایلی را برای هر مخزن جدید تولید می‌کند: یک مسیریاب AGENTS.md تنظیم‌شده برای پروژه، یک agent_state.json با کلیدهای درست، و یک task_board.json که با کارهای معوق فعلی پروژه پر شده است.
تمرین‌ها
- یک برچسب زمانی
last_runبهagent_state.jsonاضافه کنید. اگر عمر فایل بیش از 24 ساعت بود، اجرای برنامه را تا زمان تأیید اپراتور متوقف کنید. - فیلد
priorityرا به تابلوی تسک‌ها اضافه کنید و سازوکار واکشی را طوری تغییر دهید که همیشه تسکtodoبا بالاترین اولویت را بردارد. - فایل
task_board.jsonرا به فرمت JSON Lines منتقل کنید تا هر تسک در یک خط قرار بگیرد و تغییرات در کنترل نسخه (Version Control) شفاف ثبت شوند. - یک اسکریپت
lint_workbench.pyبنویسید که اگر حجمAGENTS.mdبیش از 80 خط بود یا به فایلی ارجاع می‌داد که وجود خارجی ندارد، با خطا متوقف شود. - بررسی کنید از دست دادن کدام‌یک از این سه فایل بیشترین آسیب را می‌زند. از پاسخ خود دفاع کنید.
اصطلاحات کلیدی
| اصطلاح | در گفتار عامیانه | معنای دقیق فنی |
|---|---|---|
| مسیریاب (Router) | AGENTS.md |
فایل ریشهای و کوتاهی که ایجنت را به مستندات و فایلهای عمیقتر هدایت می‌کند |
| فایل وضعیت (State file) | «یادداشت‌ها» | سابقه‌ای ماشین‌خوان از وضعیت فعلی ایجنت که در هر نوبت گفت‌وگو نوشته می‌شود |
| تابلوی تسک‌ها (Task board) | «بک‌لاگ» | صفی از کارها با فرمت JSON به همراه وضعیت، مسئول و معیارهای پذیرش |
| مرجع رسمی سوابق (System of record) | «منبع حقیقت» | فایلی که پس از پایان چت، میز کار آن را به‌عنوان مرجع معتبر کارها در نظر میگیرد |
مطالعه‌ی بیشتر
- مشخصات باز agents.md — پذیرفته‌شده توسط Cursor، Codex، Claude Code، Copilot، Gemini، OpenCode
- Augment Code: یک AGENTS.md خوب مثل ارتقای مدل است؛ یک فایل بد، نتیجه را از نبود داکیومنت هم بدتر می‌کند — جهش‌های کیفی سنجیده‌شده
- Blake Crosley: الگوهای AGENTS.md؛ چه چیزی واقعاً رفتار ایجنت را تغییر می‌دهد — نتایج تجربی از آنچه مؤثر است و آنچه نیست
- Datadog Frontend: هدایت ایجنت‌های هوش مصنوعی در مونوریپوها با AGENTS.md — اولویت‌بندی فایلهای تودرتو در عمل
- Nx Blog: آموزش کار در مونوریپو به ایجنت هوش مصنوعی شما — تولید فایل‌ها از یک منبع واحد در شش ابزار مختلف
- The Prompt Shelf: بهترین الگوهای AGENTS.md؛ ساختار، دامنه و مثال‌های واقعی — ترتیب چینش بخش‌ها برای تایید در بازبینی
- Anthropic: ساب‌ایجنت‌های Claude Code
- فاز 14 · بخش 31 — حالت‌های شکستی که این کمینه‌ی ابزاری مهار می‌کند
- فاز 14 · بخش 34 — اسکیما یا طرحواره‌ی وضعیت پایدار که در این درس پیش‌نمایش آن بررسی شد