黑盒子 (Blackbox)
概述
黑盒子是一個項目的飛行記錄器：每個經所有者批准的變更單位，都有一份非摘要式的決策記錄——包含所有者實際說的話（逐字稿）、其在上下文中的含義、助手的建議與建置內容、選擇理由、驅動每個選擇的證據，以及助手在過程中犯的錯誤——這些記錄固定在其解釋的內容上，並僅在需要時才讀取。它的存在是為了讓未來的會話可以稽核規則的來源，而不是重新爭論它。
它有兩個不屬於的範疇：
- 不是逐字稿。 選擇並非摘要。條目是根據決策軌跡而非聊天記錄撰寫的：有助於所有者理解但未改變任何決策的教學、類比和岔題，都被省略。保留下來的內容則完整保留。
- 不是關於所有者的日記。 它記錄的是說了什麼和決定了什麼，而非所有者是誰。工作風格的觀察應放在助手的記憶中，絕不放在這裡。
這個項目有黑盒子嗎？
blackbox/README.md位於項目旁（或儲存庫根目錄） → 表示採用此慣例。在撰寫你的條目前，請先閱讀該README以及最新的條目—— schema 來自它們，而非你的想像。- 沒有標記，且所有者要求採用 → 初始化：從此技能的目錄複製
blackbox/README.md到項目中，除了項目名稱外不要更改任何內容，然後將採用行為本身記錄為第一個條目。 - 沒有標記，且你即將在此會話中首次編輯一份規格/慣例/設計文件 → 檢查標記。如果不存在，一次性地用一句話提出採用建議，然後繼續執行所有者的任務。採用與否由所有者決定；如果他們拒絕，請在記憶中記下，以便不再向此儲存庫提問。
採用的單位是包含標記的目錄——一個技能、一個套件，或整個儲存庫。任何儲存庫、任何合併方式皆可。
單位與時機
- 每個經所有者批准的單位一條條目：已確認的規格、已合併的 PR、已修訂的慣例。不是每次提交一條，也不是每次對話輪次一條。產生多次提交的單位，只會有一條條目。
- 在決策發生的會話中撰寫。 原始的交流僅存在於當前上下文中；一旦會話結束，只有摘要會留存，逐字引用也將消失。如果一個單位時間過長或跨越會話，請儘早保存草稿——填入
Refs: pending、所有者的引用和索引——並在批准時完成（固定 blob、完成本文）。一份草稿勝過重建的記憶。
配方（每個經所有者批准的單位）
- 進行變更。
- 按內容固定結果。 對於每個變更的檔案，對工作目錄執行
git hash-object <path>。Blob SHA 是內容定址的——相同的位元組永遠會產生相同的 hash，因此固定能經得起 squash、rebase 和任何歷史重寫，並且它存在於任何提交之前。 - 撰寫條目
blackbox/YYYY-MM-DD-<slug>.md，格式如下：一個指向本文的索引，然後是純本文。 - 將條目與變更一起提交——同一個 commit 或同一個 PR，無論儲存庫通常如何合併。
驗證固定：執行 git hash-object <path> 並比對。檢索固定狀態：使用 git log --find-object=<sha> 或 GitHub 的 blobs API。
閱讀規則：在項目的正常工作期間，永遠不要載入 blackbox/。僅在調查來源問題時才讀取它。
條目格式
# YYYY-MM-DD — <標題>
Refs: <路徑> @ blob <sha> (每個變更檔案一行)
Decisions: <決策> <權重> [→ <新權重>, 參見 §…] · …
Reversals: §… · §… (或：無)
Owner caught: §… · … (或：無)
Declined: §… · … (或：無)
Evidence: <指令 / 數字 / 連結> · …
Understanding: §… (或：不適用)
---
<純本文，包含索引指向的 § 標題>
索引行指向本文；它們永不取代本文。
- Decisions — 單位中包含的每個決策，以及助手在詢問時賦予的權重（🔴 必須立即決定 · 🟡 決定，可修正 · 🟢 接受建議）。如果權重後來被更改，請說明並指出原因。隨著時間推移，這一行是所有者稽核自己的審議過程與決策應得權重之間差異的方式。
- Reversals — 助手曾主張但後來撤回或改正的任何事項：錯誤的主張、被測量結果推翻的建議、未經詢問而做出的決定。
無是有效值，且必須明確寫出。 - Owner caught — 所有者發現的不一致或缺陷（錯誤的計數、遺漏的項目、結構性錯誤）。所有者的稽核，而非僅是助手的。
- Declined — 故意不採納的選項、工具預設值或外部建議，理由在本文中說明。
- Evidence — 決策時實際參考的內容：執行的指令、產生的數字、顯示的頁面或檔案。記錄可重現的步驟，而非圖像——圖表應由指令重新生成；螢幕截圖則不適用。
- Understanding — 當所有者在表示不完全理解的情況下批准時，他們的陳述以及必須稍後重新解釋的內容。
語言
- 本文：英文，無論儲存庫的文件語言為何。
- 所有者的輸入：先提供原始逐字稿，再提供英文改寫。 逐字稿在前，放在
>引用區塊中，完全按輸入的樣子——包含錯字、縮寫、ㅇ等。然後是改寫：內容完整、形式自然、自成體系（沒有其他上下文的讀者也能理解）。逐字稿是證據——只有在那裡才能找到改變了決策的錯字。改寫是助手當時的解讀——如果兩者不一致，條目本身就已經記錄了這個錯誤。 - 助手的回應、理由和內部處理過程：英文，對於任何與決策相關的內容，都使用完整形式。
> ㅇ後面接著所有者批准了選項 (a)。就是完整的記錄；不需要填充內容。
嚴格格式
| 規則 | 不正確的範例 |
|---|---|
| 所有者輸入 = 逐字引用 和 英文改寫 | 僅有逐字引用（無上下文難以閱讀）、僅有改寫（遺失證據），或僅一行摘要 |
索引在頂部，純本文在下方，索引行指向 § 標題 | 索引做摘要而非指向；本文沒有索引；章節只填充一行內容 |
| 本文來自決策軌跡 | 未改變任何決策的教學、類比或岔題 |
Reversals: 存在，即使是 無 | 只列出正確事項的條目 |
Refs: = 每個檔案的 blob SHA（git hash-object） | 使用 commit 或 PR 編號作為錨點——歷史重寫會破壞它們 |
| 條目與變更在同一個 commit 或 PR 中提交 | 後續的 "稍後" PR |
| 在決策發生的會話中撰寫 | 下個會話根據記憶重建 |
| 條目 schema 來自 README 和最新的條目 | 發明的格式 |
危險信號
- 缺少
Refs:行的條目，或Refs:使用 commit 或 PR 而非 blob 的條目 - 缺少
>逐字引用的所有者輸入，或引用後沒有改寫 - 完全缺少
Reversals:行 - 讀起來像是摘要而非指向的索引行
- 向讀者解釋概念而非記錄決策內容的本文
- 變更合併了但缺少其條目
- 在記錄決策的之後的會話中撰寫的條目（如果無法避免，請在條目中說明）
來源
blackbox/ 存放此項目的完整決策記錄——所有者輸入（逐字稿 + 英文改寫）、助手推理、證據和推翻事項，並按經批准的變更進行內容固定。僅在調查規則存在原因或所有者最初要求什麼時閱讀。在正常使用期間永遠不要載入它。