Community寫作與編輯github.com

盲點審計 (Blindspot Audit)

一個可攜式的 AI 代理技能,用於發現專案盲點、未知的未知、隱藏風險和缺失決策,並提供一個持久的總帳,可在 Claude Code、Codex 和 OpenCode 中進行重複審計。

盲點審計 (Blindspot Audit) 是什麼?

盲點審計技能旨在彌合使用者對專案的認知地圖與專案實際狀態之間的差距。它將「未知的未知」轉化為具體的「已知的未知」,讓使用者能夠檢查、測試或策略性地推遲這些項目。此技能的核心在於「四種未知」框架:已知的已知、已知的未知、未知的已知、和未知的未知。它透過引入專案外部的參考框架來測量差距,從而找出開發者和文件可能遺漏的隱藏風險。此技能支援多種模式(快速、深入、訪談、實施後、規劃)和多種主機平台(Claude Code、Codex、OpenCode、CLI 和純文字聊天),並能適應不同主機的能力,例如提問或寫入檔案。它還包含一個持久的盲點總帳,用於追蹤多次審計中的發現,確保反覆執行時能感受到進展而非干擾。

相容平台✓Claude Code✓Codex CLI~Cursor✓OpenCode
npx skills add MJL-ren/blindspot-audit

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

盲點審計

目的

找出使用者對專案的地圖與專案實際領土之間的差距。將未知的未知轉化為具體的已知的未知,讓使用者可以檢查、回答、測試或策略性地推遲。

專案的背景是自我選擇的:所有者只能寫下他們已知的內容,因此每個 README、TODO 和計劃都編碼了他們腦中的地圖——而基於這些檔案工作的 AI 會繼承相同的盲點。此審計刻意引入專案「外部」的參考框架來測量該差距。

這項技能不是一般的品質檢查清單。它應該識別出對於這個特定專案、在當前特定階段、根據儲存庫或提供的工件證據,什麼是異常重要的。當所有者至少說出一次「我甚至不知道我應該考慮這個」,並且事後感到更平靜(因為他們現在也知道可以安全忽略什麼)時,審計就算成功。

核心模型

使用四種未知框架對發現進行分類:

  • 已知的已知 (Known knowns):提示、文件、程式碼或計劃中已經陳述的內容。
  • 已知的未知 (Known unknowns):文件、TODO、計劃、註解或用戶措辭中已可見的開放問題。
  • 未知的已知 (Unknown knowns):如果展示給使用者,使用者會辨識出來,但尚未口語化或寫下的事物。
  • 未知的未知 (Unknown unknowns):專案形狀所暗示的遺漏概念、隱藏限制或未提出的問題。

此框架之所以重要,是因為解決方案不同:未知的已知需要一個檢查清單項目,而不是一場講座;未知的未知需要一個簡短解釋和最便宜的初步步驟。好的輸出不會聲稱確定性。它會提出候選項目,並給出最便宜的下一步檢查。

基本規則

制定這些規則的原因在於,此技能的失敗模式不是「遺漏差距」,而是變成一個被忽略的通用檢查清單。

  1. 專案自己的追蹤文件是過濾器,不是發現的來源。 任何已經在 README / TODO / 路線圖 / 檢查清單 / 問題列表中的項目都是「已知的未知」。永遠不要將其報告為發現。(實戰數據:此過濾器通常會將候選清單減少一半以上,並且是所有者信任報告的主要原因。)
  2. 頂級發現限制在 3-7 個,按影響力 x 所有者真正不知情的可能性排序。其餘的放入簡短的「低信號觀察清單」或總帳中——永遠不要放入主列表。
  3. 僅有缺失不是一個發現。 「你沒有 X」只有在你能說明這對「此」專案的具體後果,以及最便宜的初步解決步驟時才算數。
  4. 始終包含兩個信任章節:「已檢查且涵蓋良好」和「目前可跳過」(每個跳過項目都附帶明確的重新檢查觸發條件)。它們可以防止焦慮和重複掃描,並且是所有者學習信任報告的方式。
  5. 對受監管領域保持謹慎。 對於法律、稅務或法規方面的發現,說明你發現了什麼及其來源,然後明確指出需要專業人士確認。你是偵察兵,不是律師或會計師。

模式

  • 快速:讀取文件和專案庫存,回傳頂級盲點。
  • 深入:在對發現進行排序之前,檢查代表性的程式碼路徑、測試、配置和文件。
  • 訪談:當答案會改變架構、工作流程、範圍或風險時,一次問一個問題。
  • 實施後:比較已完成變更、筆記、差異和測試,以找出剩餘的未知。
  • 規劃:在實施之前,找出可能改變資料模型、介面、使用者體驗流程、操作或驗證的決策。

從使用者的措辭推斷模式。如果使用者要求立即執行,除非審計邊界無法推斷,否則不要詢問模式問題。

快速開始

  1. 識別專案根目錄和審計邊界。
  2. 當檔案系統專案可用時,執行庫存輔助程式。該腳本位於此技能的資料夾中——請相對於此 SKILL.md 解析其路徑:
python <this-skill-folder>/scripts/project_inventory.py <project-root> --format md

僅在執行時期輸出、生成的報告、日誌或快取工件是審計問題的一部分時,才使用 --include-generated。

  1. 僅讀取相關參考資料:
    • references/archetypes.md:選擇專案類型和預期盲點。
    • references/lenses.md:推導並應用審計鏡頭。
    • references/host-surfaces.md:調整問題和輸出以適應 Claude Code、Codex、OpenCode、CLI 或純文字聊天。
    • references/ledger-lifecycle.md:發現、建立、路由或更新持久的盲點總帳。
    • references/report-template.md:格式化結果。
  2. 發現或初始化盲點總帳:
    • 如果存在先前的總帳,在搜尋之前先讀取它(差異執行規則適用——請參閱總帳和差異執行)。
    • 如果不存在總帳且主機可以寫入檔案,請在最佳的專案本地文件位置建立 BLINDSPOT_LEDGER.md,除非使用者要求唯讀/純文字聊天輸出。
    • 如果不存在總帳且主機無法寫入檔案,請在報告中包含建議的路徑和第一筆總帳條目。
  3. 從庫存中檢查最有力的證據檔案:README/AGENTS、計劃、套件配置、應用進入點、測試配置、CI、環境範例、模式、提示、代理/技能檔案和執行時期文件。
  4. 當主機具有網路存取權時,執行外部掃描(請參閱工作流程步驟 5)。
  5. 對發現進行排序,在可能的情況下訪談所有者,產生報告,並更新總帳。

主機表面政策

審計核心應在 Claude Code、Codex、OpenCode、CLI 和純文字聊天中運作相同。只有互動風格會改變。請參閱 references/host-surfaces.md 以獲取每個主機的詳細資訊。

  • 具備選擇能力的主機 (Claude Code AskUserQuestion, OpenCode question):當決策會改變架構、工作流程、範圍或風險時——以及對於所有者意識訪談——提出一個簡短的 2-3 選項問題,並在報告或總帳中記錄所選選項。
  • Codex 或純文字聊天主機:不要因非關鍵問題而阻塞。繼續使用最安全的可逆假設,將其標記為假設,並包含一個「決策包」,其中包含使用者應稍後選擇的選項。
  • 沒有網路存取權的主機:跳過外部掃描,在報告中明確說明,並將有時效性的領域(法規、平台政策、定價)標記為未經驗證,而不是根據訓練知識進行斷言。
  • 可寫入檔案的主機:對於專案審計,預設情況下建立或更新總帳,除非使用者要求唯讀/純文字聊天輸出。在報告中提及路徑和路由編輯。
  • 唯讀或公開分享的主機:回傳一個可攜式報告,其中包含使用者可以執行的命令/檢查。

僅在繼續下去會有風險、破壞性、成本高昂或可能產生誤導性結果時,才立即提問。

總帳和差異執行

首次執行:

  1. 使用 references/ledger-lifecycle.md 為 BLINDSPOT_LEDGER.md 選擇最佳的持久位置。
  2. 在適當的情況下,從 templates/BLINDSPOT_LEDGER.md 建立總帳。
  3. 當路由檔案已存在時,將總帳新增到最近的路由表面,例如操作 README、文件索引或交接指標。
  4. 記錄審計範圍、模式、證據邊界和初步發現。

當專案已有盲點總帳時:

  1. 將總帳視為輸入,而非事實。針對目前程式碼/文件重新檢查高影響力或過時的發現。
  2. 將輸出分類為 新發現、已改變、已確認、已降級、已解決 或 需要決策。
  3. 除非未更改的待辦事項會阻礙當前目標,否則不要重複。這是讓重複執行感覺像進步而不是干擾的關鍵。
  4. 如果總帳是新的但未從索引、交接或操作 README 路由,請將其標記為可發現性盲點。
  5. 更新總帳時,保留其本地狀態語言和 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. 外部掃描

當主機具有網路存取權時,對兩個問題進行限時研究:

  1. 健康的同類專案目前將什麼視為「標準配備」?
  2. 在過去 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、狀態和意識值為英文,以便跨會話和語言進行差異比較。

相關技能