盲點審計
目的
找出使用者對專案的地圖與專案實際領土之間的差距。將未知的未知轉化為具體的已知的未知,讓使用者可以檢查、回答、測試或策略性地推遲。
專案的背景是自我選擇的:所有者只能寫下他們已知的內容,因此每個 README、TODO 和計劃都編碼了他們腦中的地圖——而基於這些檔案工作的 AI 會繼承相同的盲點。此審計刻意引入專案「外部」的參考框架來測量該差距。
這項技能不是一般的品質檢查清單。它應該識別出對於這個特定專案、在當前特定階段、根據儲存庫或提供的工件證據,什麼是異常重要的。當所有者至少說出一次「我甚至不知道我應該考慮這個」,並且事後感到更平靜(因為他們現在也知道可以安全忽略什麼)時,審計就算成功。
核心模型
使用四種未知框架對發現進行分類:
- 已知的已知 (Known knowns):提示、文件、程式碼或計劃中已經陳述的內容。
- 已知的未知 (Known unknowns):文件、TODO、計劃、註解或用戶措辭中已可見的開放問題。
- 未知的已知 (Unknown knowns):如果展示給使用者,使用者會辨識出來,但尚未口語化或寫下的事物。
- 未知的未知 (Unknown unknowns):專案形狀所暗示的遺漏概念、隱藏限制或未提出的問題。
此框架之所以重要,是因為解決方案不同:未知的已知需要一個檢查清單項目,而不是一場講座;未知的未知需要一個簡短解釋和最便宜的初步步驟。好的輸出不會聲稱確定性。它會提出候選項目,並給出最便宜的下一步檢查。
基本規則
制定這些規則的原因在於,此技能的失敗模式不是「遺漏差距」,而是變成一個被忽略的通用檢查清單。
- 專案自己的追蹤文件是過濾器,不是發現的來源。 任何已經在 README / TODO / 路線圖 / 檢查清單 / 問題列表中的項目都是「已知的未知」。永遠不要將其報告為發現。(實戰數據:此過濾器通常會將候選清單減少一半以上,並且是所有者信任報告的主要原因。)
- 頂級發現限制在 3-7 個,按影響力 x 所有者真正不知情的可能性排序。其餘的放入簡短的「低信號觀察清單」或總帳中——永遠不要放入主列表。
- 僅有缺失不是一個發現。 「你沒有 X」只有在你能說明這對「此」專案的具體後果,以及最便宜的初步解決步驟時才算數。
- 始終包含兩個信任章節:「已檢查且涵蓋良好」和「目前可跳過」(每個跳過項目都附帶明確的重新檢查觸發條件)。它們可以防止焦慮和重複掃描,並且是所有者學習信任報告的方式。
- 對受監管領域保持謹慎。 對於法律、稅務或法規方面的發現,說明你發現了什麼及其來源,然後明確指出需要專業人士確認。你是偵察兵,不是律師或會計師。
模式
快速:讀取文件和專案庫存,回傳頂級盲點。深入:在對發現進行排序之前,檢查代表性的程式碼路徑、測試、配置和文件。訪談:當答案會改變架構、工作流程、範圍或風險時,一次問一個問題。實施後:比較已完成變更、筆記、差異和測試,以找出剩餘的未知。規劃:在實施之前,找出可能改變資料模型、介面、使用者體驗流程、操作或驗證的決策。
從使用者的措辭推斷模式。如果使用者要求立即執行,除非審計邊界無法推斷,否則不要詢問模式問題。
快速開始
- 識別專案根目錄和審計邊界。
- 當檔案系統專案可用時,執行庫存輔助程式。該腳本位於此技能的資料夾中——請相對於此 SKILL.md 解析其路徑:
python <this-skill-folder>/scripts/project_inventory.py <project-root> --format md
僅在執行時期輸出、生成的報告、日誌或快取工件是審計問題的一部分時,才使用 --include-generated。
- 僅讀取相關參考資料:
references/archetypes.md:選擇專案類型和預期盲點。references/lenses.md:推導並應用審計鏡頭。references/host-surfaces.md:調整問題和輸出以適應 Claude Code、Codex、OpenCode、CLI 或純文字聊天。references/ledger-lifecycle.md:發現、建立、路由或更新持久的盲點總帳。references/report-template.md:格式化結果。
- 發現或初始化盲點總帳:
- 如果存在先前的總帳,在搜尋之前先讀取它(差異執行規則適用——請參閱總帳和差異執行)。
- 如果不存在總帳且主機可以寫入檔案,請在最佳的專案本地文件位置建立
BLINDSPOT_LEDGER.md,除非使用者要求唯讀/純文字聊天輸出。 - 如果不存在總帳且主機無法寫入檔案,請在報告中包含建議的路徑和第一筆總帳條目。
- 從庫存中檢查最有力的證據檔案:README/AGENTS、計劃、套件配置、應用進入點、測試配置、CI、環境範例、模式、提示、代理/技能檔案和執行時期文件。
- 當主機具有網路存取權時,執行外部掃描(請參閱工作流程步驟 5)。
- 對發現進行排序,在可能的情況下訪談所有者,產生報告,並更新總帳。
主機表面政策
審計核心應在 Claude Code、Codex、OpenCode、CLI 和純文字聊天中運作相同。只有互動風格會改變。請參閱 references/host-surfaces.md 以獲取每個主機的詳細資訊。
- 具備選擇能力的主機 (Claude Code
AskUserQuestion, OpenCodequestion):當決策會改變架構、工作流程、範圍或風險時——以及對於所有者意識訪談——提出一個簡短的 2-3 選項問題,並在報告或總帳中記錄所選選項。 - Codex 或純文字聊天主機:不要因非關鍵問題而阻塞。繼續使用最安全的可逆假設,將其標記為假設,並包含一個「決策包」,其中包含使用者應稍後選擇的選項。
- 沒有網路存取權的主機:跳過外部掃描,在報告中明確說明,並將有時效性的領域(法規、平台政策、定價)標記為未經驗證,而不是根據訓練知識進行斷言。
- 可寫入檔案的主機:對於專案審計,預設情況下建立或更新總帳,除非使用者要求唯讀/純文字聊天輸出。在報告中提及路徑和路由編輯。
- 唯讀或公開分享的主機:回傳一個可攜式報告,其中包含使用者可以執行的命令/檢查。
僅在繼續下去會有風險、破壞性、成本高昂或可能產生誤導性結果時,才立即提問。
總帳和差異執行
首次執行:
- 使用
references/ledger-lifecycle.md為BLINDSPOT_LEDGER.md選擇最佳的持久位置。 - 在適當的情況下,從
templates/BLINDSPOT_LEDGER.md建立總帳。 - 當路由檔案已存在時,將總帳新增到最近的路由表面,例如操作 README、文件索引或交接指標。
- 記錄審計範圍、模式、證據邊界和初步發現。
當專案已有盲點總帳時:
- 將總帳視為輸入,而非事實。針對目前程式碼/文件重新檢查高影響力或過時的發現。
- 將輸出分類為
新發現、已改變、已確認、已降級、已解決或需要決策。 - 除非未更改的待辦事項會阻礙當前目標,否則不要重複。這是讓重複執行感覺像進步而不是干擾的關鍵。
- 如果總帳是新的但未從索引、交接或操作 README 路由,請將其標記為可發現性盲點。
- 更新總帳時,保留其本地狀態語言和 ID。
好的總帳能讓將來的審計更便宜。壞的總帳會變成另一個隱藏文件,因此始終檢查可發現性。
搜尋衛生
使用有界限的搜尋。盲點審計通常會觸及廣泛的儲存庫,而嘈雜的生成檔案可能造成虛假信心或浪費上下文。
rg 和類似工具的預設排除項,除非審計明確針對這些區域:
!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**
優先使用目標路徑和 --glob 排除項,而非全儲存庫掃描。如果廣泛掃描回傳大量生成檔案,請停止並在更嚴格的邊界下重新執行,然後再使用結果。
工作流程
1. 定義地圖
用 2-4 行說明使用者明顯的目標、專案類型、成熟度和你的審計邊界。明確標記假設。包含所有者簡介:
- 個人還是團隊?所有者明顯擅長什麼,更重要的是,「不」擅長什麼?盲點集中在所有者的非專業領域,因此要提高這些鏡頭的權重。
- 愛好還是商業?私人還是公開?商業或公開意圖會啟用法律、稅務和市場鏡頭,而這些對於私人愛好專案來說完全是雜訊。如果無法從檔案中讀取意圖,請在掃描前詢問(一個簡短的問題)——錯誤猜測意圖會浪費整個審計。
2. 收集證據
使用庫存輔助程式加上目標讀取。首先閱讀專案的自我意識表面(README、TODO、路線圖、檢查清單、設計文件、概要/大綱)——它們既是你的最佳簡介來源,也是你的雜訊過濾器(基本規則 1)。偏好證據勝過廣泛猜測。將證據標記為:
- 已觀察:直接存在於檔案或輸出中。
- 已缺失:在檢查範圍內未找到預期的工件。
- 已推斷:從結構、命名或慣例中推斷出來。
- 存疑:需要使用者或領域所有者確認。
3. 分類領域
從 references/archetypes.md 中選擇一個或多個原型。如果是混合型專案,不要強行將其歸入一個類別。
4. 應用鏡頭
僅應用適合專案階段的鏡頭。原型不需要企業合規性,但它可能仍然需要資料遺失邊界、秘密處理或可恢復性。
5. 外部掃描
當主機具有網路存取權時,對兩個問題進行限時研究:
- 健康的同類專案目前將什麼視為「標準配備」?
- 在過去 6-12 個月內,發生了哪些變化——法規、平台政策、市場或類型慣例、工具——而此專案的文件不可能包含這些?
問題 2 具有不成比例的價值:時間依賴性變化在結構上對儲存庫和所有者的記憶都是不可見的。(實戰數據:在早期執行中,單一影響最大的發現——一項將在下個月生效的 AI 內容標籤法、一項使已記錄計劃失效的支付供應商收購——都來自此步驟。)為此處發現的任何內容引用來源。如果沒有網路存取權,請跳過並揭露(請參閱主機表面政策)。
6. 將盲點轉化為檢查
對於每個發現,包括:
- 可能缺失了什麼。
- 為什麼這對此專案很重要。
- 證據。
- 最便宜的下一步檢查。
- 可能的所有者或決策表面。
- 優先級:現在、下一步、稍後或觀察。
- 信心:高、中、低。
刪除出現在專案自己的追蹤文件中的候選項目(基本規則 1),保留前 3-7 個,將其餘的移到觀察清單或總帳中。
7. 訪談所有者
呈現發現,然後詢問所有者哪些是他們已經知道的(在具備選擇能力的主機上,一個簡單的多選問題很有效)。將每個發現分類:
| 意識 | 意義 | 處方 |
|---|---|---|
unknown_unknown | 所有者不知道 | 解釋為什麼在這裡很重要 + 最便宜的初步步驟 |
unknown_known | 所有者知道,但沒有寫在任何地方 | 解決方案是文件化,而不是實施——讓它進入他們的追蹤文件,以便代理和未來的會話可以看到它 |
deliberate_skip | 所有者考慮過並選擇不處理 | 移至跳過清單,附帶原因和重新檢查觸發條件 |
(實戰數據:在早期執行中,大約一半的頂級發現結果是 unknown_known——儲存庫中的真正差距,但不在所有者的腦中。這個區別完全改變了後續行動。)
在無法提問的主機上,將每個意識值標記為 未確認,將訪談問題嵌入報告中,並將開放的決策放入「決策包」中。
8. 保持輸出的實用性
以最高信號的盲點開頭。始終包含兩個信任章節(基本規則 4)。以所有者在對話中使用的語言撰寫報告和總帳散文;保持 ID、狀態和意識值為英文,以便跨會話和語言進行差異比較。按照 references/report-template.md 格式化。
護欄
- 除非專案證據使其相關,否則不要將通用最佳實踐作為發現呈現。
- 不要重新報告已存在於總帳或專案自己的追蹤文件中的項目。
- 不要對個人實驗或早期原型要求繁重的流程。
- 除非使用者明確要求修復,否則不要進行程式碼更改。
- 不要僅僅因為檔案缺失就聲明某物已損壞;說明缺失暗示了什麼以及如何確認。
- 僅當專案聲明可重複交付、共享交接或類似生產的可靠性時,才將缺失的 CI、測試、發布文件或部署檔案視為盲點。個人筆記和早期原型可能不需要它們。
- 不要用每一種可能的風險淹沒使用者。根據專案適合度、影響範圍、可逆性和可能性進行排序。
- 當使用者在該領域非專家時,為不熟悉的盲點包含簡短的教學說明。
- 當發現取決於當前的外部平台行為時,在使用官方文件或當前研究進行驗證之前,不要將其視為事實;如果沒有網路存取權,請呈現為假設並披露你的限制。
- 輸出必須是在使用者對話中使用的語言;保持 ID、狀態和意識值為英文,以便跨會話和語言進行差異比較。