حافظهٔ پایدار، Provenance و تحویل زمینه

Agent بعد از دو ساعت بررسی می‌نویسد «فهمیدم؛ فقط route را تغییر بده.» session تمام می‌شود. نفر بعدی نمی‌داند timezone را چه کسی انتخاب کرده، test واقعاً روی چه commitی اجرا شده و آیا migration خارج از Scope بوده است. Context کوتاه‌مدت حافظهٔ پروژه نیست. حافظهٔ پایدار باید آن‌قدر مختصر باشد که بارگذاری شود و آن‌قدر شاهددار که تصمیم و evidence با حدس اشتباه نشود.

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

پس از این درس می‌توانی ADR، glossary، plan، progress و evidence log را بر اساس نقش تفکیک کنی، provenance برای Fact و result ثبت کنی، یک compaction-safe summary بنویسی، handoff قابل‌اجرا به Agent یا انسان بدهی، و stale state، تکرار و ادعای بی‌شاهد را قبل از ادامهٔ کار تشخیص دهی.

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

درس‌های ۸ تا ۱۰ Context یک نوبت و دستورهای آن را تنظیم کردند. این درس در مرز Observe → Verify → Learn قرار دارد: خروجی discovery، تصمیم و verification از Context محو می‌شود و در Artifactهای version-controlled می‌نشیند. فصل بعد همین state را ورودی Spec، ADR طراحی و ExecPlan می‌گیرد. حافظهٔ بیرونی authority تازه تولید نمی‌کند؛ تصمیم باز را باز نگه می‌دارد و منبع تصمیم معتبر را قابل بازیابی می‌کند.

## هر نوع state یک سؤال پاسخ می‌دهد

**Glossary** می‌پرسد: «این واژه در این پروژه دقیقاً چه معنایی دارد؟» مثلاً tenant، clinic timezone یا adjacent slot. یک تعریف مشترک است، نه timeline تصمیم. **Decision ledger** می‌پرسد: «چه policy هنوز owner/deadline دارد و پیش‌فرض امن چیست؟» رکورد کوتاه پیش از design است. **ADR** می‌پرسد: «چه تصمیم معماری پذیرفته شد، چه گزینه‌هایی رد شدند و پیامد چیست؟» ADR جای log هر مشاهده نیست.

**Plan/ExecPlan** می‌پرسد: «چه گام‌هایی، با چه dependency و verification، قرار است انجام شود؟» **Progress** می‌پرسد: «در این کار اکنون چه چیز واقعاً انجام/باقی/مسدود است؟» **Evidence log** می‌پرسد: «کدام فرمان یا مشاهده در چه محیط و revisionی چه نتیجه‌ای داده است؟» جداسازی مانع می‌شود که یک `progress.md` ۵۰۰ خطی هم قانون domain، هم design، هم log خام و هم چک‌لیست آینده باشد.

جدول نقش ساده:

## خلاصهٔ خوب چرا کوتاه است؟

خلاصه با حذف token ارزشمند است فقط اگر قابلیت ادامه را حفظ کند. برای هر خط بپرسید: نفر بعد با این خط چه عمل یا تصمیمی می‌تواند بگیرد؟ `مسیر: apps/api/...`، `SHA: abc` و `command/result` قابل‌عمل‌اند. «کد مرتب شد» نه scope دارد، نه authority. provenance یعنی همان link از Fact به منشأ: path+line یا commit برای code، URL/version برای docs، owner/date برای decision، و revision/environment برای test result.

بنابراین raw log را در progress paste نمی‌کنیم. failure digest، مسیر artifact و فرمان کافی است؛ log کامل در CI یا فایل artifact می‌ماند. البته خلاصه نباید evidence را پاک کند: اگر test نیاز به database ephemeral داشت، چنین محدودیتی باید ثبت شود تا سبزشدن دوباره قابل تکرار باشد.

یک entry خوب ممکن است این باشد:

## 2026-09-05 — reschedule reconnaissance
- Done: مسیر route → service → transaction map شد؛ شاهد: `docs/maps/appointments.md`، commit `abc123`.
- Decision valid: timezone کلینیک؛ ADR-014، owner Architecture، status Accepted.
- Blocked/DECIDE: adjacent slots؛ owner Product، deadline 2026-09-06؛ هیچ behavior جدیدی implement نشود.
- Verify: `pnpm test appointments` در Node/lockfile ثبت‌شده passed؛ integration نیازمند DB ساختگی است؛ artifact: CI run/link.
- Next: مثال پذیرش concurrency را پیش از plan تأیید کن؛ refund و historical migration خارج از Scope.

این متن نشان نمی‌دهد که route «درست» است؛ فقط scope مشاهده، منبع و محدودیت را می‌گوید. اگر commit تغییر کند یا ADR superseded شود، entry stale است و باید link/status به‌روز شود، نه اینکه نتیجهٔ قدیمی دوباره به‌عنوان Fact جاری نقل شود.

## ADR و ledger: تصمیم موقت را معماری نکنید

دفتری که در فصل ۲ ساختید برای تصمیم‌های باز و high-risk است. وقتی authority انتخاب را تأیید و اثر فنی روشن شد، ADR کوتاه می‌تواند تصمیم معماری ماندگار را ثبت کند: مثلاً مرجع timezone و اثر آن بر storage/display. «Agent ترجیح داد» دلیل ADR نیست؛ decision authority، evidence و optionهای واقعی لازم است. برعکس، هر تغییر نام فایل ADR نمی‌خواهد. معیار، هزینهٔ برگشت و تاثیر میان‌اجزایی است.

برای booking-platform، ADR-014 می‌تواند بگوید timestampها UTC ذخیره می‌شوند و clinic timezone authority نمایش/validation MVP است؛ گزینهٔ doctor timezone رد شده چون policy فعلی چنین است؛ پیامد: test DST و contract field لازم می‌شود. policy refund تا وقتی Product owner آن را نپذیرفته، ledger می‌ماند. تفکیک این دو، Context بعدی را از تصمیم جعلی محافظت می‌کند.

## Compaction-safe: مرحله به مرحله، نه مکالمه به مکالمه

وقتی Context reset می‌شود، هدف این نیست که transcript را بازنویسی کنیم. چک‌پوینت باید شامل پنج دسته باشد: **قصد و Scope**، **تصمیم معتبر و تصمیم باز**، **Facts با source و confidence**، **Evidence verification با محیط/revision** و **next action/blocker**. برای هر artifact canonical link بدهید. اگر همه چیز در summary تکرار شده است، reader نمی‌فهمد کدام نسخه مرجع است؛ اگر فقط link دارید، reader هدف کار را نمی‌فهمد. تعادل، چند خط دقیق و مسیرهای بازیابی است.

Compaction پس از هر گام پرریسک یا قبل از handoff انجام شود، نه فقط هنگامی که model window پر شد. یک تغییر design بدون ثبت دلیل، حتی در Context بزرگ، حافظهٔ ضعیف است. از تاریخ‌های نسبی مثل «دیروز» پرهیز کنید؛ date، timezone و commit را بنویسید. برای secret، PII یا raw production data، identifier حساس را هم در durable state وارد نکنید؛ redacted reference و محل امن کنترل‌شده کافی است.

مثال ضعیف: `progress.md`

# Progress
همه چیز بررسی شد. ایجنت گفت این بهترین راه است.
تست‌ها سبز شدند، احتمالاً. اکنون API را کامل کنیم.

این فایل نه Scope دارد، نه command، نه revision، نه تصمیم ownerدار، نه blocker. «بهترین» جای trade-off را پنهان می‌کند و «احتمالاً» evidence نیست. نفر بعد ممکن است refund را در Scope بداند یا test نامناسب را تکرار کند.

نمونهٔ اصلاح‌شده `progress.md`

# Reschedule — checkpoint 2026-09-05
## Scope
Conflict-safe reschedule در یک tenant؛ refund، provider sync و migration تاریخی خارج از Scope.
## Facts / provenance
- route/service/test map: `docs/maps/appointments.md` @ `abc123`; confidence: medium.
- conflict test فعلی فقط مسیر ترتیبی را پوشش می‌دهد: `.../appointments.int.test.ts`; concurrent case unknown.
## Decisions
- Accepted: clinic timezone — ADR-014.
- DECIDE: adjacent slots — Product owner, 2026-09-06, default BLOCKED.
## Evidence
- command/result/environment: CI link، SHA، database fixture version؛ بدون production data.
## Next / handoff
پس از پاسخ adjacent slots، example concurrency را بنویس؛ سپس plan. اجرای test خارجی بدون sandbox ممنوع.

این progress هنوز کوتاه است، ولی هر جمله محل ادامه را روشن می‌کند. علامت `medium` اجازه می‌دهد نوبت بعد قبل از implementation Fact را قوی‌تر کند. همان راهبرد، خطای اعتمادبه‌نفس مصنوعی را کاهش می‌دهد.

## handoff یک قرارداد ادامه است

Handoff خوب با «از اینجا ادامه بده» شروع نمی‌شود. دریافت‌کننده باید task identity، Scope، branch/revision، state، evidence، permissions، خطر و next action را بداند. اگر کاری مستقل نیست، handoff آن را موازی اعلام نمی‌کند. قالب زیر را برای agent-to-agent یا human-to-agent نگه دارید:

Task / outcome: …
Revision / environment: …
Scope + non-goals: …
Canonical artifacts: glossary, ledger, ADR, plan, progress links.
Facts + provenance + confidence: …
Decisions: accepted / DECIDE / BLOCKED, owner and deadline: …
Verification already run: command, result, limits, artifact: …
Permissions / safety: read-only, network, secrets, approvals: …
Next smallest action + expected evidence: …
Stop condition / escalation: …

Handoff به معنای انتقال authority نیست. مالک Product همچنان تصمیم policy می‌گیرد و reviewer مستقل هنوز Evidence را بازبینی می‌کند. اگر Contextی که تحویل می‌دهید شامل متن غیرقابل‌اعتماد از issue یا web است، آن را source غیرقابل‌اعتماد علامت بزنید؛ directiveهای آن، instruction معتبر نیستند.

## مثال ضعیف در booking-platform

Agent اول: reschedule تقریباً تمام شد؛ از log بالا استفاده کن و باقی‌اش را تمام کن.
Agent دوم: همه چیز درست است؛ migration و refund هم اضافه می‌کنم.

اولی identifier، revision و ownership ندارد؛ دومی Scope را گسترش داده و policy را خودسرانه حل کرده است. یک خلاصهٔ بلندتر نیز مشکل را حل نمی‌کند اگر `next action` و stop condition نداشته باشد.

مثال اصلاح‌شده

Outcome: مثال/plan برای conflict-safe reschedule، نه implementation.
Revision: abc123؛ workspace clean بررسی‌شده در زمان checkpoint.
Facts: map مسیر و test ترتیبی با لینک؛ concurrency unknown (medium).
Accepted: clinic timezone, ADR-014. DECIDE: adjacent slots, Product, deadline.
Evidence: command X در sandbox Y؛ result Z؛ integration DB بیرونی اجرا نشده.
Next: بعد از تصمیم، Given/When/Then concurrency بنویس؛ expected output: مثال و test plan.
Stop: بدون decision یا محیط امن، code/migration/refund نزن.

در این نسخه، نفر دوم می‌تواند مفید باشد بدون اینکه «تقریباً» را به مجوز تغییر تبدیل کند.

## آزمایشگاه: checkpoint و handoff بساز

**ورودی:** خروجی reconnaissance فصل ۳ برای reschedule، یک ADR پذیرفته، دو decision باز و نتیجهٔ یک test محلی. **گام‌ها:** ۱) هر قطعه را در glossary/ledger/ADR/plan/progress/evidence جای بده. ۲) progress را در حداکثر ۱۵ bullet بنویس. ۳) برای هر Fact path، commit/date و confidence ثبت کن. ۴) evidence test را با command، محیط، revision، result و limitation بنویس. ۵) handoff قالب بالا بساز و next smallest action/stop condition تعیین کن.

**فرمان‌های read-only:** این اطلاعات provenance را بدون تغییر checkout جمع می‌کنند:

git rev-parse HEAD
git log -1 --format='%H%n%cI%n%s'
git status --short

**خروجی واقع‌بینانهٔ مورد انتظار:** فرمان اول یک SHA چهل‌کاراکتری می‌دهد؛ فرمان دوم همان SHA، یک زمان ISO-8601 و عنوان آخرین commit را در سه خط چاپ می‌کند؛ فرمان سوم برای checkout پاک خروجی ندارد و در غیر این صورت فقط مسیرهای تغییرکرده را نشان می‌دهد. این خروجی، به‌تنهایی نتیجهٔ test نیست؛ آن را کنار command/result واقعی test و محیط ثبت کن.

**خروجی مورد انتظار:** فرد تازه بدون transcript می‌فهمد چه چیز معتبر، باز، تست‌شده، خارج از Scope و گام بعد است. progress شامل SHA و زمان مشاهده، و Evidence شامل command/result/محیط test است. با linkها می‌تواند evidence را دوباره باز کند؛ secret و log خام در فایل نیست.

**Recovery:** اگر `git rev-parse HEAD` شکست خورد، در Git repository نیستید یا metadata در دسترس نیست؛ directory و limitation را ثبت کن و SHA نساز. اگر `git status --short` خروجی داد، همان تغییرها را در handoff Scope کن یا پیش از ادعای نتیجهٔ clean متوقف شو. اگر progress بلند شد، raw output و روایت جلسه را به artifact/link منتقل و فقط outcome نگه دارید. اگر هیچ revision یا command ندارید، نتیجه را «تأییدشده» ننویسید؛ verification را unknown بگذارید. اگر تصمیم بدون owner است، آن را به ledger برگردانید و `DECIDE` کنید. اگر link مرده است، path/commit جدید بسازید یا Fact را stale علامت بزنید.

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

• **یک فایل همه‌کاره:** progress هم source policy و هم log هزارخطی است.
• **Evidence بدون provenance:** «سبز» است اما command و revision ندارد.
• **تصمیم باز در ADR Accepted:** authority و تاریخ تأیید ندارد.
• **حافظهٔ ابزار را منبع حقیقت می‌گیریم:** Auto memory یا chat state جای artifact مشترک می‌نشیند.
• **handoff بدون توقف:** دریافت‌کننده نمی‌داند چه زمانی escalate کند.

## چک‌لیست Verification

• [ ] هر artifact یک نقش و canonical path دارد.
• [ ] Factها source، تاریخ/revision و confidence دارند.
• [ ] ADR فقط تصمیم architecture پذیرفته با گزینه/پیامد است؛ ledger تصمیم باز را نگه می‌دارد.
• [ ] Evidence command، محیط، revision، result و limitation دارد.
• [ ] progress next action، blocked/DECIDE و non-goal را روشن می‌کند.
• [ ] handoff permission، safety و stop condition دارد و secret را افشا نمی‌کند.

## تمرین مستقل

برای تغییر «ارسال reminder قابل‌تکرار»، یک ledger دو ردیفی، ADR کوتاه یا دلیلِ نیازنداشتن به ADR، progress checkpoint و handoff بنویس.

**Rubric پاسخ:** پاسخ خوب idempotency، tenant و زمان‌بندی را با source/confidence جدا می‌کند؛ policy channel/opt-out را ownerدار و باز می‌گذارد؛ ADR را فقط برای trade-off معماری مانند deduplication store با گزینه و پیامد می‌نویسد؛ evidence را command/revision/environmentدار می‌کند؛ و handoff گام بعد/stop را تعیین می‌کند. پاسخ بدون provenance، یا واگذاری policy به Agent، مردود است.

## جمع‌بندی

حافظهٔ پایدار transcript نیست؛ شاخص کوتاهِ تصمیم، Fact، evidence و گام بعد است. با provenance، نوبت تازه می‌تواند state را دوباره verify کند؛ با handoff، تغییر بزرگ بدون توهم تداوم ادامه می‌یابد. اکنون دوره آماده است تا همین Context و state را به Spec و برنامهٔ اجرایی قابل‌بررسی تبدیل کند.

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

• [Anthropic — Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — گزارش فنی فروشنده دربارهٔ compaction و note-taking؛ نه جایگزین Artifactهای پروژه.
• [Claude Code memory](https://code.claude.com/docs/en/memory) — مستند رسمی حافظه/دستور Claude Code و محدودیت Context.
• [OpenAI Codex — AGENTS.md](https://developers.openai.com/codex/guides/agents-md) — مستند رسمی برای instruction chain؛ نه حافظهٔ پایدار مستقل از runtime.
• [AGENTS.md](https://agents.md/) — Convention باز برای راهنمای مخزن با محدودیت portability.

به زبان ساده

حافظهٔ پایدار باید به نفر بعدی بگوید چه چیزی تصمیم گرفته، چه چیزی مشاهده شده و گام بعد چیست. ADR، progress و Evidence log را جدا نگه‌داشتن، از تبدیل یک فایل به مخلوطی از policy و log جلوگیری می‌کند.

مثال واقعی

یک checkpoint قابل‌ردیابی می‌تواند SHA، فرمان تست و نتیجهٔ آن را کنار وضعیت `DECIDE` برای adjacent slot ثبت کند؛ عبارت «تقریباً تمام شد» برای ادامهٔ کار کافی نیست.