قبل از کد، طرح اجرا را نقد کن

قبل از اولین ویرایش، مسیر تغییر را قابل نقد کنید

مسئله، محدوده و معیارهای «تمام‌شدن» از قبل روشن شده‌اند. با این حال هنوز یک شکست رایج باقی می‌ماند: یک AI یا همکار planی می‌دهد که منطقی به نظر می‌رسد، اما یک dependency را ندیده، change surface را قطعی فرض کرده یا روش verification را به آخر کار موکول کرده است. اگر مستقیم وارد edit شوید، تازه بعد از ایجاد Diff می‌فهمید جهت تغییر از ابتدا مشکل داشته است.

در این درس Plan Review Record v1 می‌سازید: یک رکورد کوتاه و قابل بازبینی که برای هر گام plan نشان می‌دهد Trace اصلی آن به کدام scope item یا acceptance criterion وصل است، کدام constraintهای مرتبط باید به‌صورت check/annotation ثانویه ثبت شوند، چه change surfaceای را پیشنهاد می‌کند، چه dependency یا unknownی دارد، چه assumption/riskی باید بررسی شود و با چه verificationی می‌توان آن را پذیرفت یا اصلاح کرد. در پایان یک انسان plan مشخص را با دلیل ACCEPT، MODIFY یا REJECT می‌کند.

این درس spec را بازنویسی نمی‌کند و هنوز code review نیست. همچنین handoff جامع اجرای کار را نمی‌سازد؛ یک plan مشخص را پیش از کدنویسی نقد می‌کند.

زمان فعال تقریبی: ۴۵ دقیقه.

این درس برای شماست اگر: از specification مستقیم به implementation می‌پرید، یا plan پیشنهادی را فقط به این دلیل می‌پذیرید که مرتب، فنی و قانع‌کننده به نظر می‌رسد.

این درس برای این کارها نیست: بازنویسی Problem Brief/Scope Box/Done Matrix، شروع edit قبل از review، تبدیل فهرست فایل‌های پیشنهادی به scope قطعی، code review بعد از Diff، یا ساخت handoff نهایی اجرای کل قابلیت.

پیش‌نیاز سخت — FND-001-P03: باید بتوانید Done Matrix v1 را طوری بسازید که criterion، روش اثبات و evidence state مستقل از implementation plan قابل داوری باشند.

پروب کوتاه پیش‌نیاز

کیس: بعد از upload فایل، نتیجهٔ success یا failure همان تلاش باید برای کاربر قابل مشاهده باشد. constraint این است که storage provider عوض نشود.

دو ردیف کوتاه Done Matrix بنویسید: یکی برای success و یکی برای failure. در هر ردیف criterion observable، proof method و evidence state اولیه را مشخص کنید. سپس در یک خط جدا، constraint «storage provider عوض نشود» را با proof method مناسب و evidence state اولیه ثبت کنید. هنوز plan یا فایل پیشنهادی ننویسید.

PASS فقط با ۵/۵: criterionها رفتار را می‌گویند نه implementation؛ proof method از criterion جداست؛ success/failure مستقل قابل داوری‌اند؛ constraintِ storage provider یک proof method مشخص دارد؛ و همهٔ evidenceها پیش از اجرا NOT_RUN می‌مانند، نه PASS فرضی.

اگر یکی از این چهار مورد شکست خورد، فقط همان بخش از FND-001-P03 را repair کنید و probe را تکرار کنید. plan خوب نمی‌تواند معیار «Done» مبهم را جبران کند.

میزان راهنمایی مناسب را انتخاب کنید

همهٔ مسیرها به یک Plan Review Record v1 و یک evidence bar می‌رسند؛ فقط میزان scaffold فرق می‌کند.

پروب چهارمفهومی مسیر

بدون خواندن ادامه، این چهار سؤال را کوتاه جواب دهید:

1. Implementation plan: چرا plan نمی‌تواند scope یا criterion جدید بسازد؟
2. Change surface: چرا «این سه فایل حتماً باید تغییر کنند» معمولاً statement ضعیف‌تری از «این سطوح اکنون محتمل‌اند و باید با repository evidence تأیید شوند» است؟
3. Plan assumption and risk: فرق assumption تصمیم‌ساز با fact چیست و قبل از approval چه اتفاقی باید برایش بیفتد؟
4. Plan review gate: چرا خروجی AI—even اگر دقیق به نظر برسد—خودش authority پذیرش plan نیست؟

۴/۴ → مسیر باتجربه/Fast Path؛ ۲–۳/۴ → فقط مفهوم‌های شکست‌خورده را repair کنید؛ ۰–۱/۴ → مسیر پایه.

• پایه: کیس مشترک فیلتر task list را با scaffold کامل پیش ببرید.
• ترمیم: فقط distinction شکننده را بازسازی کنید.
• باتجربه/Fast Path: مستقیم به کیس مستقل بروید؛ در آن contradiction، unknown و dependency ambiguity عمداً باقی مانده است.

Fast Path evidence bar را پایین نمی‌آورد؛ فقط راهنمایی مرحله‌به‌مرحله را حذف می‌کند.

مدل ذهنی: طرح اجرا یک فرضیهٔ تغییر است، نه قرارداد قطعی

Plan Review Record v1 بین specification و edit قرار می‌گیرد. specification می‌گوید چه رفتار و مرزی باید حفظ شود؛ plan می‌گوید برای رسیدن به آن، فعلاً چه مسیر فنی‌ای پیشنهاد می‌شود. این پیشنهاد باید قابل رد یا اصلاح باشد.

یک plan خوب الزاماً طولانی نیست. باید بتوانید از هر step به specification برگردید و بگویید «چرا این step وجود دارد، چه چیزی را ممکن است لمس کند، چه چیزی هنوز نمی‌دانیم و قبل/بعد از آن چه checkی داریم.»

چهار مفهوم پایه

۱. طرح اجرا / Implementation plan

طرح اجرا نقشهٔ پیشنهادی تغییر قبل از edit است: stepها، ترتیب، surfaceهای درگیر و verificationهای لازم. plan نباید requirement تازه ایجاد کند. Trace اصلی هر step باید به یک scope item یا acceptance criterion موجود وصل شود و بتوان آن را حذف، جابه‌جا یا اصلاح کرد. constraint مرتبطِ specification را می‌توان به‌صورت check/annotation ثانویه ثبت کرد، اما constraint جای Trace اصلی scope/criterion را نمی‌گیرد. constraint را به criterion ساختگی تبدیل نکنید.

۲. سطح تغییر / Change surface

Change surface تصویری فنی و موقت از جاهایی است که plan احتمال می‌دهد تحت اثر باشند: UI، service، data contract، config، test surface یا فایل‌های مرتبط. دو برچسب مفید کنار هر surface بنویسید: READ/WRITE و confidence/unknown. اگر scan واقعی repository نشان داد surface دیگری لازم است، plan باید بازبینی شود؛ scope نباید برای هماهنگ‌شدن با فهرست فایل اولیه کش بیاید.

۳. فرض و ریسک طرح / Plan assumption and risk

Assumption ادعایی است که plan به آن تکیه دارد ولی evidence کافی برایش نداریم؛ risk پیامدی است که اگر assumption یا انتخاب plan غلط باشد رخ می‌دهد. برای assumption بنویسید evidence needed؛ برای risk بنویسید mitigation/check. عبارت «احتمالاً همین‌طور است» closure نیست.

۴. دروازهٔ تأیید طرح / Plan review gate

قبل از edit، یک انسان plan و نسخهٔ specification را کنار هم می‌گذارد و تصمیم می‌گیرد:

• ACCEPT: plan فعلی برای شروع کار evidence کافی دارد؛
• MODIFY: مسیر کلی قابل استفاده است اما step/surface/assumption/check باید اصلاح شود؛
• REJECT: plan با specification یا evidence موجود تعارض بنیادی دارد.

دلیل تصمیم و نسخهٔ spec/plan ثبت می‌شود. این gate code review نیست؛ code review بعداً Diff واقعی را می‌بیند.

Plan Review Record v1 را چگونه بسازیم؟

ورودی شما Problem Brief v1، Scope Box v1، Done Matrix v1 و یک implementation plan پیشنهادی است. این‌ها را با هم ادغام نکنید؛ از آن‌ها برای نقد plan استفاده کنید.

برای هر step این فیلدها کافی‌اند:

بالای artifact نسخهٔ specification و نسخهٔ plan را بنویسید و در انتها Overall decision = ACCEPT/MODIFY/REJECT + reason را ثبت کنید.

چهار قاعدهٔ ساخت:

1. هر step باید Trace اصلی داشته باشد. Trace اصلی باید به scope item یا acceptance criterion وصل شود. constraintهای مرتبطِ specification را جداگانه به‌صورت check/annotation ثانویه ثبت کنید؛ constraint به‌تنهایی Trace اصلی معتبر نیست. step بدون Trace معتبر scope/criterion candidate برای حذف یا توضیح صریح است.
2. surface را hypothesis نگه دارید. فهرست فایل یا component فقط تا وقتی معتبر است که repository evidence آن را پشتیبانی کند.
3. unknown را زنده نگه دارید. اگر dependency یا ownership روشن نیست، plan را بر مبنای حدس approve نکنید.
4. verification را قبل از edit تعریف کنید. check باید نشان دهد step به criterion نزدیک شده و regression مشخصی ایجاد نکرده است.

AI می‌تواند plan را critique کند، dependency احتمالی پیشنهاد دهد یا inconsistency را پیدا کند؛ اما اجازه ندارد unknown را به fact تبدیل کند، scope را عوض کند یا gate انسانی را جایگزین کند.

مثال حل‌شده: نقد طرح اجرای فیلتر فهرست کارها

Packet identity: spec_version=TASK-SPEC-01 و plan_version=TASK-PLAN-01.

Specification موجود می‌گوید کاربر می‌تواند «همهٔ taskها» یا «فقط ناتمام‌ها» را ببیند؛ completed در حالت unfinished پنهان است؛ storage schema تغییر نمی‌کند؛ persistence فیلتر و redesign خارج از scope هستند. Done Matrix نیز behaviorهای مربوط به نمایش، بازگشت به All و حفظ schema را قابل اثبات کرده است.

AI این plan را پیشنهاد می‌دهد:

1. بعد از دریافت taskها، در UI list را filter کن.
2. state فیلتر را در component نگه دار.
3. data layer را تغییر نده چون status از قبل موجود است.
4. یک UI test برای unfinished view اضافه کن.

plan مرتب است، اما review باید سؤال کند: آیا filtering بعد از fetch با pagination فعلی سازگار است؟ اگر backend صفحه‌بندی‌شده فقط ۲۰ task برگرداند، filter کردن سمت UI ممکن است صفحه‌ای خالی نشان دهد درحالی‌که task ناتمام در صفحهٔ بعد وجود دارد. repository evidence این ترتیب را هنوز تأیید نکرده است.

یک Plan Review Record فشرده:

Overall decision: MODIFY. دلیل: plan از نظر جهت کلی قابل استفاده است، اما assumption مربوط به pagination تصمیم‌ساز است و باید قبل از edit روشن شود. این تصمیم scope را گسترش نمی‌دهد؛ اگر evidence نشان دهد server-side filtering لازم است، plan دوباره نوشته می‌شود و هر surface جدید باید به همان specification trace شود.

چهار خطای محتمل

خطا ۱: plan به spec trace نمی‌شود

Stepهایی مثل «service را refactor کن» یا «cache اضافه کن» ممکن است فنی و جذاب باشند، اما اگر Trace اصلی آن‌ها به scope item یا acceptance criterion وصل نیست، plan می‌تواند در حال ساختن کار تازه باشد. repair: برای هر step Trace اصلی scope/criterion بنویسید و constraint مرتبط را فقط به‌صورت check/annotation ثانویه ثبت کنید؛ بدون Trace اصلی معتبر، step را حذف کنید یا justification صریح بدهید.

خطا ۲: فهرست فایل‌ها به قرارداد تبدیل می‌شود

«فقط این سه فایل تغییر می‌کنند» وقتی repository هنوز بررسی نشده، certainty جعلی می‌سازد. repair: surface را proposed بنویسید، READ/WRITE و confidence را ثبت کنید و discovery را مجاز نگه دارید.

خطا ۳: assumption به‌صورت fact وارد plan می‌شود

«این service حتماً synchronous است» بدون evidence می‌تواند ترتیب stepها را خراب کند. repair: assumption + evidence-needed + نتیجهٔ review را ثبت کنید. تا وقتی assumption تصمیم‌ساز unresolved است، plan نیازمند MODIFY است.

خطا ۴: plan فقط «منطقی به نظر می‌رسد»

یک plan خوش‌ساخت می‌تواند verification ناقص یا scope expansion داشته باشد. repair: review را against specification و Done Matrix انجام دهید؛ نه against حس معماری یا اعتماد به AI.

پل مسیر باتجربه: وقتی evidence با plan سازگار نیست

در repository واقعی، plan اغلب قبل از discovery کامل ساخته می‌شود. ممکن است یک comment بگوید filtering client-side است، یک test integration نشان دهد server query روی status اعمال می‌شود، و ownership یک cache یا event contract روشن نباشد. وظیفهٔ reviewer این نیست که یک روایت را حدس بزند؛ باید contradiction را در Record نگه دارد و بگوید کدام step تا روشن‌شدن evidence قابل قبول نیست.

برای planهای پیچیده سه فشار اضافه وارد کنید:

• یک dependency که وجودش معلوم است اما contract دقیقش unknown است؛
• دو evidence item که به تفسیرهای متفاوت از change surface منجر می‌شوند؛
• یک step که اگر زود انجام شود Diff پرهزینه یا rollback دشوار ایجاد می‌کند.

در این حالت MODIFY یا REJECT شکست نیست. gate دقیقاً برای جلوگیری از edit بر پایهٔ confidence مصنوعی وجود دارد.

شکل‌های مختلف طرح اجرا و بده‌بستان آن‌ها

Plan می‌تواند checklist، جدول، sequence کوتاه یا issue breakdown باشد. قالب مهم نیست؛ invariantها مهم‌اند.

• Checklist کوتاه: سریع و مناسب تغییرهای کوچک؛ ولی trace/assumption ممکن است پنهان شود.
• جدول traceability: برای review مستقل قوی است؛ ممکن است برای کار بسیار کوچک سنگین باشد.
• Dependency-first sequence: ریسک ترتیب را خوب نشان می‌دهد؛ اگر scope trace نداشته باشد می‌تواند به planning معماری تبدیل شود.
• AI-generated prose plan: سریع است؛ ولی certainty زبانی آن می‌تواند unknown و surface hypothesis را پنهان کند.

Plan Review Record v1 قرار نیست format همهٔ planها را جایگزین کند. یک لایهٔ review است که چهار سؤال ثابت را روی هر format اعمال می‌کند: trace؟ surface؟ assumption/risk؟ human gate؟

تمرین هدایت‌شده و مستقل

تمرین هدایت‌شده — Order search

Packet identity: spec_version=ORD-SPEC-03 و plan_version=ORD-PLAN-01.

Specification packet:

• in scope: جست‌وجوی سفارش با شمارهٔ کامل در صفحهٔ سفارش‌ها؛
• constraint: schema سفارش تغییر نکند؛
• out of scope: fuzzy search، جست‌وجوی نام مشتری، redesign؛
• Done: exact match نمایش داده شود، no-match حالت واضح داشته باشد، مسیر فعلی فهرست سفارش‌ها خراب نشود.

Plan پیشنهادی:

1. input جست‌وجو را به صفحه اضافه کن؛
2. query جدید برای exact order number بساز؛
3. result state را render کن؛
4. smoke test برای match/no-match اجرا کن.

Review کنید: کدام stepها trace دارند؟ آیا query layer واقعاً change surface قطعی است یا فقط proposal؟ چه evidence لازم است تا بدانیم endpoint موجود قابلیت exact lookup ندارد؟ plan را ACCEPT/MODIFY/REJECT کنید و دلیل بنویسید.

کیس مستقل — Fast Path destination: Avatar refresh

Packet identity: spec_version=AVATAR-SPEC-02 و plan_version=AVATAR-PLAN-07.

Specification packet:

• in scope: بعد از جایگزینی موفق avatar، تصویر جدید در بازدید بعدی profile قابل مشاهده باشد؛
• constraint: قرارداد API upload و storage provider تغییر نکند؛
• out of scope: crop editor، avatar history، redesign profile؛
• Done criteria: success تصویر جدید را قابل مشاهده می‌کند؛ failure تصویر فعلی را حفظ و خطای واضح می‌دهد؛ API/storage contract unchanged می‌ماند.

Plan پیشنهادی:

1. پس از success، URL فعلی avatar را با query token جدید render کن.
2. client cache entry را حذف کن.
3. هیچ server/CDN change انجام نده.
4. success/failure و refresh بعدی را verify کن.

Evidence packet:

• repository note A: profile client یک cache محلی برای image URL دارد؛
• operations note B: «برخی avatarها پشت CDN cache باقی می‌مانند و invalidation ممکن است لازم باشد»؛
• API contract: upload response URL را برمی‌گرداند، اما TTL/cache ownership در این packet مشخص نیست؛
• dependency state: ownership و رفتار cache بین client/CDN unknown است؛ دو note هنوز reconcile نشده‌اند.

Plan Review Record v1 بسازید. contradiction و unknown را صریح نگه دارید. حق ندارید حدس بزنید client-only یا CDN-only راه درست است. stepی که بر این assumption تکیه دارد باید CHANGE/unresolved بماند و overall gate تا evidence کافی MODIFY یا در صورت تعارض بنیادی REJECT باشد. سپس یک check محدود بنویسید که چه evidenceای قبل از edit باید ambiguity را حل کند.

چطور بفهمیم Plan Review Record کافی است؟

قبل از approval این پنج سؤال را پاسخ دهید:

1. آیا هر plan step به scope یا criterion مشخص trace می‌شود؟
2. آیا change surface با READ/WRITE و سطح اطمینان/unknown ثبت شده و به‌عنوان scope قطعی ارائه نشده است؟
3. آیا assumptionهای تصمیم‌ساز evidence-needed و riskهای مهم mitigation/check دارند؟
4. آیا verification هر step قبل از edit تعریف شده و با Done Matrix سازگار است؟
5. آیا انسان تصمیم ACCEPT/MODIFY/REJECT، دلیل و نسخهٔ spec/plan را ثبت کرده است؟

اگر answer یکی از موارد بحرانی «نه» است، approval زودهنگام است. machine validation یا نظر AI می‌تواند consistency را بررسی کند، اما sufficiency artifact و gate تصمیم انسانی‌اند.

ارزیابی و انتقال

در پایان باید بتوانید بدون template پرشده، روی یک change request تازه:

• plan پیشنهادی را به specification trace کنید؛
• surfaceهای read/write و unknownها را به‌صورت پیشنهادی ثبت کنید؛
• assumption و risk را از fact جدا کنید؛
• verification را قبل از edit تعریف کنید؛
• و یک gate انسانی با دلیل صادر کنید.

معیار transfer این نیست که wording کیس task list را تکرار کنید. باید همان invariantها را در domain جدید حفظ کنید.

مرز درس بعدی: اینجا فقط یک plan را review می‌کنید. مرحلهٔ بعدی تصمیم‌های قبلی را در یک handoff آمادهٔ اجرا یکپارچه و traceability/ambiguity کل بسته را audit می‌کند. آن artifact جامع را در این درس نسازید.

منابع و تازگی

Authority اصلی نام، artifact، چهار مفهوم و مرز این درس همان curriculum specification قفل‌شده است. استانداردها و مستندات ابزار فقط برای context و sanity-check استفاده می‌شوند و format Plan Review Record v1 را تعریف نمی‌کنند.

در بازبینی ۵ سپتامبر ۲۰۲۶، ISO/IEC/IEEE 29148:2018 همچنان Edition 2 منتشرشده و نسخهٔ فعلی بود، اما در وضعیت بازنگری قرار داشت؛ Edition 3 هنوز Draft International Standard و غیرنهایی بود. مستندات زندهٔ ابزارهای coding-agent نیز workflowهای planning/review/verification را مرتب تغییر می‌دهند. به همین دلیل این درس هیچ رفتار محصولی خاص، نام mode یا guarantee یک ابزار را به‌عنوان قانون مهندسی آموزش نمی‌دهد.

اگر بعداً یک claim جاری دربارهٔ ابزار یا standard به متن اضافه شود، همان source باید پیش از publication دوباره بررسی شود.