درس 03. تبدیل مخزن به یگانه منبع حقیقت | مهندسی هارنس

Code examples: code/ Practice project: Project 02. Make the Agent Read the Project and Pick Up Where It Left Off

تصمیمات معماری تیم شما در Confluence، Slack، Jira و ذهن چند مهندس ارشد پراکنده است. این وضعیت برای انسان‌ها به‌سختی کار می‌کند — شما می‌توانید از یک همکار بپرسید، پیام‌های گفتگو را جستجو کنید، مستندات را بکاوید، و در نهایت اگر همه‌چیز بی‌نتیجه ماند، کسی را در اتاق استراحت گیر بیندازید. اما برای یک ایجنت (agent) هوش مصنوعی، اطلاعاتی که در مخزن (repository) نیستند، اصلاً وجود ندارند.

این یک اغراق نیست. یک ایجنت تنها سه منبع ورودی دارد: پرامپت‌های سیستم و شرح وظایف، محتوای فایل‌ها از مخزن، و خروجی اجرای ابزارها. تاریخچهٔ اسلک شما، تیکت‌های جیر، صفحات کانفلوئنس، و آن تصمیم معماری که عصر جمعه با همکارتان بر سر آن توافق کردید — ایجنت هیچ‌کدام را نمی‌تواند ببیند. ایجنت نمی‌تواند «برود از کسی بپرسد» یا «گزارش‌های چت را بگردد». تمام دنیای کاری آن خود مخزن است. دربارهٔ هر چیزی بیرون از آن، هیچ دانشی ندارد.

بنابراین پرسش واقعی این است: آیا قرار است نقشه‌ای به اندازهٔ کافی خوب به آن بدهید؟

چه چیزی باید روی نقشه باشد#

شرکت OpenAI در مقالهٔ مهندسی هارنس (harness) خود این نکته را به‌روشنی بیان می‌کند: اطلاعاتی که در مخزن وجود ندارند، برای ایجنت وجود ندارند. آن‌ها این موضوع را اصل «مخزن به‌عنوان مشخصات» می‌نامند — یعنی خود مخزن بالاترین مرجع سند مشخصات است.

مستندات ایجنت‌های بلندمدت شرکت Anthropic نیز بر نکته‌ای مشابه تأکید دارد: وضعیت (state) پایدار یک شرط لازم برای پیوستگی وظایف طولانی است، و قابلیت بازیابی دانش بین نشست‌ها مستقیماً نرخ موفقیت وظایف را تعیین می‌کند. و این وضعیت باید در مخزن وجود داشته باشد — زیرا تنها حافظهٔ پایدار و با دسترسی قابل‌اعتمادی است که ایجنت در اختیار دارد.

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

این یک مشکل «مستندات بیشتر بنویسید» نیست — بلکه مشکل «اطلاعات تصمیم‌گیری را در جای مناسب بگذارید» است. یک فایل 50 خطی ARCHITECTURE.md در دایرکتوری src/api/ بسیار مفیدتر از یک سند طراحی 500 صفحه‌ای در کانفلوئنس است که هیچ‌کس از آن نگهداری نمی‌کند. نزدیکی بیشتر از طولانی بودن اهمیت دارد، زیرا اطلاعات زمانی واقعاً سودمند هستند که دقیقاً در همان لحظهٔ نیاز در دسترس باشند.

قابلیت مشاهدهٔ دانش#

flowchart LR
    Slack["Rules in Slack"] --> Write["Write into repo files<br/>AGENTS.md / ARCHITECTURE.md / PROGRESS.md"]
    Confluence["Rules in Confluence"] --> Write
    Heads["Rules in engineers' heads"] --> Write
    Jira["Rules in Jira"] --> Write
    Write --> Repo["Repository files"]
    Repo --> Agent["New agent session<br/>reads the repo directly"]
    Warning["If a rule isn't in the repo,<br/>the agent can't see it"] --> Agent

چگونه آزمایش می‌کنید که نقشه‌تان به اندازهٔ کافی خوب است؟ یک «آزمون نشست تازه» اجرا کنید: یک نشست کاملاً جدید از ایجنت را باز کنید، فقط محتویات مخزن را در اختیارش بگذارید، و بررسی کنید آیا می‌تواند به این پنج پرسش پایه‌ای پاسخ دهد:

flowchart TB
    Q1["What is this system?"] --> A1["AGENTS.md / README"]
    Q2["How is it organized?"] --> A2["ARCHITECTURE.md / module docs"]
    Q3["How do I run it?"] --> A3["Makefile / init.sh / package scripts"]
    Q4["How do I verify it?"] --> A4["Test, lint, check commands"]
    Q5["Where are we now?"] --> A5["PROGRESS.md / feature list / git history"]

    A1 --> Ready["A new session can start work<br/>without asking a human"]
    A2 --> Ready
    A3 --> Ready
    A4 --> Ready
    A5 --> Ready

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

مفاهیم اصلی#

شکاف مشاهده‌پذیری دانش (Knowledge Visibility Gap): نسبتی از کل دانش پروژه که در مخزن نیست. هر چه شکاف بزرگ‌تر باشد، نرخ شکست ایجنت بیشتر است. می‌توانید آن را این‌گونه برآورد کنید: تمام دانش ضمنی دربارهٔ پروژه را که در ذهن افراد است بشمارید، سپس ببینید چه مقدار از آن واقعاً وارد مخزن شده است. این تفاوت، همان شکاف مشاهده‌پذیری شماست.
منبع مرجع (System of Record): مخزن کد به‌عنوان منبع معتبر و نهایی برای تصمیمات پروژه، محدودیت‌های معماری، وضعیت اجرا، و استانداردهای راستی‌آزمایی (verification). مخزن حرف آخر را می‌زند — هیچ جای دیگر ملاک نیست. اگر اطلاعات «این مسیر بسته است» فقط در ذهن یک همکار قدیمی باشد، هر بار باید از او سؤال کنید. اگر آن را در مخزن بنویسید، دیگر کسی نیاز به سؤال پرسیدن نخواهد داشت.
آزمون نشست تازه (Fresh Session Test): پنج پرسش بخش پیشین. اینکه ایجنت به چه تعداد از آن‌ها می‌تواند پاسخ دهد، نشان‌دهندهٔ میزان کامل بودن نقشهٔ شماست.
هزینهٔ اکتشاف (Discovery Cost): چه میزان از بودجهٔ زمینه را ایجنت برای یافتن یک تکه اطلاعات کلیدی در مخزن مصرف می‌کند. هر چه اطلاعات پنهان‌تر باشد، هزینهٔ اکتشاف بالاتر است و بودجهٔ کمتری برای وظیفهٔ اصلی باقی می‌ماند. اطلاعات حیاتی باید در جایی قرار گیرند که ایجنت اول از همه آن‌ها را ببیند — نه اینکه در عمق ده لایه دایرکتوری دفن شده باشند.
نرخ زوال دانش (Knowledge Decay Rate): نسبتی از مدخل‌های دانش در مخزن که در واحد زمان کهنه و نامعتبر می‌شوند. ناهماهنگ شدن مستندات با کد، بزرگ‌ترین دشمن است — بدتر از نبود مستندات، وجود مستنداتی است که قدیمی و منسوخ شده‌اند.
تمثیل ACID: به‌کارگیری اصول تراکنش‌های پایگاه داده (اتمام‌پذیری، سازگاری، انزوا، پایایی) در مدیریت وضعیت ایجنت. در ادامه به تشریح آن می‌پردازیم.

چگونه یک نقشهٔ خوب ترسیم کنیم#

اصل 1: دانش در کنار کد زندگی می‌کند. قاعده‌ای دربارهٔ احراز هویت اندپوینت‌های API باید در کنار کد API قرار گیرد، نه اینکه در اعماق یک سند غول‌پیکر سراسری دفن شود. یک سند کوتاه در دایرکتوری هر ماژول قرار دهید و مسئولیت‌ها، رابط‌ها، و محدودیت‌های خاص آن ماژول را شرح دهید. دایرکتوری خود ماژول یک فهرست راهنمای طبیعی است — وقتی ایجنت به کد می‌رسد، به محدودیت‌ها نیز می‌رسد، بدون نیاز به جستجو.

اصل 2: از یک فایل ورودی استاندارد استفاده کنید. فایل AGENTS.md (یا CLAUDE.md) «صفحهٔ فرود» ایجنت است. نیازی نیست تمام اطلاعات را در خود جای دهد، اما باید به ایجنت امکان دهد به‌سرعت به سه پرسش پاسخ دهد: «این پروژه چیست»، «چگونه آن را اجرا کنم»، و «چگونه آن را راستی‌آزمایی کنم». 50 تا 100 خط کافی است.

اصل 3: کمینه اما کامل. هر بخش از دانش باید کاربردی شفاف داشته باشد. اگر حذف یک قاعده بر کیفیت تصمیم‌گیری ایجنت اثری ندارد، آن قاعده نباید وجود داشته باشد. اما هر پرسشی از آزمون نشست تازه باید پاسخی داشته باشد. این یک تعادل همیشگی است که باید حفظ شود — نه خیلی زیاد، نه خیلی کم، درست به اندازه.

اصل 4: به‌روزرسانی همگام با کد. به‌روزرسانی دانش را به تغییرات کد پیوند بزنید. ساده‌ترین رویکرد: مستندات معماری را در دایرکتوری همان ماژول بگذارید. وقتی کد را ویرایش می‌کنید، به‌طور طبیعی متوجه سند می‌شوید. پس از تغییرات کد، CI می‌تواند یادآوری کند که بررسی کنید آیا مستندات نیاز به به‌روزرسانی دارند یا خیر.

ساختار ملموس مخزن:

project/
├── AGENTS.md              # Entry: project overview, run commands, hard constraints
├── src/
│   ├── api/
│   │   ├── ARCHITECTURE.md  # API layer architecture decisions
│   │   └── ...
│   ├── db/
│   │   ├── CONSTRAINTS.md   # Database operation hard constraints
│   │   └── ...
│   └── ...
├── PROGRESS.md             # Current progress: done, in-progress, blocked
└── Makefile                # Standardized commands: setup, test, lint, check

مدیریت وضعیت ایجنت با اصول ACID#

این تمثیل برگرفته از مدیریت تراکنش‌های پایگاه داده است. شاید احساس کنید این موضوع بیش از حد پیچیده شده است، اما در عمل چارچوبی بسیار کاربردی فراهم می‌کند:

اتمام‌پذیری (Atomicity): یک «عملیات منطقی» (مثلاً افزودن یک اندپوینت و به‌روزرسانی آزمون‌های آن) تنها زمانی به‌صورت یکپارچه کامیت می‌شود که کامل و راستی‌آزمایی شده باشد. تلاش ناموفق یا رهاشده دور ریخته می‌شود، نه اینکه به‌صورت ناقص ادغام گردد. یا همه‌چیز یا هیچ‌چیز.
سازگاری (Consistency): گزاره‌های راستی‌آزمایی «وضعیت سازگار» را تعریف کنید — تمام آزمون‌ها پاس شوند، لینت صفر خطا گزارش دهد. ایجنت پس از هر عملیات، راستی‌آزمایی را اجرا می‌کند؛ وضعیت‌های میانی ناسازگار نباید کامیت شوند. پس از یک عملیات، سیستم باید در وضعیتی با درستی قابل‌اثبات باشد.
انزوا (Isolation): وقتی چندین ایجنت به‌طور هم‌روند کار می‌کنند، فایل‌های وضعیت را به‌گونه‌ای طراحی کنید که از شرایط رقابتی (race conditions) جلوگیری شود. رویکرد ساده: هر ایجنت از فایل پیشرفت اختصاصی خود استفاده کند، یا از شاخه‌های گیت برای انزوا بهره ببرید. نوشتن هم‌زمان در یک فایل منبع رایج دردسرها است.
پایایی (Durability): دانش حیاتی پروژه در فایل‌هایی نگهداری می‌شود که توسط گیت ردیابی می‌شوند. وضعیت موقت می‌تواند در حافظهٔ نشست بماند، اما دانشی که باید در طول نشست‌ها زنده بماند باید در فایل‌ها نوشته شود. آنچه در ذهن شماست به‌حساب نمی‌آید — فقط آنچه نوشته شده به‌حساب می‌آید.

رویکرد OpenAI: دانش مخزن به‌عنوان منبع مرجع#

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

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

OpenAI

شرکت OpenAI گزارش می‌دهد که حدود 1,500 پول‌ریکوئست (PR) باز و ادغام‌شده در طول پنج ماه توسط تیم کوچکی متشکل از سه مهندس با استفاده از Codex به ثبت رسیده است، با میانگین توان عملیاتی 3.5 پول‌ریکوئست به‌ازای هر مهندس در روز. تیم بعداً به هفت نفر افزایش یافت. این‌ها نتایج عملیاتی گزارش‌شده برای کل ساختار مهندسی هستند؛ مقاله سهم مستندات مخزن را به‌صورت جداگانه تفکیک نمی‌کند. OpenAI: Harness engineering

نکات کلیدی#

دانشی که در مخزن نیست برای ایجنت وجود ندارد. قرار دادن اطلاعات تصمیم‌گیری حیاتی در مخزن، اساسی‌ترین سرمایه‌گذاری در هارنس است — نقشه‌ای خوب ترسیم کنید تا گم نشوید.
از «آزمون نشست تازه» برای ارزیابی کیفیت مخزن بهره ببرید: آیا یک نشست کاملاً جدید می‌تواند تنها با استفاده از محتویات مخزن به پنج پرسش پایه‌ای پاسخ دهد؟
دانش باید نزدیک کد، کمینه اما کامل، و همگام با کد به‌روزرسانی شود. موضوع نوشتن مستندات بیشتر نیست — موضوع قرار دادن اطلاعات در جای مناسب است.
از اصول ACID برای وضعیت ایجنت استفاده کنید: کامیت‌های اتمام‌پذیر، راستی‌آزمایی سازگاری، انزوای هم‌روندی، و پایایی دانش حیاتی.
زوال دانش بزرگ‌ترین دشمن است. مستندات منسوخ‌شده خطرناک‌تر از نبود مستندات هستند — ایجنت را به مسیر غلط می‌فرستند در حالی که ایجنت گمان می‌کند در مسیر درست است.

منابع بیشتر#

تمرین‌ها#

آزمون نشست تازه: یک نشست کاملاً تازه از ایجنت را در پروژهٔ خود باز کنید (هیچ‌گونه زمینهٔ کلامی ارائه ندهید)، بگذارید تنها محتویات مخزن را ببیند، سپس پنج پرسش از آن بپرسید: این سیستم چیست؟ چگونه سازماندهی شده است؟ چگونه آن را اجرا کنم؟ چگونه آن را راستی‌آزمایی کنم؟ پیشرفت کنونی کجاست؟ مواردی را که نمی‌تواند پاسخ دهد ثبت کرده و سپس مخزن را بهبود دهید تا بتواند به همهٔ آن‌ها پاسخ دهد.
سنجش کمّی بیرونی‌سازی دانش: تمام تصمیمات و محدودیت‌های مهم برای کارهای توسعه را در پروژهٔ خود فهرست کنید. هر مورد را با برچسب داخل یا خارج مخزن علامت‌گذاری نمایید. شکاف مشاهده‌پذیری دانش خود را محاسبه کنید (نسبت مواردی که بیرون مخزن هستند). برنامه‌ای بریزید تا این شکاف را به زیر 10% برسانید.
ارزیابی ACID: مدیریت وضعیت پروژهٔ خود را با استفاده از تمثیل ACID این درس ارزیابی کنید. اتمام‌پذیری — آیا عملیات ایجنت می‌تواند به‌طور پاک بازگردانده (rollback) شود؟ سازگاری — آیا مخزن دارای راستی‌آزمایی «وضعیت سازگار» است؟ انزوا — آیا چند ایجنت هم‌روند تداخل ایجاد می‌کنند؟ پایایی — آیا تمام دانش بین نشست‌ها به‌درستی پایدار می‌شود؟