خواندن سریع یک مخزن کد ناآشنا

سریع خواندن یعنی زودتر به ادعای محدود و قابل دفاع برسید، نه زودتر حدس بزنید

یک checkout از سرویسی به شما داده شده که تا امروز ندیده‌اید. درخواست کوچک به نظر می‌رسد: «مسیر اعمال coupon را پیدا کنید و بگویید برای تغییر بعدی کدام بخش‌ها باید بررسی شوند.» پوشه‌ای به نام src/api خیلی واضح به نظر می‌رسد. چند نتیجه‌ی جست‌وجو هم همان‌جا پیدا می‌شود. اما registration واقعی runtime و محل کشف testها جای دیگری است.

اگر در همین لحظه بگویید «معماری را فهمیدم» یا «این همان implementation فعال است»، از شواهد جلو زده‌اید. هدف این درس familiarity ذهنی با repository نیست. هدف، ساختن یک Repository Reconnaissance Record v1 است که نشان دهد:

• مرز مؤثر repository/workspace را چگونه تشخیص دادید؛
• سؤال‌ها را به anchorهای قابل بررسی تبدیل کردید؛
• بین مشاهده، استنباط محدود و مجهول فرق گذاشتید؛
• cueهای گمراه‌کننده را ثبت و رد کردید؛
• و در نقطه‌ای مشخص STOP / CONTINUE ONE STEP / DEFER را انتخاب کردید.

این record باید به reviewer اجازه دهد مسیر فکر شما را بدون اعتماد به حافظه، شهود یا خروجی AI بازسازی کند.

زمان فعال تقریبی: ۶۵ دقیقه.

این درس برای شماست اگر: با repository ناآشنا روبه‌رو می‌شوید و قبل از edit/debug می‌خواهید یک نقشه‌ی محدود از boundary، manifestها، wiring/runtime anchors، test-discovery و feature trace بسازید.

این درس برای این کارها نیست: پیدا کردن Root Cause، اثبات درست‌بودن implementation، اثبات تمام runtime pathها، یا طراحی کامل Test Strategy. این‌ها به مراحل بعدی نیاز دارند.

پیش‌نیاز سخت: باید بتوانید request، context، evidence و خروجی تأییدنشده‌ی AI را از هم جدا نگه دارید.

پروب کوتاه پیش‌نیاز

فرض کنید AI می‌گوید: «فایل src/api/coupon.py را پیدا کردم، پس این entry point است.» در سه خط بنویسید:

1. چه چیزی واقعاً مشاهده شده است؟
2. چه چیزی هنوز فقط inference است؟
3. چه evidence دیگری لازم است تا بتوانید ادعای قوی‌تری بسازید؟

PASS: بین evidence موجود و conclusion ادعاشده مرز روشن بگذارید و final judgment را به خروجی AI نسپارید.

اگر این تفکیک برایتان شکننده است، فقط همین dependency را repair کنید: هر خروجی ابزار یا AI را «candidate evidence» بدانید تا زمانی که locator، claim boundary و تصمیم انسانی روشن شود. آموخته‌ی درس قبل را دوباره از ابتدا نمی‌سازیم.

مسیر یادگیری را بر اساس نیازتان انتخاب کنید

سه مسیر توضیح متفاوت دارند، اما artifact و evidence bar یکسان است.

پروب مسیر

برای هر مورد یک پاسخ کوتاه بدهید:

1. چرا نام یک پوشه فقط cue است، نه proof؟
2. یک search hit چه زمانی برای نقشه‌ی repository ارزشمند می‌شود؟
3. فرق OBSERVED با INFERRED چیست؟
4. test file با test-discovery anchor چه فرقی دارد؟
5. چه زمانی باید reconnaissance را متوقف یا defer کرد؟

۵/۵ → Fast Path؛ ۳–۴/۵ → repair هدفمند؛ ۰–۲/۵ → مسیر پایه.

• مسیر پایه: واژگان، یک trace حل‌شده و قالب نیمه‌ساخت‌یافته‌ی record.
• مسیر repair: فقط misconception ضعیف با یک counterexample اضافی.
• مسیر باتجربه/Fast Path: توضیح کوتاه‌تر، اما همان LAB، همان transfer و همان معیار review.

سطح راهنمایی می‌تواند کم شود؛ معیار evidence کم نمی‌شود.

مدل ذهنی: از سؤال به anchor، از anchor به ادعای محدود

Reconnaissance را به‌صورت «گردش بین فایل‌ها» نبینید. آن را یک زنجیره‌ی تصمیم ببینید:

Question → Anchor → Evidence type → Bounded claim → Next discriminating question → Stop/Defer

سه لایه را همیشه جدا نگه دارید:

1. Repository shape — چه فایل‌ها، پوشه‌ها، manifestها و configهایی وجود دارند؟
2. Runtime reachability evidence — چه registration، import، entry یا wiringای نشان می‌دهد یک مسیر احتمالاً به runtime وصل است؟
3. Causal behavior — در اجرا واقعاً چه اتفاقی می‌افتد و علت یک defect چیست؟

این درس لایه‌ی اول را با anchorهای لایه‌ی دوم پیوند می‌دهد، اما لایه‌ی سوم را اثبات نمی‌کند.

یک record خوب از «اطلاعات زیاد» ساخته نمی‌شود؛ از سؤال‌های discriminating ساخته می‌شود. سؤال خوب نتیجه‌ی بعدی را تغییر می‌دهد. اگر پاسخ یک search هیچ candidate را حذف یا تقویت نمی‌کند، ممکن است صرفاً noise باشد.

برای confidence از عددهای ساختگی استفاده نکنید. وضعیت را فقط به‌صورت OBSERVED / INFERRED / UNKNOWN ثبت کنید. این labelها ادعای آماری نیستند؛ مرز استدلال را visible می‌کنند.

مفاهیم پایه‌ای که جلوی داستان‌سازی زودهنگام را می‌گیرند

۱. Repository / Workspace Boundary

مرزی که تعیین می‌کند «این نقشه درباره‌ی کدام checkout/workspace است». root Git، manifestهای سطح بالا، workspace config و tracked-file inventory می‌توانند anchor باشند. قبل از تفسیر پوشه‌های داخلی، boundary را ثبت کنید.

۲. Anchor

یک locator قابل بررسی که به سؤال شما ربط مستقیم دارد: manifest، runtime registration، entry point، test-discovery configuration، import/wiring یا testی که feature را از مسیر فعال فراخوانی می‌کند. anchor به‌تنهایی همیشه proof کامل نیست؛ باید بگویید چه claimی را پشتیبانی می‌کند.

۳. Search Trace

فهرست hitها نیست. یک توالی زمانی است:

سؤال → query/action → نتیجه → چرا discriminating بود/نبود → سؤال بعدی

اگر search به ۳۰ نتیجه برسد اما ندانید کدام نتیجه claim را تغییر می‌دهد، trace ندارید؛ فقط inventory دارید.

۴. مشاهده، استنباط محدود، مجهول

• OBSERVED: مستقیماً در فایل/config/خروجی قابل locator دیده شده است.
• INFERRED: از چند مشاهده نتیجه‌ای محدود ساخته‌اید، اما هنوز proof مستقیم ندارید.
• UNKNOWN: evidence فعلی برای ادعا کافی نیست یا هنوز بررسی نشده است.

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

۵. Stop / Defer Boundary

Reconnaissance باید پایان داشته باشد. وقتی سؤال bounded شما به اندازه‌ی لازم evidence دارد، record را ببندید. اگر یک claim مهم بدون runtime/dynamic evidence قابل حل نیست، آن را UNKNOWN نگه دارید و به debugging/test strategy یا reviewer مناسب defer کنید.

۶. دو ابزار Git در این درس

git ls-files می‌تواند برای inventory محدود فایل‌های tracked/index/worktree طبق optionهای انتخاب‌شده استفاده شود. این command درباره‌ی architecture حکم صادر نمی‌کند.

git grep می‌تواند pattern را در محتوای tracked/worktree جست‌وجو کند و anchor candidate بسازد. یک text hit به‌تنهایی ثابت نمی‌کند آن code در runtime اجرا می‌شود.

ابزار عوض می‌شود؛ evidence contract عوض نمی‌شود.

تمرین کوتاه: مشاهده را از اجرای فعال جدا کنید

سناریو: src/api/coupon.py در inventory فایل‌های tracked دیده شده و یک text search هم به آن hit می‌دهد. آیا می‌توانید نتیجه بگیرید که این فایل runtime entry فعال است؟

پاسخ باید دو بخش داشته باشد:

1. claim را با یکی از OBSERVED / INFERRED / UNKNOWN محدود کنید؛
2. evidence گمشده‌ای را نام ببرید که برای claim قوی‌تر لازم است.

روش شش‌گامی برای Repository Reconnaissance Record v1

گام ۱ — سؤال تغییر را bounded کنید

به‌جای «این repository چطور کار می‌کند؟» بپرسید: «برای feature X، کدام anchorها wiring، implementation candidate و test-discovery را نشان می‌دهند؟» سؤال باید آن‌قدر محدود باشد که بتوانید stop condition تعریف کنید.

گام ۲ — boundary و manifestها را پیدا کنید

اول root/workspace را مشخص کنید. سپس manifest/configهای سطح بالا را بخوانید تا package/workspace boundaries، entry conventions یا test configuration candidateها پیدا شوند. نام پوشه‌ها را هنوز architecture فرض نکنید.

گام ۳ — runtime/wiring anchor را جست‌وجو کنید

از issue language، feature key، command name، route name یا identifierی که در brief دارید شروع کنید. search trace را ثبت کنید. اگر چند implementation هم‌نام وجود دارد، دنبال registration/import/wiringای بگردید که آن‌ها را از هم discriminates کند.

گام ۴ — test-discovery را جداگانه ثابت کنید

وجود یک پوشه‌ی tests/ کافی نیست. config یا runner entryای را پیدا کنید که نشان دهد چه testهایی واقعاً discover می‌شوند. سپس test مرتبط را به feature trace متصل کنید. این هنوز correctness را ثابت نمی‌کند؛ فقط test anchor را مستند می‌کند.

گام ۵ — claimها را label و cueهای ردشده را ثبت کنید

برای هر conclusion سه چیز لازم است:

• evidence locator؛
• status: OBSERVED / INFERRED / UNKNOWN؛
• claim boundary: «این evidence چه چیزی را ثابت نمی‌کند؟»

cue گمراه‌کننده را حذف نکنید؛ در rejected_cues ثبت کنید. reviewer باید بفهمد چرا مسیر واضح کنار گذاشته شد.

گام ۶ — Stop / Continue / Defer را انسانی انتخاب کنید

در پایان یکی از این حالت‌ها را ثبت کنید:

• STOP_WITH_BOUNDED_MAP — سؤال محدود پاسخ reviewable دارد.
• CONTINUE_ONE_DISCRIMINATING_STEP — فقط یک evidence gap مشخص مانده است.
• DEFER_ESCALATE — ادعای موردنظر به debugging، dynamic execution، Test Strategy یا authority دیگری نیاز دارد.

AI و documentation فقط پس از بسته‌شدن یک retrieval/first-diagnosis probe مستقل می‌توانند برای exploration کمک کنند. استفاده باید disclosed باشد؛ locatorها و evidence را مستقل validate کنید و final evidence-sufficiency decision را انسانی نگه دارید.

مثال حل‌شده: feature مربوط به coupon در یک service ناشناخته

فرض کنید brief می‌گوید: «قبل از تغییر رفتار coupon، محل wiring فعال و test entry مربوط را پیدا کنید.» در یک repository نمونه، این مسیرها دیده می‌شوند:

• config/service.yaml
• bootstrap/plugins.py
• domain/promotions/coupons.py
• quality/scenarios/test_coupon_flow.py
• src/api/coupon_handler.py

آخرین مسیر وسوسه‌انگیز است، اما هنوز فقط اسم خوبی دارد.

Trace 1 — boundary و inventory

سؤال: «root و فایل‌های tracked این checkout کدام‌اند؟»

Action: inventory محدود با git ls-files و مشاهده‌ی configهای سطح بالا.

Result: config/service.yaml و مسیرهای متعدد coupon دیده می‌شوند.

Claim: وجود این فایل‌ها OBSERVED است. اینکه src/api/coupon_handler.py entry فعال باشد هنوز UNKNOWN است.

Trace 2 — feature anchor

سؤال: «کدام locator feature key را به wiring وصل می‌کند؟»

Action: جست‌وجوی bounded برای identifier مربوط به coupon.

Result: bootstrap/plugins.py implementation داخل domain/promotions/coupons.py را register می‌کند. src/api/coupon_handler.py در registration دیده نمی‌شود.

Claim: registration یک anchor قوی‌تر برای runtime reachability است. هنوز نگفته‌ایم تمام runtime pathها را اثبات کرده‌ایم.

Trace 3 — test discovery

سؤال: «test مرتبط چگونه discover می‌شود؟»

Action: config مربوط به runner را پیدا کنید و سپس test candidate را با همان config بسنجید.

Result: config، quality/scenarios/ را test root معرفی می‌کند و test_coupon_flow.py feature key را از مسیر registration فراخوانی می‌کند.

Claim: test anchor و wiring trace قابل review هستند. این evidence اثبات نمی‌کند feature در production بدون defect است.

Cue ردشده

src/api/coupon_handler.py به‌خاطر نام پوشه و کلاس plausible بود. چون registration/import anchor آن را پشتیبانی نکرد، به‌عنوان REJECTED_CUE ثبت می‌شود، نه اینکه از record ناپدید شود.

Stop

برای سؤال اولیه، boundary، wiring anchor و test-discovery بسته شده‌اند. Root Cause یا correctness خارج از scope است؛ پس STOP_WITH_BOUNDED_MAP موجه است.

تمرین کوتاه: یک shortcut plausible را به چالش بکشید

یک architecture note می‌گوید coupon handler زیر src/api/ است و همان path نیز در repository وجود دارد. shortcut این است که همان را implementation فعال اعلام کنید.

سه خط تحویل دهید:

1. چرا این shortcut از claim boundary عبور می‌کند؛
2. کدام evidence فعلی فقط cue است؛
3. یک next step واقعاً discriminating مثل registration/import/wiring lookup که می‌تواند candidateها را جدا کند.

شکست‌های رایج و repair محدود هرکدام

شکست ۱ — «واضح‌ترین پوشه همان runtime entry است»

نشانه: نتیجه از نام api, core, main, service ساخته می‌شود قبل از اینکه wiring دیده شود. Repair: یک registration/import/manifest anchor مستقل پیدا کنید؛ تا آن زمان claim را INFERRED یا UNKNOWN نگه دارید.

شکست ۲ — «hit بیشتر یعنی confidence بیشتر»

نشانه: search trace تبدیل به شمارش نتیجه‌ها می‌شود. Repair: برای هر query بنویسید کدام candidate را حذف/تقویت کرد. hit غیر-discriminating را کنار بگذارید.

شکست ۳ — «وجود test file یعنی test پوشش داده می‌شود»

نشانه: فقط نام فایل test ثبت می‌شود. Repair: test-discovery config یا runner entry را پیدا کنید و locator آن را کنار test نگه دارید.

شکست ۴ — «Repository map رفتار را ثابت می‌کند»

نشانه: از static structure به correctness، Root Cause یا production safety می‌پرید. Repair: claim را به structural/runtime-reachability evidence محدود کنید و سؤال causal را defer کنید.

شکست ۵ — «تا وقتی احساس آشنایی کنم می‌گردم»

نشانه: stop condition ندارید و هر search سؤال تازه‌ای تولید می‌کند. Repair: bounded question و evidence bar را به ابتدای record برگردانید. فقط یک discriminating gap باز را ادامه دهید؛ بقیه را unknown/defer کنید.

شکست ۶ — AI به‌عنوان authority نهایی

نشانه: summary ابزار بدون locator وارد record می‌شود. Repair: AI output را به hypothesis/search option تبدیل کنید، source/evidence را مستقل بررسی کنید و final decision را خودتان ثبت کنید.

پل مسیر باتجربه: ابزارهای سریع‌تر، evidence bar ثابت

ممکن است سال‌ها با IDE symbol search، rg, language server، dependency graph یا code navigation کار کرده باشید. لازم نیست این عادت‌ها را کنار بگذارید. آن‌ها را به record قابل audit تبدیل کنید.

برای هر حرکت سریع فقط این چهار سؤال را جواب دهید:

1. سؤال من چه بود؟
2. این ابزار چه anchorی داد؟
3. anchor چه claim محدودی را پشتیبانی می‌کند؟
4. چه alternative یا unknownی هنوز باقی است؟

اگر IDE مستقیم شما را به definition ببرد، locator را ثبت کنید؛ سپس wiring/test-discovery را مستقل بررسی کنید. AI/documentation support فقط پس از بسته‌شدن یک retrieval/first-diagnosis probe مستقل مجاز است؛ بعد از آن نیز summary را evidence ندانید تا anchorهایش را بازبینی کنید.

Fast Path یعنی توضیح کمتر، نه evidence کمتر. در transfer باید بدون template pathها، همان invariant questionها را بازسازی کنید.

گزینه‌ها و بده‌بستان‌ها

قاعده‌ی انتخاب: کم‌هزینه‌ترین evidenceای را بگیرید که candidateهای مهم را discriminates کند. اگر سؤال شما به Root Cause تبدیل شد، دیگر با search بیشتر آن را masquerade نکنید؛ stage مناسب را انتخاب کنید.

تمرین هدایت‌شده و اجرای مستقل

تمرین هدایت‌شده

برای مثال coupon حل‌شده، سه row اول Repository Reconnaissance Record v1 را خودتان بازسازی کنید:

• bounded question؛
• boundary/manifest anchor؛
• اولین feature-search query؛
• status هر claim؛
• یک rejected cue؛
• stop condition.

سپس متن بالا را ببندید و بررسی کنید آیا record شما هنوز برای reviewer قابل دنبال‌کردن است.

LAB — repository واقعیِ مصنوعی و گمراه‌کننده

LAB همراه درس یک checkout محلی دارد. brief، فایل‌ها و ابزارهای local در اختیار شماست؛ canonical anchor map در دسترس learner نیست.

وظیفه:

1. boundary و حداقل یک manifest anchor را پیدا کنید؛
2. runtime registration و test-discovery anchor را مشخص کنید؛
3. feature خواسته‌شده را تا implementation wired و test مرتبط trace کنید؛
4. حداقل یک cue plausible ولی گمراه‌کننده را رد یا uncertain ثبت کنید؛
5. Repository Reconnaissance Record v1 را کامل کنید؛
6. بدون ادعای Root Cause/correctness، یک stop/defer decision انسانی بدهید.

اجرای مستقل

اگر Fast Path هستید، مستقیم LAB را بدون rowهای prefilled انجام دهید. اگر مسیر پایه هستید، از قالب blank استفاده کنید ولی قبل از transfer promptهای کمکی را حذف کنید.

قانون استقلال: AI/documentation support فقط بعد از بسته‌شدن یک retrieval/first-diagnosis probe مستقل مجاز است. استفاده را disclose کنید؛ evidence locator، claim boundary و final decision باید مستقلاً قابل دفاع باشد.

تمرین کوتاه: record خود را مستقل بازبینی کنید

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

• evidence locator و status برای claimهای مرکزی؛
• stop/defer decision انسانی با rationale؛
• limitation/non-claim صریح، بدون ارتقای unsupported inference به fact.

چه چیزی یک Repository Reconnaissance Record را قابل قبول می‌کند؟

Reviewer باید بتواند پنج dimension را بررسی کند:

1. Boundary correctness — معلوم است record درباره‌ی کدام repository/workspace است.
2. Traceability of anchors — conclusionهای blocking به locator و search trace وصل‌اند.
3. Fact/inference/unknown separation — inference بدون برچسب به fact تبدیل نشده است.
4. Resistance to misleading cues — حداقل یک cue plausible بررسی و disposition آن ثبت شده است.
5. Transfer — در layout جدید، evidence تازه ساخته شده و pathهای مثال کپی نشده‌اند.

حداقل بسته‌ی evidence:

• Repository Reconnaissance Record v1؛
• LAB evidence/trace؛
• یک limitation یا non-claim صریح؛
• disclosure استفاده از AI/tool support؛
• تصمیم انسانی ACCEPT / MODIFY / REJECT برای کیفیت record، یا DEFER برای claimی که خارج از evidence bar است.

ACCEPT یعنی record برای سؤال bounded قابل دفاع است؛ به معنی درست‌بودن کل architecture یا behavior نیست. هیچ میانگین نمره‌ای نمی‌تواند شکست یک dimension critical را پنهان کند.

ارزیابی و انتقال

ارزیابی پنج نوع evidence را می‌سنجد:

• S1 — Retrieval: فرق boundary/anchor و fact/inference/unknown را در سناریوی کوتاه تشخیص دهید.
• S2 — Application: بخش مرکزی record را از LAB بسازید و locatorها را به claimها وصل کنید.
• S3 — Diagnosis: اولین جایی را پیدا کنید که یک مسیر plausible evidence را بیش از حد قوی کرده است.
• S4 — Decision: برای conclusion ناقص یا متعارض، ACCEPT / MODIFY / REJECT / BOUNDED_DEFER را با rationale انتخاب کنید.
• S5 — Transfer: در repository دومِ همراه درس در assessment/transfer/FND004-S5_SECOND_REPO/ از CHANGE_BRIEF.md شروع کنید، inventory و search trace خودتان را بسازید و با نام‌گذاری/layout متفاوت evidence تازه تولید کنید؛ anchor map آماده‌ای در اختیار شما نیست.

S2 تا S5 blocking هستند. اگر فقط pathهای مثال یا LAB را کپی کنید، transfer بسته نشده است. پاسخ مرجع یا AI نمی‌تواند جای evidence جدید شما را بگیرد.

منابع فنی و مرز تازگی

دو claim ابزاری این درس به manual رسمی Git متصل‌اند:

• git ls-files — منبع: Git manual؛ استفاده در این درس فقط برای inventory فایل‌های tracked/index/worktree طبق optionهای command است. این منبع authority معماری repository نیست.
• git grep — منبع: Git manual؛ استفاده در این درس فقط برای pattern search و ساختن anchor candidate است. text match proof اجرای runtime نیست.

این دو منبع در 2026-09-02 بررسی شده‌اند. این درس فقط به معنای مستند همین دو command برای inventory و pattern search تکیه می‌کند؛ هیچ‌کدام به‌عنوان authority معماری یا proof اجرای runtime استفاده نمی‌شوند.

آنچه deliberately claim نمی‌کنیم:

• tracked بودن یک فایل یعنی اجراشدن آن؛
• text match یعنی dependency runtime؛
• اولین entry point plausible همان entry واقعی است؛
• repository reconnaissance معادل debugging است.

Conventionهای repository بین زبان‌ها و build systemها متفاوت‌اند؛ این درس invariant questionها را آموزش می‌دهد، نه layout جهانی واحد.