原始碼偵查 (Source Recon)
影片中的每個像素與每句話稍後都需要與程式碼核對,因此程式碼必須是正確的程式碼。在這些技能誕生的製作環境中,主要的前端 checkout 曾落後生產環境約兩個月,而當時的當前程式碼卻放在另一個沒人關注的 worktree 裡長達三天。在有人發現之前,同一個影片的三個版本都是從舊程式碼重建的。這個技能的存在就是為了讓這種事不再發生:先鎖定原始碼,證明它們是生產環境版本,然後將畫面對應到檔案。
以唯讀方式工作。 你只能讀取程式碼;永遠不要編輯、check out、fetch 或在使用者的儲存庫中建立 worktree。他們的工作樹可能包含未提交的工作,而 checkout 或 fetch 會改變他們未要求你改變的狀態。
1. 鎖定原始碼
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/fetch_sources.py" <product_dir>
它會讀取 product.yaml 中的 sources:,並根據角色 (role) 執行:
url::將分支 shallow-clone 到sources/.git-cache/<role>.git並匯出。path:(指向 Git 儲存庫):使用git archive匯出<branch>和origin/<branch>中較新的那個。當本地分支落後或分歧、origin 的 refs 超過一週未 fetch、或同一儲存庫的其他 worktree 比匯出版本更新時,它會發出警告。path:(不是 Git 儲存庫):直接複製並根據其檔案 hash 鎖定("pinned": false,因此對它的引用可能會無預警失效;建議優先使用 Git 來源)。
匯出的內容會以唯讀方式存放在 sources/<role>/,而 sources.lock 會記錄此次提交。若某個已鎖定的角色在磁碟上遺失(例如產品儲存庫的全新 clone),它會在其鎖定的提交還原,因此引用能持續指向相同的行數。請閱讀它印出的每一行 note:,並在繼續之前處理它們:每一條 note 都代表一個可能導致匯出版本非生產環境的原因。
所有下游的引用都會使用 <role>/<path>:<line>@<short sha> 格式,其中路徑相對於儲存庫根目錄(因此 sources/<role>/<path> 存在),sha 是鎖定的那個。
2. 證明它是生產環境版本
分支名稱不是證明。生產環境版本是部署管線最後一次構建的內容。在對應任何畫面之前,需依以下優先順序確定哪個提交是線上版本:
- 發行紀錄:發行標籤、部署日誌、部署儲存庫中的「last deployed sha」檔案。
- 部署管線設定:它從哪個分支構建,以及其構建參數(內建於構建中的環境變數可能改變品牌或隱藏功能)。
- 團隊確認已部署的最新分支,並與
git worktree list、分支日期和merge-base進行比對。
閱讀 references/freshness.md 以了解確切指令與陷阱(過時的遠端 refs、功能開關、改變渲染結果的構建參數)。如果你無法確認生產環境提交,請在 SOURCES.md 的開頭說明(「production commit unconfirmed」),並向用戶提出一個封閉式問題並建議答案,例如:「將 origin/develop(最新,包含主線)匯出為生產環境版本?建議:是,因為這是部署工作流程構建的內容。」
當用戶確認了不同的分支,請修改 product.yaml 中的 branch: 並執行 fetch_sources.py <product_dir> --refresh --role <role>(如果影片已引用此來源,請先執行 changed_since.py,見第 6 節)。
3. 對應每個畫面
從影片的 BRIEF.md(章節)和 COVERAGE.md 取得畫面與狀態。為每個畫面(或共享元件的少量畫面組)啟動一個唯讀的探索子代理 (Explore subagent),並平行執行。給予每個代理 references/recon-prompt.md 中的提示,並指向 sources/<role>/(鎖定的匯出版本,絕不是用戶的 checkout),以確保它回傳的每個行號都與鎖定版本相符。
每個子代理會回傳(附上引用):路由、頁面與子元件(模板、邏輯、樣式檔案)、影片語言中的 i18n 鍵與確切字串、決定渲染內容的狀態(預設值、標誌、功能門控、空狀態、權限檢查)、正在使用的圖示集與素材,以及任何看起來未發布、受門控或受限制的內容。
然後,親自對照你擁有的任何參考資料(錄影、復原的畫面截圖、文件),抽查每個畫面的兩三組字串。字串不同代表匯出版本非生產環境,或畫面被隱藏在功能開關之後;在撰寫 SOURCES.md 之前解決此問題。
4. 撰寫 SOURCES.md
每個影片一個檔案,位於 videos/<video>/SOURCES.md:
# Sources: <video>
Locked: frontend main@1a2b3c4 (2026-01-12), backend main@5d6e7f8 (2026-01-10)
Production: confirmed by <release tag v4.2.0 | deploy workflow builds main | team confirmation>
| screen | route | components | citation |
|---|---|---|---|
| Board, empty | /board | BoardPage > TaskList > EmptyState | frontend/src/pages/board/BoardPage.tsx:14@1a2b3c4 |
## Board, empty
- Strings: `board.empty.title` "Nothing planned yet" (frontend/src/i18n/en.json:88@1a2b3c4)
- State: renders when `tasks.length === 0` (frontend/src/pages/board/TaskList.tsx:41@1a2b3c4)
- Icons: lucide `calendar-plus` (frontend/src/pages/board/EmptyState.tsx:9@1a2b3c4)
- Flags or gates: none found
- Not found: <anything the brief needs that the code does not have>
## No-code references
<what exists for each screen without code, see section 5>
沒有引用的畫面不應放入影片中。將其列在「Not found」下並告知用戶;發明一個不存在的畫面是審查者最無法容忍的錯誤,因為這會展示一個不存在的產品。
5. 列出無碼參考資料
對於程式碼無法呈現的畫面(第三方 UI、執行時期輸出、不在儲存庫中的後端,或完全沒有前端程式碼),列出可用的資料,優先順序如下:references/ 中已分析的螢幕錄影、可從過去對話記錄中復原的畫面截圖、與生產環境一樣建置的本機應用程式實例、公開文件與截圖。請勿在此自行擷取畫面;那是 ui-reference-capture 的工作。永遠不要依賴審查者的個人瀏覽器。
6. 當程式碼變更時
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/source-recon/scripts/changed_since.py" <product_dir> [--offline]
它會比對每個鎖定的提交與目前分支的最新版本,並列出所有引用了變更檔案的影片(以及組件檔案)的 SOURCES.md、TRUTH.md、規格或 video/src/,並標記那些行數已變更的引用。它不會移動任何東西。在任何 --refresh 之前執行此工具:它比較的是鎖定版本與最新版本,而 refresh 會使它們相等,因此之後變更的列表就會消失(此時腳本會印出提示訊息)。向用戶顯示該列表,然後,如果他們想要新的程式碼,請執行 fetch_sources.py --refresh、為受影響的畫面重新執行 ui-spec-from-code,以及為受影響的行數重新執行 product-truth。沒有引用到變更內容的影片則保持不變。
規則與原因
- 讀取匯出版本,引用鎖定版本。 來自不同 checkout 的行號會在下次 refresh 後默默指向錯誤的程式碼。
- 永遠不要印出在程式碼中發現的機密。 前端程式碼經常包含金鑰和 token。僅回報檔案與行號,並將其視為安全問題告知用戶。
- 未發布、受門控或受限制的功能也是事實。 在 SOURCES.md 中標記它們(
gate: <flag>,restricted: <who sees it>)。product-truth 會決定影片是否可以展示它們,通常需要審查者的同意。 - 避免真實資料。 儲存庫中的測試用固定資料或種子檔案可能包含真實客戶名稱。引用它們的結構,而不是它們的值。