پروژه 08. جریان کاری خود را به صورت یک گراف ترسیم کنید

درس مرتبط: درس 14. از تک‌حلقه‌ها تا مهندسی گراف

کاری که انجام می‌دهید#

این پروژه مرحله گذار از «حلقه» به «گراف» است. در پروژه قبل یک حلقه سازنده-بازبین ساختید — پیاده‌سازی، راستی‌آزمایی، بازخورد، پیاده‌سازی مجدد — که در آن هر تصمیمی درون پنجره زمینه یک ایجنت واحد رخ می‌داد. در این پروژه شما ساختاری را که درون حلقه پنهان شده بود، صریح و آشکار خواهید ساخت: گره‌ها، یال‌ها، وضعیت مشترک و قواعد مسیریابی، که کلمه به کلمه نوشته می‌شوند.

شما سه آزمایش پیش‌رونده انجام خواهید داد: ابتدا حلقه سازنده-بازبین P07 خود را به صورت یک گراف صریح رسم می‌کنید، سپس یک گره موازی پراکنش / تجمیع (fan-out / fan-in) اضافه می‌نمایید، و پس از آن یک یال بازگشت به عقب شرطی و یک گره تأیید انسانی اضافه خواهید کرد. پس از اتمام، این موضوع را از نزدیک لمس خواهید کرد: یک گراف اختراعی جدید نیست — بلکه همان چیزی است که حلقه شما پس از پیچیده شدن به آن تبدیل می‌شود.

ابزارهایی که استفاده خواهید کرد#

• Claude Code یا Codex
• Git
• حلقه سازنده-بازبینی که در P07 ساختید (یا هر جریان کاری ایجنتی که بتوانید مکرراً اجرا کنید)
• یک ویرایشگر متن یا ابزار رسم نمودار (رسم کردن برای زیبایی نیست — برای آوردن ساختار روی کاغذ است؛ mermaid یا یک فایل دست‌نویس graph.md هر دو مناسبند)

مراحل#

آماده‌سازی#

1. از مخزنی که P07 را در آن تمام کردید، یا از هر جریان کاری ایجنتی که هم‌اکنون اجرا می‌کنید، شروع نمایید.
2. سه شاخه ایجاد کنید: p08-explicit-graph، p08-parallel، p08-human-in-the-loop.
3. یک فایل state.md را به عنوان فایل وضعیت مشترک خود آماده کنید: نیازمندی‌ها، پیشرفت و نتایج راستی‌آزمایی همگی در اینجا قرار می‌گیرند. این همان «فضای کاری مشترک» گراف است.

آزمایش 1: رسم حلقه به صورت یک گراف صریح#

به شاخه p08-explicit-graph بروید.

1. فهرست کردن تمام گره‌ها: هر مرحله از حلقه سازنده-بازبین P07 را به عنوان یک گره بنویسید. برای هر گره، این موارد را یادداشت کنید: مسئولیت آن، ورودی‌های آن، خروجی‌های آن، و اینکه آیا یک ایجنت است یا کد قطعی.
2. رسم تمام یال‌ها: تمام یال‌های میان گره‌ها را فهرست کنید. دو نوع خاص را مشخص نمایید: - یال‌های شرطی: راستی‌آزمایی قبول شد/رد شد — هر کدام چه مسیری را طی می‌کنند؟ - یال‌های بازگشت به عقب: شکست به کجا بازمی‌گردد؟
3. نوشتن وضعیت مشترک: فیلدهای موجود در وضعیت (نیازمندی‌ها، کد، نتایج تست، نتیجه‌گیری‌های بازبینی) و اینکه چه کسی هر کدام را می‌خواند/می‌نویسد به طور صریح بنویسید.
4. نوشتن قواعد مسیریابی: عبارت «اجرا در مرحله بعد به کجا می‌رود» را به ساده‌ترین زبان شرطی بیان کنید، به عنوان مثال: if verify passed → merge node if verify failed → implement node if implement node lacks information → research node
5. نوشتن همه موارد در قالب graph.md: موارد بالا را به یک سند واحد تبدیل کنید — یک نمودار mermaid به همراه جدول گره‌ها و قواعد مسیریابی.
6. پاسخ به این پرسش: پس از رسم، حداقل یک یال که قبلاً ضمنی بود بیابید — مسیر تصمیمی که پیش‌تر درون زمینه ایجنت قرار داشت و شما حتی از وجود آن آگاه نبودید.

آزمایش 2: افزودن گره موازی پراکنش / تجمیع (Fan-out / Fan-in)#

به شاخه p08-parallel بروید.

1. انتخاب نقطه‌ای با قابلیت موازی‌سازی: نقطه‌ای را پیدا کنید که در آن وظیفه بتواند به دو بخش مستقل تقسیم شود. به عنوان مثال: - تقسیم پیاده‌سازی به دو ماژول مستقل، که به صورت موازی توسط دو ایجنت نوشته می‌شوند - تقسیم راستی‌آزمایی به دو بازبینی مستقل: یکی آزمون‌ها و لینت را اجرا می‌کند، دیگری بازبینی کد را انجام می‌دهد (دستورالعمل‌های متفاوت، تمرکز متفاوت) - تقسیم پژوهش به دو مسیر، یک ایجنت برای هر مسیر
2. نوشتن قاعده پراکنش (fan-out): در وضعیت مشترک ثبت کنید که «این وظیفه به N زیروظیفه موازی تقسیم می‌شود»، هر کدام با زمینه اختصاصی و گره اختصاصی خود.
3. نوشتن قاعده تجمیع (fan-in): پس از پایان تمام زیروظایف، چه کسی نتایج را ادغام می‌کند؟ استاندارد ادغام چیست (مثلاً هر دو بازبینی باید قبول شوند، یا یکی کافی است)؟
4. ایزوله‌سازی با ورک‌تری‌ها: هر زیروظیفه موازی را در ورک‌تری (worktree) گیت اختصاصی خود اجرا کنید تا از برخورد فیزیکی فایل‌ها جلوگیری شود (عنصر بنیادین ورک‌تری در درس 13 را مرور کنید).
5. یک بار اجرا و ثبت نتایج: زمان واقعی، هزینه توکن و کیفیت نتیجه را قبل و بعد از موازی‌سازی ثبت کنید. آیا موازی‌سازی واقعاً سریع‌تر بود؟ یا بار سربار هماهنگ‌سازی صرفه‌جویی حاصل را بلعید؟

آزمایش 3: افزودن یال بازگشت به عقب و گره تأیید انسانی#

به شاخه p08-human-in-the-loop بروید.

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

1. یال بازگشت به عقب شرطی: به گره verify یک مسیر «قبولی جزئی» بدهید — به جای اینکه کل کار را به گره پیاده‌سازی برگردانید، با بازخورد مشخص به گره‌ای که مشکل را ایجاد کرده است بازگردید. به عنوان مثال: آزمون‌ها همگی پاس می‌شوند اما بازبینی کد نشان می‌دهد نیازمندی‌ها اشتباه درک شده‌اند — به گره پژوهش برگردید، نه به گره پیاده‌سازی. این امر مستلزم آن است که وضعیت مشترک شما ثبت کند «مشکل از کدام لایه ناشی شده است».
2. گره تأیید انسانی (حضور انسان در حلقه): یک گره انسانی قبل از گره merge قرار دهید. اجرا در اینجا متوقف می‌شود و منتظر می‌ماند تا شما «approved» یا «rejected» را در state.md بنویسید. گره تأیید می‌تواند یک قاعده انقضا (timeout) داشته باشد: پس از N ساعت بدون پاسخ، رد خودکار یا ارجاع خودکار به سطح بالاتر انجام شود.
3. نوشتن قالب وقفه: درخواست تأیید چگونه باید نوشته شود — چه اتفاقی افتاد، چه چیزی تغییر کرد، چرا به انسان نیاز است، و پیامدهای تأیید/رد چیست؟
4. اجرای حداقل 2 دور کامل: هر دور در گره تأیید انسانی متوقف می‌شود و شما یک بار تأیید یا رد می‌کنید. ثبت کنید: آیا تصمیمات تأیید شما با نظر گره verify همخوانی داشت؟ آیا گره تأیید متوجه چیزی شد که گره verify آن را جا انداخته بود؟

نحوه اندازه‌گیری نتایج#

آنچه باید تحویل دهید#

• graph.md (شرح کامل گراف در آزمایش 1: نمودار mermaid + جدول گره‌ها + جدول یال‌ها + فیلدهای وضعیت مشترک + قواعد مسیریابی)
• فهرست یال‌های ضمنی که در آزمایش 1 پیدا کردید (حداقل یک مورد)
• قواعد پراکنش/تجمیع آزمایش 2 و یک گزارش اجرای موازی (مقایسه زمان/هزینه/کیفیت)
• قواعد یال بازگشت به عقب در آزمایش 3، قالب گره تأیید، و 2 دور گزارش حضور انسان در حلقه
• مرور گذشته‌نگر نهایی: با حرکت از حلقه به گراف، شیوه کاری شما چگونه تغییر کرد؟ کدام وظایف شایسته گراف هستند و کدام نیستند؟

درس‌های مرتبط#

• درس 14 — از تک‌حلقه‌ها تا مهندسی گراف
• درس 13 — از پرامپت‌نویسی دستی تا حلقه‌های خودمختار (حلقه شما گره‌ای در یک گراف است؛ این پروژه ساختار درونی آن گره را باز می‌کند)
• درس 09 — جلوگیری از اعلام پیروزی زودهنگام توسط ایجنت‌ها (چرا گره verify باید از گره implement مستقل باشد — یک مسئله ساختاری، نه یک مسئله پرامپت)
• درس 11 — مشاهده‌پذیر ساختن زمان اجرای ایجنت (هر چه گراف پیچیده‌تر باشد، بیشتر نیاز دارید ببینید هر گره چه می‌کند)