راهنمای الگوها

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

چگونه شروع کنیم#

ابتدا این چهار فایل را در ریشه پروژه خود کپی کنید:

1. AGENTS.md یا CLAUDE.md
2. init.sh
3. claude-progress.md
4. feature_list.json

با رشد پروژه، فایل‌های باقیمانده را اضافه کنید.

---

AGENTS.md#

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

نحوه استفاده از آن:

• در دایرکتوری ریشه پروژه خود کپی کنید
• مراحل جریان کاری راه‌اندازی را با مسیرها و دستورات واقعی پروژه خود جایگزین نمایید
• قواعد کاری را مطابق با عرف‌های تیم خود تنظیم کنید
• بخش تعریف اتمام کار (definition of done) را حفظ کنید — این مهم‌ترین بخش است

چه کاری برای ایجنت انجام می‌دهد:

• به آن می‌گوید پیش از شروع کار، پیشرفت و وضعیت ویژگی‌ها را بخواند
• آن را ملزم می‌کند هر بار فقط روی یک ویژگی کار کند
• پیش از علامت‌گذاری هر چیزی به عنوان اتمام‌یافته، شواهد را الزامی می‌کند
• مشخص می‌کند که پایان تمیز یک نشست چه شکلی دارد

از AGENTS.md برای Codex یا سایر ایجنت‌ها استفاده کنید. اگر با Claude Code کار می‌کنید از CLAUDE.md استفاده نمایید — ساختار یکسان است، فقط برای سبک دستورالعمل Claude قالب‌بندی شده است.

init.sh#

اسکریپت راه‌اندازی. نصب وابستگی‌ها، راستی‌آزمایی و چاپ دستور شروع را همگی در یک حرکت اجرا می‌کند.

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• این سه متغیر را در بالای فایل ویرایش کنید:
• INSTALL_CMD — دستور نصب وابستگی‌ها (مثلاً npm install، pip install -r requirements.txt)
• VERIFY_CMD — دستور راستی‌آزمایی پایه (مثلاً npm test، pytest)
• START_CMD — دستور شروع سرور توسعه (مثلاً npm run dev)
• آن را قابل اجرا کنید: chmod +x init.sh

چه کاری انجام می‌دهد:

1. دایرکتوری فعلی را چاپ می‌کند (تا مطمئن شوید در جای درست اجرا می‌شود)
2. وابستگی‌ها را نصب می‌کند
3. دستور راستی‌آزمایی را اجرا می‌کند
4. دستور شروع را چاپ می‌کند (یا اگر RUN_START_COMMAND=1 تنظیم شده باشد، آن را اجرا می‌کند)

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

claude-progress.md#

لاگ پیشرفت. هر نشست در این فایل می‌نویسد، و هر نشست جدید ابتدا آن را می‌خواند.

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• بخش «وضعیت تأییدشده فعلی» را با اطلاعات پروژه خود پر کنید
• پس از هر نشست، گزارش نشست را به‌روزرسانی نمایید

معنای هر فیلد:

• وضعیت تأییدشده فعلی (Current Verified State) — یگانه منبع حقیقت درباره جایگاه فعلی پروژه
• Repository root directory — محل قرارگیری پروژه
• Standard startup path — دستور لازم برای اجرای پروژه
• Standard verification path — دستور اجرای تست‌ها
• Highest priority unfinished feature — آنچه نشست بعدی باید روی آن کار کند
• Current blocker — هر مانعی که کار در آن گیر کرده است
• گزارش نشست (Session Record) — یک مدخل به ازای هر نشست
• Goal — آنچه برنامه‌ریزی کرده بودید انجام دهید
• Completed — آنچه در عمل انجام شد
• Verification run — چه تست‌هایی اجرا شدند
• Evidence recorded — چه مدارک و شواهدی ثبت شد
• Commits — چه کامیت‌هایی زده شد
• Known risks — چه مواردی ممکن است خراب باشند
• Next best action — نشست بعدی از کجا باید شروع کند

feature_list.json#

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

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• ویژگی‌های نمونه را با ویژگی‌های خود جایگزین کنید
• هر ویژگی نیازمند موارد زیر است:
• id — یک شناسه منحصر‌به‌فرد کوتاه
• priority — عدد صحیح، کمتر = اولویت بالاتر
• area — کدام بخش از برنامه (مثلاً "chat"، "import"، "search")
• title — شرح کوتاه
• user_visible_behavior — آنچه کاربر در زمان کارکرد صحیح باید ببیند
• status — یکی از حالات not_started، in_progress، blocked، passing
• verification — دستورالعمل‌های گام‌به‌گام برای تأیید کارکرد آن
• evidence — شواهد ثبت‌شده مبنی بر قبولی راستی‌آزمایی (توسط ایجنت پر می‌شود)
• notes — هر زمینه و یادداشت اضافی

قواعد وضعیت:

• not_started — دست نخورده است
• in_progress — تنها ویژگی‌ای که در حال حاضر روی آن کار می‌شود (در هر زمان فقط یک مورد)
• blocked — به دلیل مشکلی ثبت‌شده قابل ادامه نیست
• passing — راستی‌آزمایی قبول شده و شواهد ثبت شده است

ایجنت در هر زمان باید حداکثر یک ویژگی در وضعیت in_progress داشته باشد.

session-handoff.md#

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

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• در پایان هر نشست آن را پر کنید (یا از ایجنت بخواهید آن را پر کند)

هر بخش شامل چه مواردی است:

• تأییدشده فعلی (Currently verified) — آنچه کارکردش تأیید شده و چه راستی‌آزمایی‌ای اجرا شده است
• تغییرات این نشست (Changes this session) — چه کد یا زیرساختی تغییر کرده است
• همچنان خراب یا تأییدنشده (Still broken or unverified) — مشکلات شناخته‌شده و نواحی پرخطر
• بهترین اقدام بعدی (Next best action) — نشست بعدی چه کاری باید انجام دهد، و به چه مواردی نباید دست بزند
• دستورات (Commands) — دستورات راه‌اندازی، راستی‌آزمایی و دیباگ برای ارجاع سریع

این فایل برای نشست‌های کوچک اختیاری است. اما زمانی که نشست‌ها طولانی هستند یا پروژه دارای چندین ناحیه فعال است اهمیت پیدا می‌کند.

clean-state-checklist.md#

یک چک‌لیست برای بررسی پیش از پایان دادن به هر نشست. اطمینان حاصل می‌کند که مخزن در وضعیتی مناسب قرار دارد تا نشست بعدی بتواند به صورت تمیز آغاز به کار کند.

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• پیش از بستن یک نشست آن را مرور کنید
• ایجنت نیز باید این موارد را به عنوان بخشی از روال پایان نشست خود بررسی کند

چه مواردی را بررسی می‌کند:

• راه‌اندازی استاندارد همچنان کار می‌کند
• راستی‌آزمایی استاندارد همچنان اجرا می‌شود
• لاگ پیشرفت به‌روزرسانی شده است
• فهرست ویژگی‌ها وضعیت واقعی را منعکس می‌کند (هیچ مدخل قبولی دروغینی وجود ندارد)
• هیچ کار نیمه‌کاره‌ای ثبت‌نشده باقی نمانده است
• نشست بعدی می‌تواند بدون اصلاحات دستی کار را ادامه دهد

evaluator-rubric.md#

یک جدول امتیازدهی برای بازبینی کیفیت خروجی ایجنت. پس از یک نشست یا در نقاط عطف پروژه برای ارزیابی اینکه آیا کار به سطح استاندارد می‌رسد از این فایل استفاده کنید.

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• پس از یک نشست (یا مجموعه‌ای از نشست‌ها)، به کار ایجنت در شش بُعد نمره دهید
• هر بُعد بین 0 تا 2 نمره می‌گیرد

ابعاد شش‌گانه:

1. صحت (Correctness) — آیا پیاده‌سازی با رفتار هدف مطابقت دارد؟
2. راستی‌آزمایی (Verification) — آیا بررسی‌های الزامی واقعاً همراه با شواهد اجرا شدند؟
3. انضباط محدوده (Scope discipline) — آیا ایجنت درون ویژگی انتخاب‌شده باقی ماند؟
4. قابلیت اطمینان (Reliability) — آیا نتیجه پس از راه‌اندازی مجدد یا اجرای دوباره دوام می‌آورد؟
5. قابلیت نگهداری (Maintainability) — آیا کد و مستندات برای نشست بعدی به اندازه کافی شفاف هستند؟
6. آمادگی تحویل (Handoff readiness) — آیا یک نشست جدید می‌تواند تنها با استفاده از مصنوعات مخزن کار را ادامه دهد؟

گزینه‌های نتیجه‌گیری:

• قبول (Accept) — در حد استاندارد است
• بازنگری (Revise) — پیش از پذیرش نیازمند اصلاحات است
• مسدود (Block) — مشکلات بنیادینی وجود دارد که ابتدا باید حل شوند

نکته مهم: ارزیاب نیازمند تنظیم دقیق است. ایجنت‌ها به صورت پیش‌فرض قاضی‌های ضعیفی برای خودشان هستند — آن‌ها مشکلات را شناسایی می‌کنند و سپس با استدلال خود را قانع می‌کنند که تأیید نمایند. شما باید تکرار کنید:

1. ارزیاب را روی یک اسپرینت تکمیل‌شده اجرا نمایید.
2. نمرات آن را با قضاوت انسانی خود مقایسه کنید.
3. در جایی که اختلاف دارند، معیارهای قبولی/ردی را در جدول دقیق‌تر و جزئی‌تر سازید.
4. دوباره اجرا کنید و هم‌راستایی را بسنجید.
5. این کار را تا زمانی که ارزیاب به طور مداوم با بازبینی انسانی مطابقت پیدا کند تکرار نمایید.

برای 3 تا 5 دور تنظیم دقیق برنامه‌ریزی کنید. هر تغییر را ثبت کنید تا بتوانید آنچه را هم‌راستایی را بهبود بخشیده ردگیری نمایید.

quality-document.md#

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

نحوه استفاده از آن:

• در ریشه پروژه خود کپی کنید
• پیش از شروع یک نشست: آن را بخوانید تا بفهمید پایگاه کد در کجا ضعیف‌تر است
• پس از یک نشست: نمرات را بر اساس آنچه تغییر کرده به‌روزرسانی کنید
• در طول زمان: نماهای لحظه‌ای را با هم مقایسه کنید تا ببینید کدام تغییرات هارنس واقعاً سلامت پایگاه کد را بهبود بخشیده‌اند

چه مواردی را نمره‌دهی می‌کند:

• دامنه‌های محصول (به عنوان مثال، وارد کردن سند، جریان پرسش و پاسخ، نمایه‌سازی): هر دامنه در وضعیت راستی‌آزمایی، خوانایی برای ایجنت، پایداری تست‌ها، و شکاف‌های کلیدی نمره‌ای (A تا D) دریافت می‌کند
• لایه‌های معماری (به عنوان مثال، فرایند اصلی، پیش‌بارگذاری، رندرکننده، سرویس‌ها): هر لایه برای اعمال مرزها و خوانایی برای ایجنت نمره می‌گیرد

چرا اهمیت دارد:

جدول راهنمای ارزیاب به خروجی‌های منفرد ایجنت نمره می‌دهد. سند کیفیت به خود پایگاه کد نمره می‌دهد. آن‌ها به دو پرسش متفاوت پاسخ می‌دهند:

• راهنمای ارزیاب: «آیا ایجنت در این نشست کار خوبی انجام داد؟»
• سند کیفیت: «آیا پروژه در طول زمان در حال قوی‌تر شدن است یا ضعیف‌تر شدن؟»

چه زمانی به‌روزرسانی شود:

• پس از هر نشست مهم
• پیش از مقایسه‌های بنچ‌مارک
• پس از بازبینی‌های پاک‌سازی یا ساده‌سازی
• هنگام ورود یک ایجنت یا مدل جدید به پروژه

ارتباط با ساده‌سازی هارنس:

سند کیفیت همچنین از ساده‌سازی هارنس پشتیبانی می‌کند. هر مؤلفه هارنس فرضیه‌ای را درباره آنچه مدل قادر به انجامش نیست رمزگذاری می‌نماید. با بهبود مدل‌ها، این فرضیات کهنه می‌شوند. برای بررسی اینکه آیا یک مؤلفه هنوز لازم است یا خیر:

1. یک نمای لحظه‌ای از سند کیفیت بگیرید.
2. یک مؤلفه هارنس را حذف کنید.
3. مجموعه وظایف بنچ‌مارک را اجرا نمایید.
4. نمای لحظه‌ای دیگری بگیرید.
5. مقایسه کنید — اگر نمرات افت نکرد، آن مؤلفه بار اضافی (overhead) بوده است. اگر نمرات افت کرد، آن را برگردانید.