درس 06. وادار کردن ایجنت به مقداردهی اولیه پیش از هر نشست کاری | مهندسی هارنس

Code examples: code/ Practice project: Project 03. Multi-session continuity

شما یک نشست جدید از ایجنت (agent) را آغاز می‌کنید و به آن می‌گویید «یک قابلیت جستجو اضافه کن». ایجنت مستقیماً وارد کدنویسی می‌شود — اشتیاقی تحسین‌برانگیز. پس از 20 دقیقه متوجه می‌شود که چارچوب آزمون به‌درستی پیکربندی نشده است، 10 دقیقه دیگر را صرف اصلاح آن می‌کند، سپس می‌بیند قالب اسکریپت مایگریشن پایگاه داده اشتباه است، و باز هم کلنجار رفتن بیشتر. در نهایت قابلیت جستجو اضافه می‌شود، اما کل نشست ناکارآمد بود. بیشتر زمان صرف «سردرآوردن از سازوکار این پروژه» شد تا نوشتن خود قابلیت جستجو.

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

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

دو نوع کار با ماهیتی بنیادین متفاوت#

مقداردهی اولیه و پیاده‌سازی، اهداف بهینه‌سازی کاملاً متفاوتی دارند. هدف فاز پیاده‌سازی، به حداکثر رساندن تعداد و کیفیت قابلیت‌های راستی‌آزمایی‌شده است. هدف فاز مقداردهی اولیه، به حداکثر رساندن قابلیت اطمینان و کارایی تمام پیاده‌سازی‌های پس از آن است.

وقتی مقداردهی اولیه و پیاده‌سازی را ترکیب می‌کنید، ایجنت با یک مسئلهٔ بهینه‌سازی چندهدفه روبه‌رو می‌شود: باید هم‌زمان زیرساخت بسازد و کد قابلیت را بنویسد. بدون اولویت‌بندی صریح، ایجنت به‌طور طبیعی به سمت نوشتن کد متمایل می‌شود (چون خروجی مستقیماً مشهود است) و زیرساخت را فدا می‌کند (زیرا ارزش زیرساخت تنها در نشست‌های بعدی آشکار می‌شود). نتیجه: زیرساخت محکم ساخته نمی‌شود، و قابلیت اطمینان کد قابلیت‌ها نیز آسیب می‌بیند.

چرخهٔ حیات مقداردهی اولیه#

flowchart TB
    subgraph Wrong["Mixed into one session (wrong)"]
        W1["Start feature work immediately"] --> W2["Discover env and test gaps mid-task"]
        W2 --> W3["Accumulate unverified code"]
        W3 --> W4["Next session must rediscover project state"]
    end

    subgraph Right["Dedicated initialization phase (right)"]
        R1["Session 1: environment runnable"] --> R2["Example test passing"]
        R2 --> R3["Startup readiness checklist + task list written"]
        R3 --> R4["Clean checkpoint committed"]
        R4 --> R5["Later sessions start directly on verified tasks"]
    end

چه اتفاقی می‌افتد وقتی آن‌ها را ترکیب می‌کنید#

مستقیم‌ترین مشکل: زیرساخت محکم ساخته نمی‌شود. ایجنت بیشتر توان خود را صرف کد قابلیت‌ها می‌کند و با زیرساخت به‌عنوان موضوعی فرعی برخورد می‌نماید. چارچوب آزمون پیکربندی می‌شود اما هرگز راستی‌آزمایی نمی‌گردد، قواعد لینت تنظیم می‌شوند اما بیش از حد سست هستند، و هیچ فایل پیشرفتی ایجاد نمی‌شود. این کاستی‌ها در نشست اول آشکار نیستند (زیرا ایجنت هنوز به یاد دارد چه کرده است)، اما در نشست دوم خود را نشان می‌دهند: ایجنت جدید نمی‌داند چگونه پروژه را اجرا کند، چگونه آزمون بگیرد، یا کارها در چه وضعیتی قرار دارند.

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

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

مشکلی که ساده‌تر از همه نادیده گرفته می‌شود، مین‌های ناشی از فرض‌های ضمنی است. تصمیماتی که ایجنت در زمان مقداردهی اولیه می‌گیرد (کدام چارچوب آزمون، نحوهٔ سازماندهی دایرکتوری‌ها، مدیریت وابستگی‌ها) — اگر به‌طور صریح ثبت نشوند، نشست‌های بعدی ممکن است انتخاب‌هایی متناقض داشته باشند. نشست اول Vitest را به‌عنوان چارچوب آزمون برمی‌گزیند، اما ایجنت نشست دوم این را نمی‌داند و Jest را معرفی می‌کند. دو چارچوب آزمون در کنار هم قرار می‌گیرند، و هزینه‌های نگهداری دوبرابر می‌شود.

پژوهش‌های Anthropic روی ایجنت‌های بلندمدت مقداردهی اولیه را به یک نشست اولیهٔ مجزا تبدیل می‌کند. مقداردهی اولیه یک اسکریپت init.sh، یک فایل پیشرفت، یک فهرست ویژگی‌ها (feature list)، و کامیت اولیهٔ گیت را می‌نویسد؛ نشست‌های کدنویسی بعدی آن وضعیت را می‌خوانند، روی یک قابلیت در هر زمان کار می‌کنند، آن را سرتاسری (end-to-end) آزمون می‌کنند، کامیت می‌زنند، و فایل پیشرفت را به‌روزرسانی می‌نمایند.

راهنمای مهندسی هارنس (harness) مدل Codex از شرکت OpenAI نیز بر اصل «مخزن به‌عنوان سوابق عملیاتی» تأکید دارد: ساختار عملیاتی شفاف را از همان نخستین اجرا برقرار سازید، در غیر این صورت هر نشست جدید مجبور است قراردادهای پروژه را از نو استنتاج کند.

مفاهیم اصلی#

فاز مقداردهی اولیه (Initialization Phase): نخستین فاز در چرخهٔ حیات ایجنت — تنها پیش‌نیازهای پیاده‌سازی‌های بعدی را تثبیت می‌کند، بدون توسعهٔ هیچ‌گونه قابلیتی. خروجی آن زیرساخت است، نه کد کسب‌وکار.
چک‌لیست آمادگی راه‌اندازی (Startup Readiness Checklist): شرایطی که تحت آن‌ها یک نشست تازه از ایجنت می‌تواند بدون ابهام با پروژه کار کند: بتواند اجرا کند، بتواند آزمون بگیرد، بتواند پیشرفت را ببیند، و بتواند گام‌های بعدی را ادامه دهد. هر چهار شرط الزامی هستند.
شروع از صفر در برابر شروع از قالب: شروع از صفر یعنی ایجنت باید ساختار پروژه را خودش از یک دایرکتوری خالی استنتاج کند؛ شروع از قالب یعنی زیرساخت از قبل مستقر شده است. شروع از قالب عملکردی بسیار فراتر از شروع از صفر دارد.
همواره آماده برای تحویل: پروژه در هر لحظه در وضعیتی است که یک ایجنت تازه می‌تواند هدایت آن را به دست گیرد. نیازی به توضیح کلامی نیست — صرف نگاه کردن به محتویات مخزن (repository) برای ادامهٔ کار کفایت می‌کند.
زمان از شروع تا نخستین آزمون قبولی: زمان سپری‌شده از آغاز پروژه تا لحظه‌ای که نخستین ویژگی آزمون راستی‌آزمایی را پاس می‌کند. این سنجهٔ اصلی برای اندازه‌گیری کارایی مقداردهی اولیه است.
نرخ موفقیت نشست‌های بعدی: نسبتی از نشست‌های بعدی که می‌توانند وظایف را بدون اتکا به دانش ضمنی با موفقیت اجرا کنند. این بهترین معیار برای سنجش کیفیت مقداردهی اولیه است.

چگونه مقداردهی اولیه را درست انجام دهیم#

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

1. محیط قابل‌اجرا. پروژه شروع به کار می‌کند، وابستگی‌ها نصب شده‌اند، و هیچ مشکل محیطی وجود ندارد.

2. چارچوب آزمون قابل‌راستی‌آزمایی. دست‌کم یک آزمون نمونه پاس می‌شود، که اثبات می‌کند خود چارچوب آزمون به‌درستی پیکربندی شده است.

3. سند چک‌لیست آمادگی راه‌اندازی. سندی شفاف که به نشست‌های بعدی می‌گوید:

# Startup Readiness Checklist

## Start Commands
- Install dependencies: `make setup`
- Start dev server: `make dev`
- Run tests: `make test`
- Full verification: `make check`

## Current State
- All dependencies installed and locked
- Test framework configured (Vitest + React Testing Library)
- Example test passing (1/1)
- Lint rules configured (ESLint + Prettier)

## Project Structure
- src/ — Source code
- src/components/ — React components
- src/api/ — API client
- tests/ — Test files

4. تفکیک وظایف. کل پروژه را به یک فهرست مرتب از وظایف تقسیم کنید، که هر وظیفه دارای معیارهای پذیرش شفاف باشد:

# Task Breakdown

## Task 1: User Authentication Basics
- Implement JWT auth middleware
- Add login/register endpoints
- Acceptance: pytest tests/test_auth.py all passing

## Task 2: User Profile Page
- Implement user profile CRUD
- Add profile edit form
- Acceptance: pytest tests/test_profile.py all passing

## Task 3: Search Feature
- ...

5. کامیت گیت به‌عنوان نقطهٔ بررسی (checkpoint). پس از تکمیل مقداردهی اولیه، یک نقطهٔ بررسی در وضعیت تمیز (clean state) کامیت کنید. تمام کارهای بعدی از این نقطهٔ بررسی آغاز می‌شوند.

شروع از یک قالب: کار را از یک دایرکتوری خالی آغاز نکنید. از یک قالب پروژه (مانند create-react-app یا fastapi-template و غیره) برای پیش‌تنظیم ساختار استاندارد دایرکتوری، پیکربندی وابستگی‌ها، و چارچوب آزمون بهره ببرید. مراحل مشترک مقداردهی اولیه را در قالب تعبیه کنید، تا تنها کارهای مقداردهی اولیهٔ ویژهٔ پروژه باقی بماند.

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

## Initialization Acceptance Checklist
- [ ] `make setup` succeeds from scratch
- [ ] `make test` has at least one passing test
- [ ] A new agent session can answer "how to run" and "how to test" from repo contents alone
- [ ] Task breakdown file exists with at least 3 tasks
- [ ] Everything committed to git

مثالی از دنیای واقعی#

مقایسهٔ دو رویکرد مقداردهی اولیه برای یک پروژهٔ فرانت‌اند React:

رویکرد ترکیبی: ایجنت هم‌زمان داربست پروژه را ایجاد کرد و نخستین قابلیت را در نشست 1 پیاده‌سازی نمود. در پایان نشست، مخزن دارای کدی قابل‌اجرا بود اما هیچ مستندات صریحی برای دستورات اجرا/آزمون، هیچ فایل ردیابی پیشرفت، و هیچ تفکیک وظیفه‌ای وجود نداشت. نشست 2 حدود 20 دقیقه را صرف استنتاج ساختار پروژه، چارچوب آزمون، و فرایند بیلد کرد.

مقداردهی اولیهٔ اختصاصی: نشست 1 تنها مقداردهی اولیه را انجام داد — ساختار دایرکتوری را از روی یک قالب ایجاد کرد، چارچوب آزمون (Vitest + React Testing Library) را پیکربندی نمود، یک آزمون نمونه نوشت و راستی‌آزمایی کرد، چک‌لیست آمادگی راه‌اندازی و فایل تفکیک وظایف را ایجاد نمود، و نقطهٔ بررسی اولیه را کامیت کرد. زمان بازسازی در نشست 2 کمتر از 3 دقیقه بود، و مستقیماً کار را از روی فهرست وظایف آغاز کرد.

مقایسهٔ کل چرخهٔ پروژه: کل زمان بازسازی در رویکرد ترکیبی (در تمام نشست‌ها) حدود 60% بیشتر از رویکرد مقداردهی اولیهٔ اختصاصی بود. آن 20 دقیقه زمان اضافه‌ای که از ابتدا صرف مقداردهی اولیه شد، بارها در نشست‌های بعدی جبران شد. اندکی زمان بیشتر در ابتدا سرمایه‌گذاری کنید تا مقداردهی اولیه درست انجام شود، و در ادامه کارایی بسیار بالاتری خواهید داشت.

نکات کلیدی#

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

منابع بیشتر#

تمرین‌ها#

طراحی چک‌لیست آمادگی راه‌اندازی: یک چک‌لیست کامل آمادگی راه‌اندازی برای پروژه‌ای که در دست توسعه دارید بنویسید. سپس یک نشست کاملاً تازه از ایجنت را باز کنید، تنها محتویات مخزن را به آن نشان دهید (بدون هیچ زمینهٔ کلامی)، و از آن بخواهید پروژه را اجرا کند، آزمون‌ها را بدواند، و پیشرفت کنونی را بفهمد. هر مشکلی را که با آن روبه‌رو می‌شود ثبت کنید — هر مشکل معادل بندی جاافتاده در چک‌لیست آمادگی راه‌اندازی شماست.
آزمایش مقایسه‌ای: یک پروژهٔ جدید با پیچیدگی متوسط انتخاب کنید. رویکرد الف: بگذارید ایجنت مقداردهی اولیه و نخستین پیاده‌سازی را هم‌زمان انجام دهد. رویکرد ب: یک نشست را به مقداردهی اولیهٔ اختصاصی اختصاص دهید و پیاده‌سازی را از نشست 2 آغاز کنید. پس از 4 نشست، زمان سپری‌شده از شروع تا نخستین آزمون قبولی، هزینهٔ بازسازی، و نرخ تکمیل قابلیت‌ها را مقایسه کنید.
چک‌لیست پذیرش مقداردهی اولیه: یک چک‌لیست پذیرش مقداردهی اولیه برای پروژهٔ خود طراحی کنید. از یک نشست تازهٔ ایجنت بخواهید هر بند چک‌لیست را اجرا کند و موارد قبولی و رد را ثبت نماید. موارد ناموفق همان جاهایی هستند که هارنس شما نیاز به تقویت دارد.