داربست — خودآموز MLOps و مهندسی سامانه‌های هوش مصنوعی (پیشرفته)

فصل ۳ از ۷

پیشرفت ترم
۰٪

در این فصل چه یاد می‌گیری#

یک README می‌سازیم با شش دستورِ مستندشده — از همان‌هایی که در هر پروژه‌ای هست و همه فرض می‌کنند کار می‌کنند. بعد تستی می‌نویسیم که آن‌ها را از داخلِ متن بیرون می‌کشد و در یک نسخهٔ تازهٔ پروژه اجرا می‌کند.

از شش دستور، یکی کار می‌کند.

بعد درستش می‌کنیم و می‌شود هفت از هفت. و همان تست را به دروازهٔ فصلِ قبل وصل می‌کنیم: عوض کردنِ نامِ یک گزینه در کد، دو دستورِ مستندشده را قرمز می‌کند — بدونِ اینکه کسی README را باز کرده باشد.

در آخر سه تصمیم‌نامه می‌نویسیم و هر کدام را با یک نگهبانِ اجراشدنی می‌سنجیم. یکی سبز است، یکی قرمز — یعنی تصمیم نوشته شده و سامانه به آن عمل نمی‌کند — و یکی اصلاً نگهبان ندارد.

دفترچهٔ راهنمایی که هر صفحه‌اش به یک اهرمِ واقعیِ دستگاه وصل است

آخر این فصل می‌توانی:

  • دستورهای یک README را استخراج و در نسخهٔ تازهٔ پروژه اجرا کنی
  • سه خانوادهٔ خرابیِ مستندات را از هم جدا کنی: غلط، ناقص، و کدی که مستند را از کار انداخته
  • مستند را به همان دروازهٔ خودکارِ کد وصل کنی
  • تصمیم‌نامه‌ای بنویسی که نگهبانِ اجراشدنی دارد

قبل از شروع#

از فصلِ ۲ همین ترم: دروازه‌ای که با کدِ خروج جواب می‌دهد. مستندِ اجراشدنی دقیقاً همان قرارداد را دارد.

از ترمِ ۳ فصلِ ۷ و ترمِ ۴ فصلِ ۶: دو تصمیمی که در بخشِ ۵ به‌شکلِ تصمیم‌نامه می‌نویسیم، با همان عددهایی که آنجا اندازه گرفتیم.

💡 نکته: همهٔ دستورهای این فصل python هستند، نه فرمانِ پوسته. دلیلش قیدِ دوره است — یک نوت‌بوک باید روی هر سیستمی یک‌جور اجرا شود، و فرمانِ پوسته این را تضمین نمی‌کند. قاعده‌اش عوض نمی‌شود: دستورِ مستندشده باید اجراشدنی باشد.

📓 نوت‌بوک: نوت‌بوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

اجرا زمانِ تقریبی
کلِ نوت‌بوک روی CPU حدودِ یک دقیقه
GPU لازم نیست

۱. پروژه، همان‌طور که واقعاً روی دیسک است#

هفت فایلِ کوچک. هیچ‌کدام موضوعِ درس نیستند؛ فقط باید واقعی باشند و واقعاً اجرا شوند.

import json
import re
import shlex

SOURCE = WORK / "source"
FILES = {
    "sample.json": None,                       # پایین‌تر پر می‌شود
    "fetch.py": '"""fetch.py — دادهٔ خام را از نمونهٔ همراهِ مخزن می‌سازد."""\n'
                "import json, pathlib\n\n"
                'rows = json.load(open("sample.json", encoding="utf-8"))\n'
                'pathlib.Path("raw").mkdir(exist_ok=True)\n'
                'json.dump(rows, open("raw/tickets.json", "w", encoding="utf-8"),'
                " ensure_ascii=False)\n"
                'print("raw/tickets.json ساخته شد:", len(rows), "ردیف")\n',
    "prepare.py": '"""prepare.py — پاک‌سازی و ذخیره در work/."""\n'
                  "import json, pathlib\n\n"
                  'rows = json.load(open("raw/tickets.json", encoding="utf-8"))\n'
                  "for row in rows:\n"
                  '    row["text"] = " ".join(row["text"].replace("ي", "ی")'
                  '.replace("ك", "ک").split())\n'
                  'pathlib.Path("work").mkdir(exist_ok=True)\n'
                  'json.dump(rows, open("work/clean.json", "w", encoding="utf-8"),'
                  " ensure_ascii=False)\n"
                  'print("work/clean.json ساخته شد:", len(rows), "ردیف")\n',
    "schema_check.py": '"""schema_check.py — قراردادِ ستون‌ها روی نمونهٔ همراهِ مخزن."""\n'
                       "import json\n\n"
                       'REQUIRED = ("ticket_id", "week", "category", "text", "escalated")\n'
                       'rows = json.load(open("sample.json", encoding="utf-8"))\n'
                       "missing = sorted(set(REQUIRED) - set(rows[0]))\n"
                       'assert not missing, f"ستونِ گم‌شده: {missing}"\n'
                       'print("قرارداد سالم است:", len(rows), "ردیف")\n',
    "train.py": '"""train.py — یک مدلِ شمارشیِ ساده روی داده‌های تا هفتهٔ upto."""\n'
                "import argparse, collections, json, pathlib\n\n"
                "parser = argparse.ArgumentParser()\n"
                'parser.add_argument("--upto", type=int, required=True)\n'
                "args = parser.parse_args()\n"
                'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                'train = [r for r in rows if r["week"] < args.upto]\n'
                "score = collections.Counter()\n"
                "for row in train:\n"
                '    for word in set(row["text"].split()):\n'
                '        score[word] += 1 if row["escalated"] else -1\n'
                'pathlib.Path("models").mkdir(exist_ok=True)\n'
                'json.dump(dict(score), open("models/model.json", "w", encoding="utf-8"),'
                " ensure_ascii=False)\n"
                'print("models/model.json ساخته شد از", len(train), "ردیف")\n',
    "evaluate.py": '"""evaluate.py — دقتِ مدل روی هفته‌های بعدی."""\n'
                   "import json\n\n"
                   'model = json.load(open("models/model.json", encoding="utf-8"))\n'
                   'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                   'test = [r for r in rows if r["week"] >= 18]\n'
                   "hit = sum((sum(model.get(w, 0) for w in r[\"text\"].split()) > 0)\n"
                   '          == bool(r["escalated"]) for r in test)\n'
                   'print(f"دقت روی {len(test)} ردیفِ آینده: {hit / len(test):.4f}")\n',
    "report.py": '"""report.py — گزارشِ کوتاهِ اجرا."""\n'
                 "import argparse, json\n\n"
                 "parser = argparse.ArgumentParser()\n"
                 'parser.add_argument("--out", required=True)\n'
                 "args = parser.parse_args()\n"
                 'rows = json.load(open("work/clean.json", encoding="utf-8"))\n'
                 'open(args.out, "w", encoding="utf-8").write(f"ردیف: {len(rows)}\\n")\n'
                 'print("گزارش نوشته شد:", args.out)\n',
    "scripts/lint.py": '"""lint.py — هر فایلِ پایتونِ پروژه باید docstring داشته باشد."""\n'
                       "import pathlib\n\n"
                       'bad = [p.name for p in sorted(pathlib.Path(".").glob("*.py"))\n'
                       '       if not p.read_text(encoding="utf-8").startswith(\'"""\')]\n'
                       'assert not bad, f"بدونِ docstring: {bad}"\n'
                       'print("همهٔ فایل‌ها docstring دارند")\n',
}
FILES["sample.json"] = json.dumps(TICKETS, ensure_ascii=False)
for name, text in FILES.items():
    write(SOURCE / name, text)
print("پروژه ساخته شد:", len(FILES), "فایل")
پروژه ساخته شد: 8 فایل

۲. READMEی که کسی امتحانش نکرده#

حالا مستند. این README دروغ نمی‌گوید؛ روی ماشینِ نویسنده‌اش واقعاً کار می‌کرده. مسئله همین است.

TICKS = "`" * 3                                # سه‌تایی‌های markdown، بدونِ درگیریِ نقلِ‌قول


def as_readme(steps):
    """همان `README`ی که در مخزن می‌نشیند: هر دستور داخلِ بلوکِ کدِ خودش."""
    blocks = "\n\n".join(f"{TICKS}bash\n{step}\n{TICKS}" for step in steps)
    return "# خطِ دسته‌بندیِ تیکت\n\n## اجرا\n\n" + blocks + "\n"


README_BROKEN = as_readme([
    "python prepare.py",
    "python schema_check.py",
    "python train.py --weeks 18",
    "python evaluate.py",
    "python report.py --out out/report.md",
    "python tools/lint.py",
])
write(SOURCE / "README.md", README_BROKEN)
BASH_BLOCK = re.compile(TICKS + r"bash\n(.*?)" + TICKS, re.S)


def commands(readme):
    """هر خطِ اجرایی داخلِ بلوک‌های bash، به ترتیبِ متن."""
    return [line.strip() for block in BASH_BLOCK.findall(readme)
            for line in block.split("\n") if line.strip().startswith("python ")]


def fresh_checkout():
    """یک نسخهٔ تازه از پروژه، مثلِ کسی که همین حالا clone کرده."""
    fresh = WORK / "fresh"
    shutil.rmtree(fresh, ignore_errors=True)
    shutil.copytree(SOURCE, fresh)
    return fresh


def run_readme(readme):
    """هر دستورِ مستندشده را در یک نسخهٔ تازه اجرا می‌کند و نتیجه‌اش را برمی‌گرداند."""
    fresh = fresh_checkout()
    write(fresh / "README.md", readme)
    out = []
    for command in commands(readme):
        parts = shlex.split(command)[1:]
        if not (fresh / parts[0]).exists():
            out.append((command, 2, "فایل پیدا نشد: " + parts[0]))
            continue
        code, text = run_py(*parts, cwd=fresh)
        out.append((command, code, text.strip().split("\n")[-1]))
    return out


BEFORE = run_readme(README_BROKEN)
print(f"{'دستورِ مستندشده':<34}{'نتیجه':>8}")
for command, code, _ in BEFORE:
    print(f"{command:<34}{('کار کرد' if code == 0 else 'شکست'):>8}")
print("کار کرد:", sum(1 for _, c, _ in BEFORE if c == 0), "از", len(BEFORE))
دستورِ مستندشده                      نتیجه
python prepare.py                     شکست
python schema_check.py             کار کرد
python train.py --weeks 18            شکست
python evaluate.py                    شکست
python report.py --out out/report.md    شکست
python tools/lint.py                  شکست
کار کرد: 1 از 6

یک از شش.

و مهم‌ترین جزئیِ این آزمایش fresh_checkout است: کلِ README از اولین دستور تا آخرین، به ترتیب، در یک نسخهٔ تازه اجرا می‌شود. اگر همه را پشتِ سرِ هم در یک پوشهٔ کارکرده اجرا کنی، بعضی‌شان کار می‌کنند — چون فایلی که لازم دارند از دفعهٔ قبل مانده. مستند برای کسی نوشته می‌شود که آن فایل‌ها را ندارد.

۳. سه خانوادهٔ خرابی#

for command, code, last in BEFORE:
    if code:
        print(f"{command}\n    {last}")
python prepare.py
    FileNotFoundError: [Errno 2] No such file or directory: 'raw/tickets.json'
python train.py --weeks 18
    train.py: error: the following arguments are required: --upto
python evaluate.py
    FileNotFoundError: [Errno 2] No such file or directory: 'models/model.json'
python report.py --out out/report.md
    FileNotFoundError: [Errno 2] No such file or directory: 'work/clean.json'
python tools/lint.py
    فایل پیدا نشد: tools/lint.py

پنج شکست، ولی سه ریشهٔ متفاوت و دو قربانی — و درمانِ هر ریشه جای دیگری است:

  • ۱) مستندِ ناقص. prepare.py به raw/tickets.json نیاز دارد و هیچ‌جا نگفته آن فایل از کجا می‌آید. نویسنده‌اش سه ماه پیش یک بار fetch.py را زده بود و یادش نمانده. درمان: یک قدمِ گم‌شده به مستند اضافه شود.
  • ۲) مستندِ غلط. گزینه زمانی --weeks بود و بعد --upto شد، و مسیرِ lint.py از tools/ به scripts/ رفت. کد جلو رفت و متن سرِ جایش ماند. درمان: متن به‌روز شود.
  • ۳) کدی که مستند را غیرقابلِ اجرا کرده. report.py می‌خواهد در out/ بنویسد ولی خودش آن پوشه را نمی‌سازد. درمان اینجا در متن نیست؛ در کد است — چون هر راهنمایی‌ای که به کاربر بگوید «اول این پوشه را بساز»، فردا یک نفر فراموشش می‌کند. این خطا در جدولِ بالا هنوز دیده نمی‌شود: report.py پیش از رسیدن به نوشتن، روی نبودِ work/clean.json می‌افتد، و خطای out/ تازه بعد از تعمیرِ prepare.py بیرون می‌آید.

شکستِ evaluate.py هم چیزِ چهارمی است: آبشار. خودش سالم است و فقط قربانیِ شکستِ مرحلهٔ قبل شده. خطایی که از report.py در جدول چاپ شد هم از همین جنس است. در گزارش‌گیری، شکستِ آبشاری را از شکستِ واقعی جدا کن، وگرنه عددت را بزرگ‌تر از واقعیت نشان می‌دهی.

README_FIXED = as_readme([
    "python fetch.py",
    "python prepare.py",
    "python schema_check.py",
    "python train.py --upto 18",
    "python evaluate.py",
    "python report.py --out out/report.md",
    "python scripts/lint.py",
])
FILES["report.py"] = FILES["report.py"].replace(
    "args = parser.parse_args()\n",
    "args = parser.parse_args()\n"
    'import pathlib\npathlib.Path(args.out).parent.mkdir(parents=True, exist_ok=True)\n')
write(SOURCE / "report.py", FILES["report.py"])
write(SOURCE / "README.md", README_FIXED)
AFTER = run_readme(README_FIXED)
print(f"{'دستورِ مستندشده':<34}{'نتیجه':>8}   خروجی")
for command, code, last in AFTER:
    print(f"{command:<34}{('کار کرد' if code == 0 else 'شکست'):>8}   {last}")
print("کار کرد:", sum(1 for _, c, _ in AFTER if c == 0), "از", len(AFTER))
دستورِ مستندشده                      نتیجه   خروجی
python fetch.py                    کار کرد   raw/tickets.json ساخته شد: 2400 ردیف
python prepare.py                  کار کرد   work/clean.json ساخته شد: 2400 ردیف
python schema_check.py             کار کرد   قرارداد سالم است: 2400 ردیف
python train.py --upto 18          کار کرد   models/model.json ساخته شد از 1800 ردیف
python evaluate.py                 کار کرد   دقت روی 600 ردیفِ آینده: 0.7933
python report.py --out out/report.md کار کرد   گزارش نوشته شد: out/report.md
python scripts/lint.py             کار کرد   همهٔ فایل‌ها docstring دارند
کار کرد: 7 از 7

هفت از هفت — و حالا ستونِ آخر یک چیزِ اضافه هم می‌دهد: مستند دیگر فقط نمی‌گوید چه بزن، می‌گوید چه ببین. «۲۴۰۰ ردیف»، «دقت ۰٫۷۹۳۳». کسی که فردا این را اجرا می‌کند، می‌داند نتیجه‌اش درست درآمده یا نه.

✅ چک کن: به تعدادِ دستورها نگاه کن، نه فقط به سهمِ موفق. از شش رفتیم به هفت، چون یک قدمِ گم‌شده اضافه شد. اگر تستِ مستندت را طوری بنویسی که فقط سهم را گزارش کند، حذف کردنِ دستورهای دردسرساز آن را ۱۰۰٪ می‌کند. عددِ درست همیشه دوتاست: چندتا از چندتا.

۴. حالا مستند هم یک دروازه دارد#

مستندِ درست، فردا هم درست نمی‌ماند — مگر اینکه چیزی نگهش دارد. آن چیز همان دروازهٔ فصلِ قبل است.

بیایید کاری بکنیم که در هر پروژه‌ای هفته‌ای یک بار اتفاق می‌افتد: نامِ یک گزینه در کد عوض شود.

def docs_gate(readme):
    """دروازهٔ مستند: چند دستورِ مستندشده در نسخهٔ تازه اجرا نمی‌شود."""
    broken = [c for c, code, _ in run_readme(readme) if code]
    return len(broken), broken


write(SOURCE / "train.py", FILES["train.py"].replace('"--upto"', '"--weeks"'))
n, broken = docs_gate(README_FIXED)
print("بعد از تغییرِ نامِ گزینه در کد — دستورِ شکسته:", n)
for command in broken:
    print("   ", command)
write(SOURCE / "train.py", FILES["train.py"])
print("بعد از برگرداندنِ کد — دستورِ شکسته:", docs_gate(README_FIXED)[0])
بعد از تغییرِ نامِ گزینه در کد — دستورِ شکسته: 2
    python train.py --upto 18
    python evaluate.py
بعد از برگرداندنِ کد — دستورِ شکسته: 0

کسی README را باز نکرد و بیلد قرمز شد. این تفاوتِ «مستندی که کهنه نمی‌شود» با «مستندی که قول داده‌ایم به‌روزش نگه داریم» است: اولی یک سازوکار است، دومی یک نیت.

و همان‌جا اولین قانونِ ثابتِ دوره برمی‌گردد: «اگر خودکار نیست، انجام نمی‌شود.» به‌روز نگه داشتنِ مستندات دقیقاً همان کاری است که همه قبولش دارند و هیچ‌کس انجامش نمی‌دهد.

این تست کند است — هفت فرآیندِ جدا و یک کپیِ کاملِ پروژه — پس جایش ردهٔ کندِ فصلِ قبل است، نه دروازهٔ هر push.

۵. تصمیم‌نامه: نوشتنِ چیزی که diff نمی‌گوید#

فصلِ ۱ نشان داد که بدنهٔ پیامِ commit جوابِ «چرا» را نگه می‌دارد. ولی بعضی «چرا»ها از یک commit بزرگ‌ترند: تصمیم‌هایی که ماه‌ها روی کلِ پروژه اثر دارند. جایشان یک فایلِ کوتاه است با پنج بندِ ثابت — و یک بندِ ششم که کمتر کسی می‌نویسد: نگهبان.

DEPLOY = ('"""deploy.py — انتشارِ نسخهٔ تازه."""\n\n'
          'STAGES = ["canary", "full"]\n'
          'print("مرحله‌ها:", STAGES)\n')
write(SOURCE / "deploy.py", DEPLOY)
write(SOURCE / "split_check.py",
      '"""split_check.py — نگهبانِ تصمیمِ ۰۰۰۱."""\n'
      "import json\n\n"
      'rows = json.load(open("sample.json", encoding="utf-8"))\n'
      'train = [r["week"] for r in rows if r["week"] < 18]\n'
      'test = [r["week"] for r in rows if r["week"] >= 18]\n'
      'assert max(train) < min(test), "زمانِ آموزش و آزمون قاطی شده"\n'
      'print("تقسیم زمانی است:", max(train), "<", min(test))\n')
write(SOURCE / "release_check.py",
      '"""release_check.py — نگهبانِ تصمیمِ ۰۰۰۲."""\n'
      "import re\n\n"
      'text = open("deploy.py", encoding="utf-8").read()\n'
      'stages = re.search(r"STAGES = \\[(.+)\\]", text).group(1)\n'
      'assert "shadow" in stages, f"مرحلهٔ سایه در deploy.py نیست: {stages}"\n'
      'print("سایه پیش از قناری هست")\n')

ADR = {
    "0001-time-split.md": """# ۰۰۰۱ — تقسیمِ زمانی به‌جای تصادفی

وضعیت: پذیرفته‌شده
زمینه: با تقسیمِ تصادفی مدلِ الف ۰٫۵۹۳۸ می‌گرفت و مدلِ ب ۰٫۵۲۲۱.
تصمیم: ارزیابی فقط روی برشِ زمانیِ بعدی انجام می‌شود.
پیامد: رتبه‌بندی وارونه شد — الف ۰٫۲۲۷۱ و ب ۰٫۴۲۵۱ روی آینده.
بدیلِ ردشده: تقسیمِ تصادفی با چند seed. عددِ بهتری می‌داد و بی‌ربط بود.
نگهبان: python split_check.py
""",
    "0002-shadow-before-canary.md": """# ۰۰۰۲ — سایه پیش از قناری

وضعیت: پذیرفته‌شده
زمینه: قناریِ پنج‌درصدی با متریکِ تجمیعی در ۱۳ گروه از ۲۰ گروهِ ممکن مدلِ خراب را منتشر کرد.
تصمیم: هر انتشار اول مرحلهٔ سایه دارد، با متریکِ تفکیک‌شدهٔ زیرگروه.
پیامد: همان مدل در سایه با صفر کاربرِ آسیب‌دیده متوقف شد.
بدیلِ ردشده: بالا بردنِ سهمِ قناری. نمونه را بیشتر می‌کرد و آسیب را هم.
نگهبان: python release_check.py
""",
    "0003-keyword-model.md": """# ۰۰۰۳ — مدلِ شمارشیِ ساده

وضعیت: پذیرفته‌شده
زمینه: مدلِ سنگین‌تر روی این حجمِ داده جواب نمی‌داد.
تصمیم: فعلاً همان مدلِ شمارشی می‌ماند.
""",
}
FIELDS = ("وضعیت:", "زمینه:", "تصمیم:", "پیامد:", "بدیلِ ردشده:", "نگهبان:")
for name, text in ADR.items():
    write(SOURCE / "docs/adr" / name, text)


def audit_adr():
    """هر تصمیم‌نامه: بندهای لازم را دارد؟ نگهبانش همین حالا چه می‌گوید؟"""
    fresh = fresh_checkout()
    rows = []
    for name in sorted(ADR):
        text = (fresh / "docs/adr" / name).read_text(encoding="utf-8")
        missing = [f.rstrip(":") for f in FIELDS if f not in text]
        guard = re.search(r"نگهبان: (.+)", text)
        if not guard:
            state = "نگهبان ندارد"
        else:
            code, out = run_py(*shlex.split(guard.group(1))[1:], cwd=fresh)
            state = ("سبز" if code == 0 else "قرمز") + " — " + out.strip().split("\n")[-1]
        rows.append((name, missing, state))
    return rows


for name, missing, state in audit_adr():
    print(name)
    print("    بندِ گم‌شده:", "، ".join(missing) or "ندارد")
    print("    نگهبان:", state)
0001-time-split.md
    بندِ گم‌شده: ندارد
    نگهبان: سبز — تقسیم زمانی است: 17 < 18
0002-shadow-before-canary.md
    بندِ گم‌شده: ندارد
    نگهبان: قرمز — AssertionError: مرحلهٔ سایه در deploy.py نیست: "canary", "full"
0003-keyword-model.md
    بندِ گم‌شده: پیامد، بدیلِ ردشده، نگهبان
    نگهبان: نگهبان ندارد

سه تصمیم‌نامه، سه وضعیتِ کاملاً متفاوت — و اگر فقط می‌خواندیشان، هر سه یک‌جور به نظر می‌رسیدند.

۰۰۰۱ سبز است: تصمیم نوشته شده و سامانه به آن عمل می‌کند.

۰۰۰۲ قرمز است، و این بدترین حالتِ ممکن است. یک تصمیمِ مکتوب، مستند، با زمینه و عدد و بدیلِ ردشده — و deploy.py مرحلهٔ سایه ندارد. یعنی تیم فکر می‌کند این محافظت را دارد و ندارد. بدونِ نگهبان، این وضع تا روزِ حادثه کشف نمی‌شد.

۰۰۰۳ اصلاً تصمیم‌نامه نیست، یک یادداشت است. «فعلاً همان می‌ماند» نه پیامدی دارد، نه بدیلی، نه نگهبانی. جملهٔ «مدلِ سنگین‌تر جواب نمی‌داد» هیچ عددی ندارد — پس شش ماهِ دیگر هیچ‌کس نمی‌تواند بگوید هنوز درست است یا نه.

۶. تصمیم را واقعی کن#

write(SOURCE / "deploy.py", DEPLOY.replace('["canary"', '["shadow", "canary"'))
for name, missing, state in audit_adr():
    print(name, "→", state)
0001-time-split.md → سبز — تقسیم زمانی است: 17 < 18
0002-shadow-before-canary.md → سبز — سایه پیش از قناری هست
0003-keyword-model.md → نگهبان ندارد

یک کلمه در deploy.py اضافه شد و تصمیم از «نوشته‌شده» به «برقرار» رفت. این تفاوتِ مستندسازی و اجراست، و نگهبان تنها چیزی است که آن‌ها را از هم جدا نگه می‌دارد.

📏 اندازه بگیر: با چه چیزی مقایسه شد؟ با خودِ همان مستند، پیش و پس از تعمیر: ۱ از ۶ به ۷ از ۷. روی کدام داده؟ روی یک نسخهٔ تازهٔ پروژه در هر اجرا — که تنها شرطِ معنادار بودنِ این آزمایش است. با چند seed؟ اینجا تصادفی در کار نیست و همین را باید صریح گفت: این اندازه‌گیری قطعی است، و اگر روی ماشینِ تو عددِ دیگری داد، یعنی محیطت با نسخهٔ تازه فرق دارد — که خودش یافتهٔ مهمی است، نه نوسان.

🔧 اگر کار نکرد: اگر تستِ مستند روی سیستمِ تو همه را «کار کرد» نشان داد، اولین چیزی که باید ببینی fresh_checkout است — احتمالاً پوشهٔ قبلی پاک نشده و فایل‌های مرحله‌های قبل مانده‌اند. اگر shutil.copytree با FileExistsError: [WinError 183] ایستاد، همان یک ردیفِ rmtree بالایش اجرا نشده. و اگر re.search روی بندِ «نگهبان» AttributeError: 'NoneType' object has no attribute 'group' داد، تصمیم‌نامه‌ای آن بند را ندارد — که خودش جوابِ سؤال است، پس در کد به‌جای try یک شرطِ صریح گذاشته‌ایم.

🤖 از دستیارت بپرس: «تصمیم‌نامه (ADR) چیست و چه بندهایی دارد؟» بعد این را بپرس: «برای هر بندی که گفتی، یک راهِ خودکار پیشنهاد بده که نقضش را بگیرد.» — بندهایی که جوابِ خوبی نمی‌گیرند، همان‌هایی‌اند که در عمل هم کسی رعایتشان نمی‌کند.

واژه‌های تازهٔ این فصل#

کلمه تلفظ به حروف فارسی یعنی چه
executable documentation اگزکیوتبل داکیومنتیشن مستندی که دستورهایش واقعاً اجرا و آزموده می‌شوند
fresh checkout فرش چک‌اوت نسخهٔ تازهٔ پروژه، بدونِ هیچ فایلِ به‌جامانده از کارهای قبلی
ADR ای‌دی‌آر تصمیم‌نامه: یک فایلِ کوتاه که زمینه، تصمیم، پیامد و بدیل‌ها را نگه می‌دارد
doctest داک‌تست اجرای نمونه‌های داخلِ مستند به‌عنوان تست
stale docs استیل داکس مستندی که کد از آن جلو زده و کسی خبر ندارد

تمرین‌ها

اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.

در فصل بعد#

تا اینجا از آنچه می‌دانیم محافظت کردیم: کد، داده، مستند. فصلِ بعد سراغِ آن چیزی می‌رود که هنوز اتفاق نیفتاده.

یک سیاههٔ ریسک می‌سازیم که ردیف‌هایش شکست‌های واقعیِ پنج ترمِ قبل‌اند، هر کدام با احتمال و اثر و این سؤال که «آیا چیزی خودکار می‌گیردش؟». و بعد یک ردِ ممیزی می‌سازیم: یک شمارهٔ پیش‌بینی می‌دهی و کد بازسازی می‌کند که کدام نسخهٔ داده، کدام نسخهٔ کد و کدام نسخهٔ مدل آن جواب را ساخته.

به آخر این فصل رسیدی!

اگر ساختی و جواب داد، این دکمه مال توست.