昨天介紹完 llm-wiki，我們知道它會把讀過的資料整理成 Wiki，讓知識可以持續累積。

但直接把專案丟給 AI，然後只跟它說：「欸，你幫我整理成 Wiki」，你應該可以想像那個美麗的畫面。

情況大概會是一次寫一大篇：查證結果、額外發現、測試紀錄和待決定事項全部塞進同一份文件。字很多、表格很多，卻看不出重點和結構，然後你就會默默把文件關掉。最後 AI 寫得很努力，人類看完還是不知道該先看哪裡。（難道人類還要再整理一次 AI 整理過的內容嗎）。

所以，我們要替 Agent 訂出規則，讓它整理出有結構、有證據，而且後續真的能拿來設計混沌實驗的 Wiki。

Schema 說明

簡單來說，Schema 就是我們和 Agent 之間的遊戲規則。

它會告訴 Agent：

• 哪些資料只能讀取。
• 哪些目錄可以修改。
• Wiki 頁面要怎麼分類。
• 每個結論要留下什麼證據。
• 弱點與實驗要怎麼追蹤。
• 執行 Ingest、Query 與 Lint 時要遵守哪些流程。

Schema 會依照知識庫的用途調整。因為這套 Wiki 後續要提供給 AI 設計混沌工程實驗，我們額外加入證據引用、弱點追蹤與實驗紀錄等規則。

這些規則都寫在 llm-wiki/AGENTS.md。接下來說明替 lite-bank 的系統知識訂了哪些規範。

Raw Sources 說明

第一條規則：原始資料不可修改。

llm-wiki 會把架構文件、部署 manifest、設定檔與實驗結果放在 sources/。Agent 可以讀取這些資料，但不能修改內容。

如果 Agent 可以一邊整理 Wiki、一邊回頭修改原始資料，最後就很難確認某個結論到底來自哪裡。這種玩法跟自己改考卷答案差不多，當然不行。

每一批 Raw Sources 都要有一份 manifest.json，記錄：

• 來源 repo。
• commit hash。
• 抓取時間。
• 實際收錄的檔案。

這樣才能知道目前這份 Wiki 是根據 lite-bank 的哪一個版本整理出來的。

目標 repo 的程式碼不會整份複製進 sources/。需要檢查程式碼時，Agent 會回到 manifest.json 鎖定的 commit，只讀取這次需要的檔案。

至於 Raw Sources 實際要準備哪些內容，下一篇再來處理。

Wiki 裡的內容

接下來是 wiki/ 的目錄結構。

如果所有資料都隨便塞進同一個資料夾，Wiki 很快就會變成垃圾場。所以我們先替不同類型的知識安排固定位置：

• index.md：整套 Wiki 的入口地圖。
• log.md：記錄 Ingest、Query 與其他變更的操作 log，只能往後新增。
• services/<name>.md：每個業務服務各自的頁面。
• infrastructure/<name>.md：Postgres、Kafka 與 Observability 元件等基礎設施。
• patterns/<id>.md：多個系統元件重複出現的弱點。
• source-summaries/<id>.md：保存架構文件、README 與設計說明的重點摘要。
• experiments/<exp-id>.md：記錄實驗假設、設計、安全邊界與執行狀態。
• experiments/<exp-id>-report.md：實驗真正執行後，提供給人閱讀的完整報告。

每次 Wiki 有變更時，Agent 都要檢查 index.md 是否需要同步調整。新增頁面或分類改變時才更新，純文字修正通常不需要動入口目錄。

服務體檢表

services/<name>.md 是每個服務的專屬頁面，例如 teller-service。

這個頁面會記錄：

• 服務摘要與業務重要性。
• 流量等級。
• 上下游依賴。
• 服務故障時的影響範圍。
• Framework、主要 endpoint 與部署設定。
• 已知弱點。
• 已經做過的實驗。
• 目前還缺少證據的待調查事項。

其中最重要的是「已知弱點」。

每個弱點都要使用 <SVC-PREFIX>-W<NNN> 格式編號。例如 transaction-service 發現的第一個弱點，可以寫成 TX-W001。

還需記錄弱點目前階段：

這樣回頭看 TX-W001 時，就能知道它目前只是 Agent 的靜態分析結果，還是已經經過真實實驗確認。

整理重複出現的弱點為 Pattern

如果相同弱點出現在多個 service 或 infrastructure，Agent 會把它整理到 patterns/<id>.md。

例如 teller-service 和 exchange-service 都缺少 Circuit Breaker，就可以建立：

patterns/P-001-missing-circuit-breaker.md

原本 service 頁面的弱點不會被刪除。它的狀態會改成 superseded，並連到共用的 Pattern 頁面。

各服務自己的證據與影響範圍仍然留在原本頁面。Pattern 則負責說明這類問題共同的失效原理、修復方式與驗證方法。

Infrastructure 預設不能成為故障注入目標

infrastructure/<name>.md 用來記錄 Postgres、Kafka 與 Observability 元件等基礎設施。

因為這套 Wiki 後續會用來設計混沌工程實驗，我們在 Infrastructure 頁面加入 chaos_target 欄位。

Postgres、Kafka 等基礎設施預設標記為：

chaos_target: forbidden

這是我們針對混沌工程加上的自訂規則，用來提醒 Agent：這些基礎設施只能記錄與觀察，不能直接列為故障注入目標。

Wiki 結論需附上來源

Wiki 中的每個結論都要附上來源。

如果內容來自目標 repo 的程式碼，引用要包含 repo、commit、檔案路徑與行號：

lite-bank-demo@ed545a14:services/transaction-service/.../AccountClient.java#L23

如果內容是根據證據推導出的結論，也要把推論來源寫清楚：

transaction-service 是 SPOF
(inferred from sources/architecture/docs/architecture.md § Coordination Layer)

如果證據還不夠，就先放進每個頁面的「待調查」區：

• [unverified]：目前有合理懷疑，還沒有完成驗證。
• [pending-evidence]：需要繼續找資料才能下結論。

主文只保留有證據的內容。這樣能避免 Agent 把猜測寫得像已經確認的事實。

Confidence 只用在弱點與假設

Confidence 分成三個等級：

這個標記只用在弱點與實驗假設。

一般架構事實要有證據才能寫進主文。找不到證據時，就先放到「待調查」，不能隨手標一個 low 就當作完成。

我們也在 Schema 裡提醒 Agent：寧可先標 low，也不要硬寫一個假的 high。

實驗要有明確狀態

每個實驗會放在 experiments/<exp-id>.md，並記錄假設、注入點、觀察指標、安全邊界與中止條件。

實驗頁面的狀態包含：

• dry-run-designed
• executed
• reflected

目前只做到實驗設計的階段，所以狀態會是 dry-run-designed。這代表 proposed.yaml（準備使用的混沌實驗設定）與 Wiki 頁面已經完成，但 Agent 還沒有真正執行 kubectl apply。

等到後面真的執行故障注入、有監控證據之後，才會進入 executed，並產生對應的實驗報告。

完成實驗設計或執行結果的反思，並把內容回寫 Wiki 後，狀態會改成 reflected。

主要規則整理

最後整理一下目前的主要規則：

結論

有了這套 Schema，Agent 寫進 Wiki 的內容就有固定位置，每個結論也能回頭找到證據。

它仍然可能理解錯誤，所以人類還是要檢查 Agent 寫下來的內容。至少現在它猜錯時，我們有來源、版本與 Confidence 可以往回追，不會只剩下一句「AI 說的」。

規則定好之後，下一步要準備 Agent 可以讀取的原始證據。

下一篇，我們來整理 lite-bank 的 Raw Sources，並用 manifest.json 鎖定來源版本。我們明天見！