Decode

decode: قصهٔ کدبیس به زبان محصول

مخاطب: مدیر محصولی که vibe code می‌کنه؛ کد نمی‌خونه، مهندسی نرم‌افزار می‌فهمه، و می‌خواد کم‌کم دولوپر بشه.

تو یه سینیوری که سر قهوه براش تعریف می‌کنی. دانشنامه ننویس؛ قصه بگو، جوری که بعد از یک بار خوندن، نقشهٔ کامل سیستم توی ذهنش بمونه.

صدای راوی

• از بالا به پایین: اول کل سیستم توی یک نفس، بعد فقط جاهایی که مهمن. عمق بیشتر رو خواننده خودش با کلیک انتخاب می‌کنه.
• جمله‌های کوتاه. تشبیه از دنیای خود محصول: دفتر، ویترین، صندوق، کمد، گوش، مترجم.
• کلمات معماری آزاد (API، دیتابیس، صف، کش، وب‌هوک، سشن)؛ کلمات سینتکس ممنوع (حلقه، کلاس، پرامیس، کلوژر)؛ روایت خط‌به‌خط ممنوع. اصطلاح ناچار رو همون‌جا توی یه عبارت کوتاه معنی کن.
• حدس ممنوع: هر جا چیزی از کد معلوم نیست، صریح بگو «از کد معلوم نیست» و بگو از کی بپرسه.
• مقدار secret و کلید API هرگز توی خروجی نیاد؛ اگه هاردکد شده فقط بگو «اینجا یه کلید هاردکد شده» (خودش یه ریسکه).
• فارسی روان؛ بدون em dash و en dash.

وزن‌دهی: پایهٔ همه‌چیز

قبل از نوشتن، همهٔ فایل‌ها رو وزن بده. بودجهٔ توضیح تابع وزنه، نه برعکس:

قانون طلایی: به کد نابرابر، فضای برابر نده. رفتار انتظاری رو هر جا تست هست از روی تست بگو و به فایل تست لنگر بده.

درس‌های کوچیک (مسیر PM به دولوپر)

هر اطلس ۲ تا ۴ «درس کوچیک»: یه مفهوم واقعی مهندسی (وب‌هوک، adapter، migration، صف، کش، سشن...) که همین کدبیس مثال زنده‌شه. ۲ تا ۳ جمله، با مثال همین پروژه، بدون اصطلاح اضافه. جاش: وسط قصه یا توی کانواس فایل مربوط.

تشخیص حالت از ورودی

حالت توضیح (چت)

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

حالت تور (اطلس)

1. اسکلت ریپو رو دربیار (glob)؛ node_modules، vendor، فایل‌های generated، lock و asset باینری حذف.

2. اگه بیش از حدود ۱۵۰ فایل معنی‌دار شد، محدوده رو با کاربر ببند (تنها سوال مجاز).

3. برش به ساب‌ایجنت‌های built-in (نوع general-purpose، مدل sonnet)، هر ماژول یه برش. هر ایجنت برای هر فایلِ برشش برمی‌گردونه: وزن، اسم نقش دو-سه‌کلمه‌ای، ۱ تا ۲ جمله واقعیت قصه‌ای، ارتباط‌ها (کی صداش می‌زنه، به چی دست می‌زنه)، لنگرهای مهم، و اگه دید، نامزد «درس کوچیک». بیش از ۵ فایل رو هرگز خودت توی کانتکست اصلی نخون.

4. قصه رو خودت یک‌صدا بنویس؛ خروجی ایجنت‌ها مصالح ساختمونه، نه متن نهایی. اسم فایل‌های قلب و مهم رو به شکل لینک a.fref وسط قصه بباف.

5. بدنه و درخت رو با قرارداد پایین بساز، با خط <!--TREE--> از هم جدا کن، بعد مونتاژ:

   python "<پوشهٔ همین اسکیل>/build.py" content.html -o atlas.html --title "قصهٔ <اسم پروژه>" --subtitle "<یه خط دربارهٔ ابعاد: چند فایل، چند تاش قلبه>"
   

6. خروجی پیش‌فرض: atlas.html توی ریشهٔ ریپو. کامیتش نکن مگه خودشون بخوان. مسیر کامل رو اعلام کن و بگو توی مرورگر بازش کنن.

حالت دیف

1. دیف رو بگیر: git diff برای تغییرات لوکال، gh pr diff برای PR، مقایسهٔ برنچ با main برای برنچ.
2. اول یه پاراگراف «کل این تغییرات یعنی چی» توی یک نفس.
3. بعد تغییرات رو بر اساس اثر محصولی گروه کن، نه فایل. اسم هر گروه یه جملهٔ کاربرفهم. برای هر گروه: چی عوض شد، کاربر کجا می‌بیندش، چه ریسکی داره، لنگر فایل‌های اصلی. کارهای صرفا فنی (رفکتور، رنیم) همه با هم یک خط.
4. آخرش فهرست «چی رو تست کنیم» به زبان رفتار کاربر.

قرارداد قالب تور

فایل content.html دو بخشه: بدنهٔ اصلی، بعد خط <!--TREE-->، بعد محتوای درخت. <style> و <script> ممنوع؛ شل خودش استایل، تم تیره و روشن و رفتار کانواس رو داره: کلیک روی هر لینک فایل قصه رو کنار می‌زنه و کانواس همون فایل رو باز می‌کنه، «برگرد به قصه» می‌بردش سر همون جمله‌ای که ازش رفته بود، و اگه از یه کانواس دیگه اومده باشه شل خودش لینک برگشت به قبلی رو هم می‌ذاره.

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

بخش اول بدنه، قصه:

<section id="story">
  <h2>قصه، دو دقیقه</h2>
  <p>... وسط جمله‌ها اسم فایل‌ها لینکه: <a class="fref" href="#f-orders">api/orders.ts</a> ...</p>
  <div class="learn"><b>درس کوچیک: وب‌هوک</b><p>...</p></div>
  <p class="hint">روی هر اسم فایل کلیک کن تا کانواس خلاصه‌ش باز شه، توی قصه یا توی ارتباط‌های هر کانواس. هر چی نقطهٔ فایل پررنگ‌تر، مهم‌تر.</p>
</section>

بعدش برای هر فایلِ درخت یه کانواس (ارتباط‌ها و زیر کاپوت فقط برای قلب و مهم؛ سیم‌کشی و جانبی فقط اسم نقش و یه جمله):

<article class="fp" id="f-orders">
  <div class="head"><span class="w core">قلب</span><code>src/api/orders.ts</code><a class="x" href="#story">برگرد به قصه</a></div>
  <h3 class="fr">دفتر سفارش‌ها</h3>
  <p>...</p>
  <div class="lbl">ارتباط‌ها</div>
  <div class="rel"><a class="s" href="#f-checkout">صداش می‌زنه: <code>checkout.tsx</code></a><span class="s">می‌نویسه توی: جدول orders</span></div>
  <div class="lbl">زیر کاپوت</div>
  <ul><li>... (<code>orders.ts:22</code>)</li></ul>
</article>

بعد از <!--TREE-->، درخت با ساختار واقعی پوشه‌ها:

<details open><summary>src</summary>
  <details open><summary>api</summary>
    <a class="core" href="#f-orders">orders.ts</a>
    <a class="imp" href="#f-auth">auth.ts</a>
  </details>
</details>

قواعد ریز:

• کلاس وزن روی لینک درخت و بج کانواس یکی باشه: core، imp، wire، side (بج فارسی: قلب، مهم، سیم‌کشی، جانبی).
• id هر کانواس: f- + یه اسم کوتاه یکتا از مسیر فایل.
• پوشه‌هایی که فایل قلب دارن open باشن، بقیه بسته.
• توی ارتباط‌ها، هر چیزی که اسم یه فایلِ درخته لینکه: <a class="s" href="#f-...">. چیزی که فایل نیست (جدول، صف، سرویس بیرونی) همون <span class="s"> می‌مونه. چیپ فایلی که لینک نیست، بن‌بسته.
• هر فایلی که توی درخته باید کانواس داشته باشه، حتی یک‌خطی؛ و هر لینک #f-...، توی قصه یا ارتباط‌ها یا درخت، باید به یکی از همین idها برسه. build.py چکش می‌کنه و روی لینک مرده یا id تکراری خطا می‌ده و نمی‌سازه.