بخش آسان و بخش سخت
پرسیدهشدن برای مستندسازی چیزی — چه از طرف همتیمی، چه یک چکلیست، چه پرسش سرور MCP در WKFGo بعد از بستن یک تسک — مشکل «کِی» را حل میکند. مشکل «چه چیزی» را حل نمیکند. به «این را بنویسم؟» بله بگویید، فوراً با یک صفحهٔ خالی روبهرو میشوید. بیشتر پوسیدگی ویکی از تعداد کم صفحه نمیآید؛ از صفحاتی میآید که کسی نمیتواند استفادهشان کند، چون نویسندهاش بله گفته ولی نمیدانسته چه بنویسد.
آزمون: آیا با تغییر کد زنده میماند؟
یک قاعدهٔ مفید: اگر کد اطراف فردا کاملاً عوض شود، این صفحه هنوز درست خواهد بود؟
آزمون را رد میکند — بنویسیدش:
- چرا یک رویکرد غیربدیهی بهجای رویکرد بدیهی انتخاب شده («این نوشتهها را دستهای نمیکنیم چون سرویس صف اندازهٔ دسته را روی ۱۰ محدود کرده و دو بار در تولید به آن برخوردهایم»)
- محدودیتی که در خود کد دیده نمیشود (یک محدودیت نرخ، یک SLA قراردادی، یک الزام قانونی)
- نتیجهٔ یک بررسی، حتی یک بنبست («X را امتحان کردیم، بهخاطر Y کار نمیکند — بدون تغییر Y دوباره امتحانش نکنید»)
- یک تصمیم با بدهبستان واقعی، و اینکه چه چیزی را رها کردید
آزمون را قبول نمیکند — جای دیگری متعلق است، یا هیچجا:
- چطور کد فعلی کار میکند، قدمبهقدم — این کار خود کد است؛ صفحهٔ ویکیای که آن را تکرار کند فقط کهنه میشود
- گزارش وضعیت («مهاجرت را تمام کردم، همهچیز خوب است») — این یک کامنت یا یک ورودی چنجلاگ است، نه دانش پایدار
- هرچیزی که به همان اندازهٔ کد اطرافش زیاد تغییر میکند
برای کسی با صفر زمینه بنویسید
کسی که بعداً این صفحه را میخواند — شاید یک ایجنت هوش مصنوعی باشد که میخواند، نه یک آدم — آن مکالمهای که هنگام کار در ذهنتان داشتید را ندارد. دو عادت بیشتر این را حل میکند:
محدودیت را قبل از راهحل بگویید. «صف دستهها را روی ۱۰ محدود میکند، پس نوشتهها را تکهتکه میکنیم» حتی برعکس هم درست خوانده میشود. «نوشتهها را تکهتکه میکنیم بهخاطر صف» خواننده را مجبور میکند دنبال معنی «بهخاطر صف» بگردد.
چیزی که رد کردید را هم نام ببرید، نه فقط چیزی که انتخاب کردید. «از پولینگ استفاده میکنیم، نه وبهوک، چون سرویس مقصد از آنها پشتیبانی نمیکند» به خوانندهٔ آینده میگوید دوباره وبهوک را پیشنهاد ندهد. فقط مستند کردن «از پولینگ استفاده میکنیم» شش ماه بعد همان بحث را دوباره باز میکند.
یک مثال کارشده
صفحهٔ ویکی بد: «منطق تلاش مجدد در ورکر پرداخت را بهروز کردم.» درست است، ولی یک ماه دیگر بیفایده — این یک خط چنجلاگ است، نه مستندسازی.
بهتر: «ورکر پرداخت شارژهای ناموفق را تا ۳ بار با backoff نمایی، با سقف ۳۰ ثانیه، دوباره امتحان میکند. روی پاسخهای 4xx دوباره امتحان نمیکنیم — اینها خطاهای دائمی هستند (کارت بد، موجودی کافی نیست) و تلاش مجدد فقط خطای دیدهشده توسط کاربر را به تعویق میاندازد. فقط 5xx و timeout دوباره امتحان میشوند.»
نسخهٔ دوم حتی اگر سال بعد کسی حلقهٔ تلاش مجدد را بازنویسی کند هم زنده میماند، چون قاعده را مستند میکند، نه کد را.
این چطور به MCP وصل میشود
وقتی ایجنتی که از طریق MCP کار میکند یک تسک را تمام میکند و WKFGo میپرسد آیا مستند شود، ایجنت زمینهٔ واقعی برای نوشتن دارد — محدودیت واقعیای که به آن برخورده، جایگزین واقعیای که سنجیده. این نقطهٔ شروع بهتری است نسبت به آدمی که یک هفته بعد از روی یک diff سعی میکند استدلال را بازسازی کند. با اینحال ارزش یک نگاه سریع قبل از تأیید را دارد؛ پیشنویس اول یک ایجنت هم از همان فیلتر «آیا با تغییر کد زنده میماند» سود میبرد.
سؤالات متداول
هر تسکی باید صفحهٔ ویکی بگیرد؟
نه — بیشتر تسکها روتین هستند و چیزی ارزش ثبت پایدار ندارند. سؤال این است که آیا همین تسک خاص به یک تصمیم غیربدیهی، محدودیت یا بنبست برخورده.
یادداشتهای روتین «چه چیزی تغییر کرد» کجا جا دارند؟
پیامهای کامیت و رشتهٔ کامنت خود تسک — هر دو از قبل وجود دارند، هر دو طبیعتاً به کار وصلاند، هیچکدام نیازی به صفحهٔ ویکی ندارند.
یک صفحهٔ ویکی باید چقدر بلند باشد؟
آنقدر کوتاه که کسی کل آن را بخواند. یک ثبت تصمیم پنجپاراگرافی از یک سند معماری سیصفحهای که کسی بازش نمیکند بهتر است.
اگر بعداً معلوم شود تصمیم اشتباه بوده چه؟
صفحه را نگه دارید و یک یادداشت اضافه کنید — تصمیمی که جایگزین شده با استدلالش دستنخورده هنوز مفید است؛ به نفر بعدی میگوید چرا رویکرد قدیمی آن موقع درست بهنظر میرسیده، که معمولاً چیزی دربارهٔ رویکرد جدید هم توضیح میدهد.
جمعبندی
پرسیدهشدن برای مستندسازی یک محرک است. دانستن اینکه چه بنویسید یک مهارت است: محدودیت و جایگزین ردشده را ثبت کنید، نه مکانیکی که کد از قبل نشان میدهد.