منشأ Ralph، حلقهٔ ساده و مرز ادعای بهره‌وری

Ralph نام یک محصول یا پروتکل رسمی نیست؛ نامی برای یک الگوی جامعه‌محور است: کار کوچک را به Agent بده، خروجی را بررسی کن، state را روی دیسک و Git ثبت کن و context تازه‌ای برای تکرار بعدی بساز. Geoffrey Huntley این الگو را با یک حلقهٔ Bash بسیار کوتاه توضیح داد. کوتاهی حلقه به‌معنی بی‌نیازی از محدودیت، تست یا قضاوت نیست.

## اهداف یادگیری

پس از درس می‌توانی منشأ و سطح شواهد Ralph را توضیح دهی؛ حلقهٔ Bash حداقلی را به pseudocode امن تبدیل کنی؛ pattern را از ادعای ROI جدا کنی؛ long context و bounded session را مقایسه کنی؛ و بدون پیش‌نیاز یا ارجاع اجباری به دورهٔ `ralph-technique` یک loop کوچک بسازی.

## جایگاه در چرخهٔ سرتاسری

فصل‌های پیشین Spec، Slice، تست، harness و permission را ساخته‌اند. Ralph در مرحلهٔ `Implement → Observe → Verify` قرار می‌گیرد: هر iteration یک کار مشخص را اجرا می‌کند و evidence آن را به state durable برمی‌گرداند. Ralph تصمیم نمی‌گیرد که feature ارزشمند است، acceptance را عوض نمی‌کند و جای review مستقل را نمی‌گیرد.

## منشأ و سطح شواهد

در نوشتهٔ Geoffrey Huntley، «Ralph Wiggum» یک روش تجربی و جامعه‌محور برای تکرار اجرای Agent با فایل‌ها و commitهای بین جلسات است. منبع اولیه برای تعریف pattern مفید است، اما گزارش میدانی است، نه آزمایش کنترل‌شده. بنابراین گزارهٔ «این loop همیشه بهره‌وری را بالا می‌برد» از آن نتیجه نمی‌شود. `Ralph` را با نام محصول، استاندارد یا ضمانت کیفیت اشتباه نکن.

مثال بد

while true; do agent --prompt "هر کاری لازم است انجام بده"; done

این حلقه task boundary، خروجی، budget، توقف، محیط و recovery ندارد. اگر Agent تست را حذف کند یا فقط متن «تمام شد» چاپ کند، loop می‌تواند شکست را تکرار و هزینه را پنهان کند.

مثال خوب

set -euo pipefail
max_iterations=8
trap 'printf "%s\n" "BLOCKED: interrupted" >&2; exit 2' INT TERM
for i in $(seq 1 "$max_iterations"); do
  test -f tasks.json || { echo "BLOCKED: tasks.json missing" >&2; exit 2; }
  if ! agent --prompt "فقط اولین task آماده را اجرا کن؛ acceptance را تغییر نده"; then
    echo "BLOCKED: agent failed" >&2; exit 2
  fi
  if ! npm test -- --runInBand; then
    echo "BLOCKED: verification failed" >&2; exit 2
  fi
  if ! git diff --check; then
    echo "BLOCKED: whitespace check failed" >&2; exit 2
  fi
  git status --short
  if grep -q '"status":"COMPLETE"' state.json; then
    echo "COMPLETE"
    exit 0
  fi
done
echo "BLOCKED: iteration budget exhausted" >&2
exit 2

این فقط طرح آموزشی و sandboxed است. `set -euo pipefail` خطاهای shell و متغیرهای نامعتبر را پنهان نمی‌کند؛ `if ! ...` نیز برای هر مرحلهٔ مهم خروجی `BLOCKED` می‌دهد. بنابراین test یا `git diff --check` ناموفق نمی‌تواند success کاذب بسازد. هنوز timeout، spend budget، command validation و verifier مستقل لازم‌اند.

## long context در برابر bounded sessions

یک context طولانی می‌تواند تصمیم‌های قبلی و فایل‌های بیشتری را نگه دارد، اما با log و tool output پر می‌شود؛ بخش‌های مهم ممکن است در میان نویز گم شوند و خطای اولیه تا انتها کشیده شود. این همان ریسک context rot و position effect است، نه اینکه طول بیشتر ذاتاً بد باشد. در bounded session، هر بار هدف، فایل‌های لازم، acceptance و وضعیت فعلی دوباره بارگذاری می‌شوند. هزینهٔ orientation و خطر از دست دادن context محلی بیشتر است، اما مرز خطا و اندازهٔ بازبینی کوچک‌تر می‌شود.

انتخاب تابع اندازهٔ story، کیفیت state و نیاز به تعامل است؛ ادعای کلی «همیشه context بلند بهتر است» معتبر نیست.

## سناریوی booking-platform

برای reschedule، loop فقط S2 را می‌گیرد: eligibility و concurrency. قرارداد دقیق آن این است: در رقابت دو درخواست مجاز برای slot واحد، دقیقاً یک `200` و یک `409 SLOT_CONFLICT`؛ در مسیر موفق دقیقاً یک mutation و یک audit؛ و در مسیر failure، هیچ mutation و هیچ audit تازه‌ای. ورودی شامل Spec v1.0، تست A-04 تا A-08، مسیرهای مجاز و database ephemeral است. reminder، refund و calendar provider بیرون scope هستند. پایان موفق یعنی همین invariantها، `git diff --check` و verifier مستقل evidence داشته باشند؛ نه اینکه تعداد خطوط تغییر کرده باشد.

## آزمایشگاه گام‌به‌گام

**ورودی:** یک repository محلی، `tasks.json` با سه task غیرحساس، تست‌های موجود و `state.json` خالی. هرگز endpoint تولیدی، token واقعی یا mount خانه را وارد نکن.

۱. فقط ساختار فایل‌ها و فرمان‌های موجود را بخوان. ۲. loop هشت‌تایی بالا را به runner آزمایشگاهی تبدیل کن و `agent` را با یک stub بی‌خطر جایگزین کن. ۳. خروجی هر iteration را در `progress.md` بنویس. ۴. پس از هر تغییر، تست هدفمند و `git diff --check` را اجرا کن.

فرمان‌های نمونه فقط روی fixture محلی اجرا می‌شوند:

test -d ./lab-workspace && printf '%s\n' "workspace حاضر است"
node ./lab-runner-stub.mjs --task S2 --max-iterations 8 --network deny
npm test -- --runInBand
git diff --check

اگر runner یا فایل stub در repository واقعی وجود ندارد، آن را اجرا نکن؛ اینجا فرمان‌ها قرارداد آزمایشگاهی‌اند و باید با ابزار محلیِ ثبت‌شده جایگزین شوند. خروجی موفق باید نام task، شمارهٔ iteration، تعداد تست‌های pass و hash commit را نشان دهد. برای S2، artifact باید شمارش دقیق `one 200 / one 409 SLOT_CONFLICT`، `one audit on success` و `zero mutation/audit on failure` را هم نشان دهد. خروجی failure باید exit code غیرصفر و علت قابل‌تشخیص داشته باشد، نه پیام عمومی «try again». پیش از هر retry، همان failure را در progress ثبت کن و بررسی کن آیا مشکل از fixture، command یا acceptance است. این تفکیک مانع می‌شود time spent در loop با ارزش محصول اشتباه گرفته شود.

**خروجی مورد انتظار:** هر دور یک task مشخص، diff کوچک، نتیجهٔ test و commit یا failure روشن دارد. **Recovery:** اگر stub crash کرد، iteration را متوقف، آخرین commit و progress را نگه‌دار، علت را `BLOCKED` ثبت کن و بدون retry خودکار نامحدود به owner برگردان.

## خطاهای رایج و نشانه‌ها

• نسبت دادن ROI به وجود یک loop، بدون baseline و معیار accepted change.
• اجرای همهٔ backlog در یک context و نبود مرز story.
• تعمیم روایت Huntley به هر repository و هر مدل.
• چاپ `done` بدون تست، diff یا commit.
• وابسته‌کردن آموزش به syntax یا course دیگری به‌جای مفهوم مستقل.

## Verification

• [ ] منشأ Ralph با برچسب روش جامعه‌محور و محدودیت شواهد آمده است.
• [ ] حلقه task، stop، test، diff و state دارد.
• [ ] هیچ ادعای causal دربارهٔ ROI بدون مطالعه و population مطرح نشده است.
• [ ] long context و bounded session با trade-off مقایسه شده‌اند.
• [ ] Lab sandboxed و بدون credential واقعی است.

## تمرین و Rubric

برای یک story دربارهٔ audit trail، تصمیم بگیر long context یا سه bounded session مناسب‌تر است و pseudocode توقف بنویس.

**Rubric:** story باید به taskهای کوچک با acceptance ثابت شکسته شود؛ دست‌کم دو دلیل برای bounded session و یک هزینهٔ آن ذکر شود؛ سقف iteration/زمان/هزینه، تست مستقل، progress و recovery مشخص باشد؛ و ROI به‌عنوان فرض قابل‌اندازه‌گیری با baseline ثبت شود، نه وعده.

## جمع‌بندی

Ralph یک الگوی سادهٔ تکرار و state durable است، نه محصول، استاندارد یا تضمین ROI. ارزش آن از مرزهای کوچک، بازخورد قابل‌بررسی و sessionهای قابل‌بازسازی می‌آید. هر loop باید محدود، sandboxed و صادق دربارهٔ سطح شواهد خود باشد.

## منابع مستقیم

• [Geoffrey Huntley — Ralph Wiggum as a software engineer](https://ghuntley.com/ralph/) — منبع اولیهٔ روش جامعه‌محور؛ شواهد میدانی و غیرعلّی.
• [Anthropic — Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) — گزارش میدانی دربارهٔ progress، handoff و reset؛ تعمیم آن به همهٔ پروژه‌ها محدود است.
• [Anthropic — Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — راهنمای vendor دربارهٔ context؛ پژوهش مستقل ROI نیست.

به زبان ساده

Ralph یک الگوی جامعه‌محور برای اجرای تکراری Agent با state durable است، نه محصول رسمی یا تضمین ROI. Loop امن باید task، test، diff، بودجه و خروجی‌های `COMPLETE`، `BLOCKED` یا `DECIDE` داشته باشد.

مثال واقعی

Geoffrey Huntley حلقهٔ Bash کوتاهی برای این الگو منتشر کرده است؛ آن نوشته منشأ pattern است، نه آزمایش کنترل‌شده‌ای که افزایش بهره‌وری همهٔ تیم‌ها را ثابت کند.