راهنمای مطالعه: Workflow for AI Coding

این راهنمای مطالعه، اصول، راهبردهای معماری و چارچوب‌های اجرایی ارائه‌شده توسط Matt Pocock در ورکشاپ «Full Walkthrough: Workflow for AI Coding» را به‌صورت جامع مرور می‌کند.

ایده‌ی اصلی ورکشاپ این است که اصول مهندسی نرم‌افزار که همکاری انسان‌ها را اداره می‌کنند، مستقیماً و به‌شکلی قدرتمند در جریان‌های کاری کدنویسی با AI هم صدق می‌کنند. به‌جای تکیه بر تولید کد از روی مشخصات بدون نظارت («vibe coding»)، ادغام مؤثر AI نیازمند این موارد است: اندازه‌گیری درست تسک‌ها، حلقه‌های بازخورد قوی، برنامه‌ریزی ساختاریافته، معماری ماژولار عمیق، و تفکیک آگاهانه‌ی «هم‌ترازی با حضور انسان» از «اجرای خودکار».

• سخنران: Matt Pocock
• لینک ویدیو: https://www.youtube.com/watch?v=-QFHIoCo-Ko

---

۱. اصول بنیادین و محدودیت‌های سخت‌افزاری LLM

برای کار مؤثر با مدل‌های زبانی بزرگ (LLM)، توسعه‌دهنده باید جریان کاری خود را حول محدودیت‌های شناختی و مکانیکی پنجره‌ی context طراحی کند.

Smart Zone در برابر Dumb Zone

این مفهوم را Dex Horthy (بنیان‌گذار Human Layer) مطرح کرده و توضیح می‌دهد که توان استدلال LLM در جلسه‌های طولانی چطور افت می‌کند.

• Smart Zone (ناحیه‌ی هوشمند): ابتدای یک context تمیز. روابط attention بین token‌ها کمترین فشار را دارند و LLM می‌تواند بهترین کیفیت استدلال را ارائه دهد.
• Dumb Zone (ناحیه‌ی کم‌هوش): با انباشته شدن context، هر token اضافه تعداد روابط attention را به‌صورت درجه دوم (quadratic) بالا می‌برد (مثل اضافه کردن تیم به یک لیگ ورزشی که تعداد بازی‌های لازم را به‌شدت زیاد می‌کند). مهم نیست مدل ادعا کند context window آن ۲۰۰ هزار یا ۱ میلیون token است؛ افت عملکرد از حدود ۱۰۰ هزار token به بعد آشکار می‌شود. بعد از این آستانه مدل مرتب تصمیم‌های غیرمنطقی می‌گیرد.

┌───────────────────────────────────────────────────────────────────────┐
│ پیشروی پنجره‌ی CONTEXT                                                │
│                                                                       │
│ [ 0k token ] ------------------> [ ~100k token ] -------------------> │
│    SMART ZONE                         DUMB ZONE                       │
│ (استدلال بهینه،                  (فشار درجه‌ی دوم روی attention،      │
│  attention تمیز)                  افت منطق و اشتباهات زیاد)           │
└───────────────────────────────────────────────────────────────────────┘

پدیده‌ی «Memento» و مدیریت context

LLMها مثل قهرمان فیلم Memento هستند: هر وقت context پاک شود، به حالت پایه برمی‌گردند. هر session کدنویسی این مسیر قابل پیش‌بینی را طی می‌کند:

1. System Prompt: context دائمی (باید حداقلی باشد؛ system prompt بزرگ مدل را همان ابتدا به Dumb Zone می‌برد).
2. مرحله‌ی Exploration: agent کدبیس را بررسی می‌کند.
3. مرحله‌ی Implementation: تولید کد.
4. تست / حلقه‌های بازخورد: اجرای تست‌ها و type-check.

Compacting در برابر Clearing

• Compacting (فشرده‌سازی): تاریخچه‌ی گفتگو به یک رشته‌ی خلاصه تبدیل می‌شود، داخل همان session. توسعه‌دهنده‌ها معمولاً compact را ترجیح می‌دهند، ولی «رسوب» (sediment) در context باقی می‌گذارد و مدل را خیلی سریع به Dumb Zone برمی‌گرداند.
• Clearing (پاک‌سازی) ← ترجیح Matt: context تا حد system prompt کاملاً پاک می‌شود. با استفاده از دارایی‌های بیرونی پایدار (PRDها، فایل‌های issue محلی) به‌عنوان لنگر، پاک کردن context باعث می‌شود LLM برای هر زیرتسک به وضعیت بهینه‌ی Smart Zone برگردد.

---

۲. فاز ۱: هم‌ترازی و برنامه‌ریزی با حضور انسان

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

┌───────────────────────────────────────────────────────────────────────┐
│ نمای کلی جریان کار                                                    │
│                                                                       │
│  [ بریف مشتری / ایده ]                                                │
│            │                                                          │
│            ▼                                                          │
│  [ Grill Me Skill ] -------------> هم‌ترازی با حضور انسان             │
│            │                       (مفهوم طراحی مشترک)                │
│            ▼                                                          │
│  [ مقصد: PRD ] ------------------> مستندسازی scope و موارد خارج scope │
│            │                                                          │
│            ▼                                                          │
│  [ مسیر: Kanban/DAG ] -----------> Vertical Slice ها (Tracer Bullet)  │
│            │                                                          │
│            ▼                                                          │
│  [ اجرای AFK: Ralph ] -----------> TDD + Sandbox + حلقه‌های بازخورد   │
│            │                                                          │
│            ▼                                                          │
│  [ QA دستی و Review ] -----------> سلیقه و بررسی نهایی انسان          │
└───────────────────────────────────────────────────────────────────────┘

مهارت «Grill Me»

جنبش «Specs-to-Code» فرض می‌کند توسعه‌دهنده می‌تواند مشخصات ایستا بنویسد، به AI بسپارد، مدام مشخصات را اصلاح کند و کد خروجی را نادیده بگیرد. این رویکرد شکست می‌خورد، چون توسعه‌دهنده باید کنترل کدبیس را حفظ کند.

برای ایجاد هم‌ترازی از Grill Me Skill استفاده می‌شود:

• سازوکار: AI بی‌وقفه از توسعه‌دهنده «بازجویی» می‌کند؛ درخت تصمیم‌های طراحی را یکی‌یکی، با پرسیدن یک سؤال در هر بار و پیشنهاد گزینه‌ی توصیه‌شده، پایین می‌رود.
• پشتوانه‌ی نظری: به کتاب The Design of Design از Frederick P. Brooks ارجاع دارد. هدف از grill کردن، ایجاد مفهوم طراحی مشترک (shared design concept) بین توسعه‌دهنده و AI است.
• Sub-agent ها: می‌توان sub-agent های اکتشافی را در context window های جداگانه راه انداخت تا کدبیس را تحلیل کنند و فقط خلاصه‌ی فشرده را برگردانند، بدون آلوده کردن context اصلی.

سند مقصد: Product Requirements Document (PRD)

وقتی grill تمام شد، مفهوم طراحی مشترک در یک PRD خلاصه می‌شود. PRD نقش سند مقصد را دارد:

• شامل بیان مسئله، user story ها، تصمیم‌های معماری، راهبرد تست و موارد صریحاً خارج از scope است.
• چون LLMها در خلاصه‌سازی عالی‌اند و هم‌ترازی قبلاً در جلسه‌ی grill حاصل شده، لازم نیست توسعه‌دهنده تک‌تک خطوط PRD تولیدشده را بخواند.

---

۳. فاز ۲: نقشه‌ی مسیر و ساختاردهی تسک‌ها

وقتی مقصد مشخص شد، کار باید به تسک‌های قابل اجرا شکسته شود که برای مصرف AI بهینه شده‌اند.

برش افقی (Horizontal) در برابر Vertical Slice (Tracer Bullet)

مدل‌های AI به‌طور طبیعی به کدنویسی افقی گرایش دارند: یک لایه‌ی کامل (مثلاً schema دیتابیس) را تمام می‌کنند و بعد سراغ لایه‌های بعدی (API، فرانت‌اند) می‌روند. برش افقی بازخورد را تا اواخر پیاده‌سازی عقب می‌اندازد.

با الهام از کتاب The Pragmatic Programmer، تسک‌ها باید به شکل Tracer Bullet (Vertical Slice) ساخته شوند:

• یک vertical slice یک مسیر باریک ولی کارا از تمام لایه‌های معماری را پیاده می‌کند (دیتابیس ← API ← UI فرانت‌اند).
• در پایان همان تسک اول، بازخورد یکپارچگی سرتاسری (end-to-end) به دست می‌آید.

┌───────────────────────────────────────────────────────────────────────┐
│ برش افقی در برابر عمودی                                               │
│                                                                       │
│ افقی (پرهیز):                         عمودی (ترجیحی):                 │
│ فاز ۱: فقط Schema دیتابیس             Slice 1: UI + API + DB (فیچر A) │
│ فاز ۲: فقط Endpoint های API           Slice 2: UI + API + DB (فیچر B) │
│ فاز ۳: فقط UI فرانت‌اند               Slice 3: UI + API + DB (فیچر C) │
│ (بازخورد یکپارچگی دیر می‌رسد!)        (بازخورد یکپارچگی فوری)         │
└───────────────────────────────────────────────────────────────────────┘

Kanban / DAG در برابر برنامه‌ی ترتیبی

به‌جای برنامه‌های چندفازی ترتیبی (فاز ۱ ← فاز ۲ ← فاز ۳)، تسک‌ها به فایل‌های issue مارک‌داون محلی تبدیل می‌شوند که به‌شکل گراف جهت‌دار بدون دور (DAG) یا برد Kanban چیده شده‌اند:

• وابستگی‌های مسدودکننده صریح تعریف می‌شوند (تسک B به A وابسته است؛ تسک C و D بعد از تمام شدن A مستقل اجرا می‌شوند).
• موازی‌سازی امن را ممکن می‌کند: چند sub-agent ایزوله می‌توانند همزمان تسک‌های بدون مانع را پردازش کنند.

---

۴. فاز ۳: اجرای AFK و مهندسی کیفیت

وقتی تسک‌ها به‌شکل vertical slice روی برد Kanban تعریف شدند، انسان از حلقه خارج می‌شود و به اجرای AFK (Away From Keyboard) می‌رود.

حلقه‌ی Ralph و Sandbox

• Ralph Loop: یک حلقه‌ی اجرای خودکار (با نام برگرفته از الگوی «Ralph Wiggum») که issue های مارک‌داون محلیِ باز را مرتب به یک agent می‌دهد تا بک‌لاگ خالی شود.
• Sandbox (Sand Castle): حلقه‌های AFK باید داخل کانتینرهای Docker ایزوله و با Git worktree ها اجرا شوند. فریمورک‌هایی مثل Sand Castle (از Matt Pocock) این کار را خودکار می‌کنند: اجرای prompt ها، ساخت branch های worktree، اجرای بررسی‌های بازخورد، و فعال کردن agent های merger/reviewer.

Test-Driven Development (TDD) به‌عنوان سقف کیفیت

LLM هایی که قبل از تست، کد پیاده‌سازی می‌نویسند، اغلب تست‌های «تقلبی» یا اعتبارسنجی‌های ناقص می‌نویسند.

• الگوی Red-Green-Refactor: prompt مدل را مجبور می‌کند اول یک تست شکست‌خورده بنویسد، test runner را اجرا کند تا شکست را تأیید کند (Red)، حداقل کد لازم برای قبولی را بنویسد (Green) و بعد refactor کند.
• حلقه‌های بازخورد: سازوکارهای بازخورد قطعی (npm run test، tsc برای type check) دقیقاً سقف عملکرد AI را تعیین می‌کنند. بدون حلقه‌ی بازخورد فوری، agent ها «کور» کد می‌نویسند.

راهبرد Code Review: Push در برابر Pull

• Agent های پیاده‌ساز (Pull): دستورالعمل‌ها را در صورت نیاز از طریق skill های داخل ریپو «می‌کشند» (pull) تا فضای context window حفظ شود.
• Agent های Reviewer (Push): reviewer های خودکار باید در یک context window پاک‌شده (Smart Zone) کار کنند. استانداردها و قوانین کدنویسی باید صریحاً به prompt ی reviewer «تزریق» (push) شوند تا کد ارسال‌شده مستقیماً با دستورالعمل‌های تثبیت‌شده سنجیده شود.

---

۵. معماری کدبیس و نگهداشت بلندمدت

کدبیس بد، agent های بد تولید می‌کند. برای حفظ کارایی AI در بلندمدت و جلوگیری از فرسایش کدبیس، معماری نرم‌افزار باید تطبیق پیدا کند.

Deep Module در برابر Shallow Module

با ارجاع به کتاب A Philosophy of Software Design از John Ousterhout:

SHALLOW MODULES (بد برای AI):
[ Interface A ] ---> [ Interface B ] ---> [ Interface C ]
  (فایل‌های کوچک زیاد با coupling و وابستگی متقابل بالا)

DEEP MODULES (خوب برای AI):
┌───────────────────────────────────────────────────────┐
│ Interface ساده                                        │
├───────────────────────────────────────────────────────┤
│ منطق داخلی و تابع‌های private                         │
│ (جزئیات سنگین پیاده‌سازی پشت یک API ساده پنهان است)   │
└───────────────────────────────────────────────────────┘

مدل ذهنی: Interface را طراحی کن، پیاده‌سازی را بسپار

برای حفظ مالکیت ذهنی روی کدبیس در حال رشد، بدون بار شناختی زیاد:

1. توسعه‌دهنده Interface ماژول‌های عمیق را تعریف و طراحی می‌کند.
2. جزئیات پیاده‌سازی داخلی را به AI agent ها می‌سپارد.
3. برای تأیید انطباق داخلی، به تست‌های واحد و یکپارچگی در مرز بیرونی ماژول تکیه می‌کند.

جلوگیری از Documentation Rot

نگه داشتن PRD ها، اسناد spec و issue های مارک‌داونِ تمام‌شده‌ی منسوخ در ریپوی فعال باعث documentation rot (پوسیدگی مستندات) می‌شود. اگر LLM اسناد قدیمی را بخواند که ارجاع‌های معماری‌شان با کد فعلی در تناقض است، عملکرد agent افت می‌کند. issue های تمام‌شده باید بسته، بایگانی (خارج از context پرامپت) یا حذف شوند.

---

کوییز کوتاه‌پاسخ

سؤال‌ها

1. چرا Matt Pocock عدد حدود ۱۰۰ هزار token را مرز عملی «Smart Zone» می‌داند، فارغ از اندازه‌ی context window تبلیغ‌شده‌ی LLM؟
2. context clearing چه فرقی با context compacting دارد و چرا در session های کدنویسی با AI، clearing ترجیح داده می‌شود؟
3. هدف اصلی مهارت «Grill Me» چیست و کدام مفهوم مهندسی نرم‌افزار از Frederick P. Brooks را عملیاتی می‌کند؟
4. PRD در جریان کار Pocock چه نقشی دارد و چرا او توصیه می‌کند توسعه‌دهنده‌ها تک‌تک خطوط آن را نخوانند؟
5. vertical slice (tracer bullet) چیست و چرا هنگام واگذاری کار به AI از کدنویسی افقی لایه‌به‌لایه بهتر است؟
6. چرا برای agent های خودکار، برد Kanban ساختاریافته به‌شکل DAG بر برنامه‌ی چندفازی ترتیبی ترجیح دارد؟
7. اجبار به TDD چطور جلوی تولید کد بی‌کیفیت یا «تقلبی» توسط مدل‌های AI را می‌گیرد؟
8. Shallow module و deep module را طبق توضیح John Ousterhout مقایسه کنید و بگویید چرا deep module ها به جریان‌های کاری AI کمک می‌کنند.
9. «documentation rot» چیست و وقتی LLM agent کدبیس را کاوش می‌کند چه مشکلی ایجاد می‌کند؟
10. چرا code review خودکار با AI باید در یک context window تازه پاک‌شده انجام شود و نه در انتهای session پیاده‌سازی؟

پاسخ‌نامه

1. چرا Matt Pocock حدود ۱۰۰ هزار token را مرز عملی «Smart Zone» می‌داند؟ افزودن token ها روابط attention را به‌صورت درجه دوم زیاد می‌کند (مثل اضافه کردن تیم به یک لیگ ورزشی) و به پردازش مدل فشار سنگینی می‌آورد. حدود ۱۰۰ هزار token مدل وارد «Dumb Zone» می‌شود؛ کیفیت استدلال به‌طور محسوس افت می‌کند و تصمیم‌های غیرمنطقی بیشتر می‌شود. به همین دلیل context window های بزرگ‌تر برای تسک‌های پیچیده‌ی کدنویسی عملاً کاربردی نیستند.

1. فرق clearing و compacting و دلیل ترجیح clearing: Compacting تاریخچه‌ی قبلی را به یک رشته‌ی خلاصه در همان session تبدیل می‌کند و «رسوب» در context باقی می‌گذارد که مدل را در Dumb Zone نگه می‌دارد. Clearing کل تاریخچه‌ی session را تا system prompt پایه حذف می‌کند و مدل را به Smart Zone بهینه برمی‌گرداند، در حالی که فایل‌های پایدار (مثل PRD) پیوستگی تسک را حفظ می‌کنند.

1. هدف «Grill Me» و مفهوم Brooks: مهارت «Grill Me» AI را وادار می‌کند بی‌وقفه از توسعه‌دهنده سؤال کند تا انتخاب‌های طراحی روشن شود و پیش از نوشتن کد هم‌ترازی حاصل گردد. این کار مفهوم «design concept» مشترک Frederick P. Brooks بین همه‌ی همکاران پروژه را عملیاتی می‌کند.

1. نقش PRD و دلیل نخواندن همه‌ی خطوط آن: PRD «سند مقصد» است که بیان مسئله، user story ها، تصمیم‌های پیاده‌سازی و مرزهای خارج از scope را ثبت می‌کند. چون هم‌ترازی در جلسه‌ی grill تعاملی انجام شده و LLM ها در خلاصه‌سازی عالی‌اند، خواندن تک‌تک خطوط کار تکراری و غیرضروری برای توسعه‌دهنده است.

1. vertical slice و برتری آن بر کدنویسی افقی: Vertical slice یک تکه‌ی نازک از قابلیت را در همه‌ی لایه‌های سیستم (دیتابیس، API و UI) در یک تسک پیاده می‌کند، به‌جای ساختن ترتیبی لایه‌های کامل. این کار در پایان هر تسک بازخورد فوری و سرتاسری درباره‌ی یکپارچگی سیستم می‌دهد.

1. چرا DAG بر برنامه‌ی ترتیبی ترجیح دارد؟ برنامه‌های ترتیبی یک حلقه‌ی واحد می‌سازند که هم‌زمان فقط یک agent می‌تواند اجرا کند. ساختار DAG وابستگی‌های صریح و تیکت‌های بدون مانع را مشخص می‌کند و اجازه می‌دهد کارهای مستقل به‌طور امن بین چند AI agent موازی شوند.

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

1. مقایسه‌ی shallow و deep module: Shallow module ها interface پیچیده و تکه‌تکه با منطق داخلی ناچیز ارائه می‌دهند و شبکه‌ی درهم وابستگی می‌سازند که ردیابی context را برای LLM گیج‌کننده می‌کند. Deep module ها interface کوچک و ساده روی منطق داخلی پیچیده ارائه می‌دهند و برای AI آسان‌تر قابل پیمایش، تست و کپسوله‌سازی‌اند.

1. documentation rot: زمانی رخ می‌دهد که فایل‌های spec منسوخ یا PRD های تمام‌شده بعد از تکامل کدبیس در ریپو باقی بمانند. وقتی LLM این اسناد کهنه را هنگام ورود به context می‌خواند، بر پایه‌ی فرض‌های نامعتبر و ارجاع‌های قدیمی به فایل‌ها عمل می‌کند.

1. چرا review در context پاک‌شده؟ session پیاده‌سازی که ده‌ها هزار token جمع کرده، LLM را در Dumb Zone قرار می‌دهد و آن را به reviewer ضعیفی برای کار خودش تبدیل می‌کند. پاک کردن context مدل را به Smart Zone برمی‌گرداند و اجازه می‌دهد یک prompt ی تازه‌ی reviewer تغییرات را با ظرفیت استدلال بهینه ارزیابی کند.

---

سؤال‌های تشریحی

این موضوع‌ها برای مطالعه‌ی عمیق‌تر و تحلیل انتقادی‌اند. پاسخی برایشان ارائه نشده است.

1. سفسطه‌ی Vibe Coding و Specs-to-Code: ارزیابی انتقادی اینکه چرا توسعه‌ی صرفاً مشخصات‌محور بدون مشارکت مداوم توسعه‌دهنده در معماری کد شکست می‌خورد؛ با استفاده از راهبردهای هم‌ترازی Pocock.
2. مدیریت context window و دینامیک افت کیفیت LLM: تحلیل فنی رشد درجه‌دومِ attention نسبت به token ها و اینکه معماری جریان کار (clearing در برابر compacting، sub-agent ها، حد Smart Zone) چطور این افت را کاهش می‌دهد.
3. نرده‌های معماری برای agent های خودکار: بحث درباره‌ی اینکه شیوه‌های سنتی نرم‌افزار، به‌ویژه TDD و Tracer Bullet (vertical slice)، چطور به‌عنوان حلقه‌ی بازخورد و سقف عملکرد برای agent های AFK عمل می‌کنند.
4. طراحی کدبیس‌های قابل پیمایش برای AI: تحلیل نظریه‌ی عمق ماژول Ousterhout در مهندسی نرم‌افزار با کمک AI و اینکه interface های deep module چطور اجازه می‌دهند توسعه‌دهنده مالکیت ذهنی را حفظ کند و پیاده‌سازی را بسپارد.
5. کنترل جریان اطلاعات: Push در برابر Pull در پایپ‌لاین‌های چند-agent: ارزیابی راهبردهای بهینه‌سازی token هنگام هماهنگ کردن agent های planner، implementer، reviewer و merger در حلقه‌های اجرای خودکار.

---

واژه‌نامه‌ی جامع