هر متن کنار Agent «دستور» نیست. یک prompt درخواست همین نوبت است؛ یک instruction همیشه‌فعال قرارداد زمینه است؛ path rule فقط روی بخشی از درخت فایل اثر دارد؛ memory دانسته‌ای durable برای جلسه‌های بعدی است؛ و Skill بسته‌ای قابل‌کشف برای انجام یک کار چندمرحله‌ای است. اگر این مرزها را قاطی کنیم، `booking-platform` یا با متن سنگین خفه می‌شود یا با راهنمایی متناقض به migration خطرناک می‌رسد.
## اهداف
پس از این درس می‌توانی برای یک نیاز، محل درست ذخیره را انتخاب کنی؛ یک `AGENTS.md` کوتاه و قابل‌حمل بنویسی؛ adapterهای ابزارمحور را از قرارداد هسته جدا کنی؛ و با شواهد نشان بدهی کدام instruction واقعاً بارگذاری شده است.
## جایگاه در چرخه
فصل ۳ Context Engineering نشان داد context باید کمینه و پُرسیگنال باشد. فصل ۶ قرارداد TDD و فصل ۷ Task Contract را ساختند. این درس در `Implement` و پیش از اجرای Agent قرار می‌گیرد: ابتدا قرارداد پایدار را در سطح مناسب می‌گذاریم، سپس برای هر ابزار adapter می‌نویسیم. هیچ adapterی authority تازه‌ای برای deadline، tenant یا audit ایجاد نمی‌کند.
## پنج مفهوم با مرز روشن
**Prompt** پیام کاربر برای یک اجرای مشخص است: «تست A-04 را در محیط ephemeral اجرا کن». عمر آن معمولاً یک turn یا task است و نباید تنها محل نگهداری invariant مهم باشد.
**Always-on instruction** راهنمایی است که ابزار در scope پروژه یا کاربر به‌طور پیش‌فرض به Agent می‌دهد؛ مثل «هر تغییر باید با `pnpm test` و `git diff --check` همراه باشد». نام فایل و اولویت دقیق وابسته به ابزار است.
**Path rule** قانونی محدود به مسیر است؛ مثلاً در `apps/api/` تغییرات schema باید migration و rollback داشته باشند. مسیر نزدیک‌تر می‌تواند rule عمومی را دقیق‌تر کند، اما تضاد را پنهان نکنید.
**Memory** fact یا decision durable است: `ADR-021` می‌گوید deadline reschedule دقیقاً ۲۴ ساعت است. Memory جای prompt نیست و باید owner، تاریخ و منبع داشته باشد؛ stale memory باید علامت‌گذاری شود.
**Skill** بستهٔ reusable از metadata، دستورالعمل و workflow است که معمولاً با progressive disclosure بار می‌شود. Skill باید portable باشد: ابزار خاص در adapter بماند و ورودی، خروجی، stop condition و verification مستقل از نام محصول نوشته شوند.
مثال بد
AGENTS.md (۴۸۰ خط):
همیشه کل repository را بخوان، هر تستی را خودت اصلاح کن، migration را اجرا کن،
در production سریع deploy کن و هر جا ambiguity بود بهترین حدس را بزن.این فایل هم context را هدر می‌دهد، هم advice را با enforcement و approval مخلوط می‌کند، هم مسیر حساس production را بدون owner باز می‌گذارد. «همیشه» نیز برای همهٔ مسیرها درست نیست.
مثال خوب: هسته و adapter
# booking-platform agent contract
- قبل از تغییر، مسیرها و baseline را کشف و در Evidence ثبت کن.
- invariantهای Spec و ADR را تغییر نده؛ ابهام را با DECIDE متوقف کن.
- پیش‌فرض: read-only و database ephemeral؛ secret واقعی و network ممنوع.
- Done یعنی diff قابل‌بررسی، تست هدفمند، `git diff --check` و recovery ثبت‌شده.این هسته به `AGENTS.md` می‌رود. adapter Cursor می‌تواند مسیر rule و نام surface را توضیح دهد؛ adapter Claude Code می‌تواند محل Skill و hook schema را بگوید؛ adapter Copilot یا Codex باید همان contract را با syntax خودش مصرف کند. این‌ها قابلیت ابزار را مستند می‌کنند، نه اینکه ادعا کنند همهٔ ابزارها precedence یکسان دارند.
adapter رسمی برای GitHub Copilot
در GitHub Copilot، دو surface را با هم قاطی نکن. **Response customization** برای دستورهای سفارشیِ پاسخ‌گویی است و می‌تواند با instruction پروژه یا کاربر هم‌پوشانی داشته باشد؛ **custom agents در Copilot CLI** surface جداگانه‌ای برای تعریف Agent سفارشی و رفتار آن در CLI است. بنابراین adapter دوره باید بنویسد: `surface=Copilot CLI custom agent`، `path/format=مطابق مستند رسمی همان surface`، `capability=اجرای workflow محدود پس از بررسی permission` و `warning=این مستند معادل پشتیبانی یکسان در GitHub.com یا همهٔ IDEها نیست`. هستهٔ `AGENTS.md` را به این قالب تبدیل نکن؛ آن را به‌عنوان context مشترک نگه دار و تفاوت precedence و availability را در Evidence آزمایش کن.
منبع مستقیم این adapter، [GitHub Copilot custom agents](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-custom-agents) است؛ برای دستورهای عمومی‌تر نیز [Copilot response customization](https://docs.github.com/en/copilot/concepts/prompting/response-customization) را ببین. هر دو مستند رسمی‌اند، اما قابلیت و scope آن‌ها یکی نیست و نباید از custom agent در Copilot CLI نتیجه بگیریم که همان فایل یا lifecycle در IDE یا GitHub.com هم اعمال می‌شود.
## سناریوی booking-platform
برای reschedule چهار artifact داریم: `AGENTS.md` برای invariants مشترک؛ `apps/api/AGENTS.md` برای authorization و migration؛ `docs/decisions/adr-021-database-interval-invariant.md` به‌عنوان memory تصمیم؛ و Skill به نام `tdd-reschedule` برای چرخهٔ Red–Green–Refactor. Prompt هر اجرای امروز مشخص می‌کند فقط `packages/contracts/src/reschedule-policy.ts` و تستش مجاز است. اگر prompt با ADR ناسازگار بود، ADR authority نیست چون «قدیمی» است؟ خیر؛ باید owner و تاریخ بازبینی مشخص شود، نه اینکه Agent خودسرانه آن را overwrite کند.
## آزمایشگاه: طبقه‌بندی و adapter
**ورودی:** یک request مبهم، درخت `booking-platform`، ADR-021 و مستند رسمی rules/skills ابزار انتخابی.
۱. پنج جملهٔ زیر را طبقه‌بندی کن: «این turn فقط A-04 را اجرا کن»؛ «در API هیچ bodyی tenant را تعیین نمی‌کند»؛ «deadline ۲۴ ساعت در ADR-021»؛ «workflow هشت‌مرحله‌ای TDD»؛ «در مسیر migration rollback اجباری است». به‌ترتیب prompt، always-on/path rule، memory، Skill و path rule هستند.
۲. یک `AGENTS.md` حداکثر ۱۲ خط بساز. سپس adapter را با چهار ستون `surface / path / capability / warning` بنویس. در adapter نام model یا قیمت نگذار.
۳. با یک Agent read-only از آن بخواه «منابعی را که واقعاً خوانده، مسیر instruction و تضادها را گزارش کند». به خروجی مدل اعتماد نکن؛ فایل‌های قابل مشاهده و command trace را بررسی کن.
**خروجی مورد انتظار:** هسته زیر ۱۲ خط، سه invariant، یک stop condition، و adapterی که تفاوت local/CLI و syntax را صریح می‌کند. **Recovery:** اگر ابزار rule را بارگذاری نکرد، متن را طولانی‌تر نکن؛ مسیر رسمی و precedence را بررسی، یک command probe بزن و در Evidence بنویس. اگر دو rule متناقض‌اند، اجرا را متوقف کن و owner بده.
## خطاهای رایج
- قرار دادن تصمیم تاریخ‌دار داخل prompt و از دست دادن آن در اجرای بعد.
- تبدیل Skill به یک prompt عظیم که progressive disclosure ندارد.
- فرض precedence یکسان میان Cursor، Claude Code، Copilot و Codex.
- نام‌گذاری adapter به‌عنوان «استاندارد»، در حالی که `AGENTS.md` یک convention باز است.
- گذاشتن credential، endpoint تولید یا دستور destructive در متن راهنما.
## Verification
- [ ] هر artifact owner، scope و عمر مشخص دارد.
- [ ] `AGENTS.md` کوتاه و مستقل از برند است.
- [ ] ruleهای مسیر حساس با allowlist، rollback و stop condition همراه‌اند.
- [ ] memory به ADR یا evidence مستقیم ارجاع می‌دهد.
- [ ] Skill ورودی، خروجی، recovery و verification دارد.
- [ ] adapter capability و limitation ابزار را با تاریخ و URL رسمی ثبت می‌کند.
یک آزمون مفید برای portability این است که هسته را از یک ابزار جدا کنی و از خواننده بخواهی همان کار را با یک Agent دیگر اجرا کند. اگر تنها چیزی که عوض می‌شود مسیر فایل configuration، نام event hook یا command surface است، adapter مرز درستی دارد. اگر باید policy tenant یا معیار Done را عوض کنیم، هستهٔ قابل‌حمل بیش از حد به محصول وابسته شده است. این آزمون را با یک commit ثابت، fixture یکسان و log یکسان انجام بده؛ مقایسهٔ «مدل بهتر بود» بدون کنترل محیط، evidence معتبری نیست.
precedence نیز باید قابل مشاهده باشد. یک rule عمومی، یک rule نزدیک به `apps/api` و یک prompt متناقض بساز؛ سپس به‌جای حدس‌زدن، مستند رسمی و trace واقعی ابزار را بررسی کن. نتیجه را به‌صورت fact، limitation و decision ثبت کن. هدف این نیست که همهٔ ابزارها را یکسان کنیم؛ هدف این است که بدانیم در صورت تضاد کدام لایه واقعاً اعمال شده و کدام لایه فقط پیشنهاد بوده است.
## تمرین و پاسخ نمونه
برای درخواست «قابلیت reschedule را طوری بساز که در همهٔ ابزارها یکسان اجرا شود»، محل نگهداری پنج جزء را انتخاب کن و سه خط `AGENTS.md` بنویس.
**پاسخ نمونه:** prompt باید scope همین اجرا را تعیین کند؛ invariant tenant/timezone/deadline در always-on contract؛ تفاوت `apps/api` در path rule؛ deadline و تصمیم‌های پذیرفته‌شده در ADR؛ و workflow TDD در Skill. پاسخ نباید ادعا کند syntax یا precedence ابزارها یکسان است. rubric: تفکیک عمر و scope، stop برای ambiguity، read-only default و adapter تاریخ‌دار.
## جمع‌بندی
قابل‌حمل بودن یعنی contract و evidence مستقل بمانند، نه اینکه یک فایل جادویی همه‌جا همان‌طور اجرا شود. prompt کوتاه‌عمر، instruction پایدار، path rule محدود، memory قابل‌ردیابی و Skill workflow را از هم جدا کن؛ سپس سطح ابزار را در adapter نگه دار.
## منابع مستقیم
- [Agent Skills specification](https://agentskills.io/specification) — تعریف ساختار Skill و progressive disclosure؛ maturity و پشتیبانی ابزارها متفاوت است.
- [AGENTS.md](https://agents.md/) — convention باز برای instruction فایل‌محور؛ runtime یکسان را تضمین نمی‌کند.
- [Cursor Rules](https://cursor.com/docs/rules.md) — مستند رسمی rules و scope؛ syntax محصول‌محور است.
- [Claude Code memory](https://code.claude.com/docs/en/memory) — مستند رسمی memory و تفاوت scopeها.
- [OpenAI Codex AGENTS.md](https://developers.openai.com/codex/guides/agents-md) — adapter رسمی Codex؛ جای قرارداد قابل‌حمل را نمی‌گیرد.
به زبان ساده
Prompt عمر کوتاه یک اجرا را دارد، Rule به مسیر یا پروژه مربوط است، Memory تصمیم durable را نگه می‌دارد و Skill workflow چندمرحله‌ای را بسته‌بندی می‌کند. قابل‌حمل‌بودن یعنی قرارداد و Evidence مستقل بمانند، نه اینکه همهٔ Hostها یک loader داشته باشند.
مثال واقعی
در ساختار فرضی دوره، `ADR-021` محل تصمیم timezone، `AGENTS.md` محل invariant مشترک و Skill محل چرخهٔ TDD است؛ prompt فقط فایل policy همان اجرای امروز را محدود می‌کند.