شناخت Codebase و آشکارسازی تدریجی

یک Agent برای افزودن reschedule مستقیماً فایل UI را باز می‌کند، endpoint جدید می‌سازد و بعد می‌فهمد که booking-platform قراردادهای مشترک، service مرکزی و تست E2E دارد. این خطا معمولاً «ناتوانی مدل در کدنویسی» نیست؛ شروع تغییر پیش از ساختن نقشهٔ حداقلی از مخزن است. Reconnaissance خوب همه‌چیز را نمی‌خواند؛ راه رسیدن به شاهد بعدی را پیدا می‌کند.

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

پس از این درس می‌توانی reconnaissance را از implementation جدا کنی، نقشهٔ کوتاه repository شامل manifest، entry point، قرارداد، test و Git history بسازی، ترتیب بازیابی overview→مرز→فایل را به کار ببری، Fact را با مسیر و confidence گزارش کنی، و یک retrieval plan just-in-time برای تغییر رزرو طراحی کنی.

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

پس از Elicit، تیم می‌داند چه چیز تصمیم باز است. اکنون در Observe قرار داریم: نقشهٔ مخزن facts لازم برای Specify و plan را فراهم می‌کند. خروجی این درس هنوز design یا code نیست؛ repository map و سؤال‌های باز است. اگر map نشان داد schema، route و test از سه package می‌گذرند، آن یک Fact مهندسی است؛ اینکه کاربر حق reschedule دارد همچنان Decision دفتر قبلی است.

## چرا reconnaissance یک مرحلهٔ مستقل است؟

Codebase یک graph است، نه فهرست فایل. نام folder به‌تنهایی authority نیست: `legacy/`, generated code، test fixture یا wrapper ممکن است رفتار واقعی را تعیین نکند. ورود مستقیم به file اول، مدل را به local optimum می‌رساند؛ تغییر در handler می‌دهد، ولی validator، contract یا migration را نمی‌بیند. ورود مستقیم به همهٔ فایل‌ها هم context rot می‌سازد. پاسخ، progressive disclosure است: ابتدا سطح و مرز، سپس مسیر اجرای رفتار، آنگاه جزئیات موردنیاز همان سؤال.

یک قرارداد read-only آغاز کنید:

هدف: مسیر فعلی ایجاد/تغییر appointment و مرز tenant را نقشه‌برداری کن.
مجاز: tree، manifest، entry pointها، قراردادها، testها و ۵ commit نزدیک.
ممنوع: ویرایش، نصب dependency، شبکه، secret، export داده و اجرای destructive command.
خروجی: map حداکثر یک صفحه + Fact | شاهد | confidence | سؤال باز.
توقف: هر policy یا Scope ناشناخته = DECIDE؛ هر نتیجهٔ بدون شاهد = unknown.

این قرارداد هم استقلال Agent و هم قابلیت بازبینی انسان را بالا می‌برد. اجرای command در sandbox نیز از روی نام پروژه مجاز نمی‌شود؛ قبل از test باید script manifest و اثر آن را بخوانید.

## لایه‌های نقشه

**۱. شکل و مرز مخزن.** `git rev-parse --show-toplevel`، tree سطح اول و فایل‌های workspace نشان می‌دهند monorepo هست یا نه. manifest ریشه scriptهای declared، package manager و workspaceها را می‌گوید. فقط نام `apps/api` اثبات نمی‌کند API آنجاست؛ entry point و script شاهد بهتری‌اند.

**۲. مسیر رفتار.** برای reschedule از واژه‌های domain (`appointment`, `reschedule`, `conflict`) و قرارداد (`PATCH`, `idempotency`) جست‌وجوی محدود کنید. سپس entry point، handler، service، repository/database adapter و contract را باز کنید. هم‌زمان مسیر خروجی را بپرسید: response code، audit event و UI کجا مصرف می‌شوند؟

**۳. oracle و عملیات.** testهای unit، integration و E2E می‌گویند چه رفتاری اکنون checked می‌شود، نه لزوماً محصول چه می‌خواهد. CI workflow و package script روش canonical اجرا را نشان می‌دهند. config runtime، migration و fixtureها فقط زمانی وارد Context می‌شوند که map سؤال مربوط ساخته باشد.

**۴. تغییرات نزدیک.** `git log --oneline -5 -- <path>` یا `git log -p` محدود، واژگان و تصمیم‌های تازه را نشان می‌دهد. Git history شاهد ثانویه است: commit message یا comment policy تأییدشده نیست. برای یک رفتار حساس، ADR/Spec و owner authority را نیز پیدا کنید.

## نقشهٔ فشردهٔ booking-platform

هدف: reschedule بدون double booking؛ refund و migration تاریخی خارج از Scope.
مرزها: apps/web = درخواست/نمایش؛ apps/api = orchestration رفتار؛
        packages/contracts = شکل پیام؛ packages/database = persistence/migration.
ورود محتمل: route appointment → service → repository transaction.
Verification: testهای module و E2E نزدیک؛ فرمان را فقط از package.json تأیید کن.
شواهد لازم: tenant filter، idempotency key، conflict response، audit event، timezone.
مالک تصمیم‌های باز: cancellation و adjacent slots در Decision ledger.

این map عمداً از نام دقیق فایل یا فرمان خیالی دوری می‌کند. پس از command واقعی، مسیر و نام test جایگزین «محتمل» می‌شود. واژهٔ **محتمل**، دروغ ضعف نیست؛ confidence مناسب برای مرحلهٔ اول است.

## چرخش retrieval: فرضیه، مشاهده، بارگذاری بعدی

Agent به جای آنکه ۲۰ فایل را «برای زمینه» باز کند، با پرسش کوچک کار می‌کند. فرضیه: «تغییر رزرو از service مرکزی می‌گذرد.» مشاهده: نام route و import service را می‌بیند. retrieval بعدی: فقط signature service و integration test همان route. اگر test نشان داد web مستقیماً به provider صدا می‌زند، فرضیه رد می‌شود و map اصلاح می‌گردد. همین چرخه، هزینهٔ مسیر اشتباه را زود نشان می‌دهد.

فایل بزرگ را نیز chunk معنادار بخوانید: ابتدا exportها، function نام‌دار و test نامربوط را پیدا کنید؛ سپس block مربوط را باز کنید. خروجی search را مانند سند canonical درمان نکنید. Match در generated fixture یا comment، سرنخ است و باید با محل اجرا/تست تأیید شود.

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

برای reschedule، از apps/web شروع کن و هر فایلی که نام appointment دارد بخوان.
وقتی فهمیدی، endpoint و migration لازم را بساز.

دستور، contract مشترک، transaction و test را پیش‌فرض گرفته است؛ migration را بدون Fact یا Decision وارد Scope می‌کند. همچنین «وقتی فهمیدی» معیار توقف ندارد. Agent ممکن است ۳۰۰ نتیجهٔ جست‌وجو را بخواند و یک route مشابه legacy را مبنا قرار دهد.

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

مرحلهٔ A (read-only): manifest/workspace، entry point و test command را نقشه کن.
مرحلهٔ B: برای یک request موجود، مسیر route→service→contract→persistence را فقط با شاهد باز کن.
مرحلهٔ C: ۵ commit نزدیکِ همان مسیر را برای تغییرهای active بررسی کن.
پس از هر مرحله: Factها، confidence، path و سؤال باز را در map به‌روز کن.
قبل از برنامه: tenant، idempotency و timezone را با test/contract چک کن.
اگر policy لغو یا adjacent slots لازم شد: ledger را ارجاع بده و DECIDE کن.

این نسخه ترتیب مشاهده را می‌گوید، نه معماری مطلوب را. در نتیجه اگر رفتار واقعی متفاوت باشد، Agent می‌تواند یافته را گزارش کند بدون آنکه implementation اشتباه را ادامه دهد.

## انتخاب ابزار و اندازهٔ خروجی

`rg` یا search نام domain برای راه‌یابی مناسب است؛ `git log -- <path>` برای تازگی محدود؛ خواندن manifest برای فرمان؛ و اجرای test فقط وقتی script و هزینه‌اش شناخته شده است. برای هر فرمان در report بنویسید: چرا اجرا شد، چه Scopeی داشت، چه خروجی کوتاهی evidence شد و چه چیزی هنوز unknown است. خروجی هزارخطی test یا lockfile را در Context نچسبانید. failure signature، نام test، command و مسیر artifact معمولاً برای نوبت بعدی کافی است.

اگر repository بزرگ است، map را به «شاخص» تبدیل کنید، نه دانشنامه: `domain → ownership/path → canonical command → evidence`. این حافظهٔ بیرونی در درس ۱۱ پایدار می‌شود. برای هر تغییر جدید، فقط شاخهٔ map مربوط را تازه کنید؛ بازنویسی کل map ممکن است تاریخ و confidence را نابود کند.

## آزمایشگاه: یک repository map بساز

**ورودی:** checkout امن booking-platform و brief «reschedule بدون double booking». **گام‌ها:** ۱) root، workspace و manifest را بخوان. ۲) نام entry point و یک command candidate برای test را با مسیر ثبت کن. ۳) یک flow موجود appointment را route تا persistence trace کن، اما فقط فایل‌های لازم را باز کن. ۴) test نزدیک و حداکثر پنج commit همان مسیر را بررسی کن. ۵) map بالا را با Fact/شاهد/confidence/سؤال باز کامل کن.

**فرمان‌های نمونه:** `git status --short`، `rg -n "appointment|reschedule" apps packages` و `git log --oneline -5 -- apps/api/src/modules/appointments`. اگر manifest فرمان دیگری دارد، همان فرمان declared را بخوان و اثرش را قبل از اجرا ارزیابی کن.

**خروجی مورد انتظار:** یک map کوتاه که owner فنیِ مسیرها، test یا command واقعی، مرز contract و حداقل یک unknown مانند policy adjacent slot را دارد. هیچ فایل تغییر نکرده و evidence هر Fact مسیرمند است.

**Recovery:** اگر search بسیار گسترده بود، query را به module و extension محدود کنید. اگر چند entry point یافتید، از route/test موجود سؤال trace بسازید، نه انتخاب سلیقه‌ای. اگر command test dependency یا سرویس خارجی می‌خواهد، اجرا نکنید؛ dependency را گزارش، محیط امن را مشخص و وضعیت را BLOCKED یا محدود به static evidence کنید.

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

• **map از اسم folder ساخته شده:** مسیر اجرا یا script شاهد ندارد.
• **تست به policy تبدیل شده:** assertion فعلی جای Decision product نشسته است.
• **تاریخچه همه‌چیز است:** `git log --all` هزار commit می‌آورد ولی branch و path روشن نیست.
• **تغییر حین reconnaissance:** Agent برای «اثبات» map یک refactor می‌کند.
• **confidence حذف می‌شود:** نتیجهٔ جست‌وجو قطعی گزارش می‌شود، با اینکه generated code بوده است.

## چک‌لیست Verification

• [ ] root، manifest، entry point، contract/persistence، test و history نزدیک بررسی شده‌اند.
• [ ] هر Fact مسیر یا فرمان شاهد و confidence دارد.
• [ ] فقط فایل‌های لازم برای پرسش جاری retrieve شده‌اند.
• [ ] script یا test پیش از اجرا از manifest/محیط بررسی شده است.
• [ ] Fact فنی و Decision ledger مخلوط نشده‌اند.
• [ ] reconnaissance read-only مانده یا افزایش دسترسی دلیل و Scope دارد.

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

برای قابلیت «لغو رزرو تا ۲۴ ساعت قبل»، map و retrieval plan سه‌مرحله‌ای بنویس. حداقل دو unknown را به دفتر تصمیم ارجاع بده.

**Rubric پاسخ:** پاسخ خوب مسیر لغو از UI/API تا time source و persistence را با شاهد پیشنهادی نشان می‌دهد؛ test و command را از manifest کشف می‌کند؛ tenant، timezone و audit را نادیده نمی‌گیرد؛ history را به path محدود می‌کند؛ و policy refund/deadline را Fact نمی‌نامد. طرحی که با «کل repo را بخوان» آغاز شود یا در مرحلهٔ discovery code می‌زند، امتیاز کامل نمی‌گیرد.

## جمع‌بندی

شناخت مخزن یعنی ساختن یک graph کوچک و قابل‌ردیابی، نه حفظ‌کردن تمام فایل‌ها. مسیر discover→observe→retrieve بعدی، Context را تازه نگه می‌دارد و before-plan معلوم می‌کند کدام Fact کافی و کدام Decision هنوز باز است. در درس بعد، همین map با دستورهای runtimeهای مختلف هماهنگ می‌شود.

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

• [Anthropic — Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — گزارش فنی فروشنده دربارهٔ بازیابی just-in-time و progressive disclosure.
• [Claude Code best practices](https://www.anthropic.com/engineering/claude-code-best-practices) — توصیهٔ رسمی فروشنده برای کار مرحله‌ای با codebase.
• [Anthropic — Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) — محدودیت‌ها و trade-offهای جست‌وجوی Agentic.

به زبان ساده

Reconnaissance یعنی ساختن نقشهٔ کوچک از manifest، مسیر اجرا، قرارداد، تست و تاریخچه، نه خواندن کورکورانهٔ کل repository. هر Fact باید با مسیر یا فرمان و سطح اطمینان گزارش شود.

مثال واقعی

در سناریوی فرضی دوره، مسیر `route → service → repository` برای reschedule با جست‌وجوی محدود و تست نزدیک trace می‌شود؛ نام پوشهٔ `apps/api` به‌تنهایی چنین مسیری را ثابت نمی‌کند.