Wiki
專案 Wiki 是一個 Markdown 頁面資料夾，用來解釋專案內容：各元件的功能、運作方式及依據。供人閱讀，由代理程式維護。每當有新的來源、問題或程式碼變更時，都應讓 Wiki 變得更加完整與準確。
此方法遵循「LLM wiki」模式：保留原始來源、撰寫摘要與連貫說明的頁面，並維護索引與日誌，讓整體內容易於瀏覽。
先遵守儲存庫規則
如果儲存庫已有 Wiki，請先讀取其結構或指令檔案（通常是 wiki/README.md、wiki/AGENTS.md 或 wiki/schema.md），再進行任何變更。該 Wiki 的佈局、元資料、連結樣式與指令優先於此處的預設值。當儲存庫已有 Wiki 腳本時，請直接使用，不要手動編輯這些腳本產生的檔案。
組成部分
| 部分 | 說明 | 誰負責編輯 |
|---|---|---|
| 來源 | 原始資料的副本：問題、PR、文章、筆記、逐字稿 | 新增後不再修改 |
| 頁面 | 針對主題撰寫的說明，引用來源與程式碼 | 事實變更時更新 |
| 結構 | 一份包含 Wiki 規則的檔案：佈局、元資料、慣例 | 經審慎考量後變更 |
| 索引 | 每個頁面的清單，附一行摘要 | 重新產生或保持完整 |
| 日誌 | 按日期排列、只能附加的 Wiki 變更記錄 | 每次操作新增一筆 |
一個新 Wiki 的預設佈局：
wiki/
├── README.md # Wiki 的用途與使用方法
├── schema.md # 規則（唯一記錄規則的地方）
├── index.md # 每個頁面一行
├── log.md # 變更記錄，最新者置底
├── pages/ # 主題頁面
└── sources/ # 原始資料，新增後不變
小規模專案到此即可。只有在頁面數量多到讓人難以找到時，才新增子資料夾。
來源衝突時的裁決原則
在結構（schema）中寫明，對於各類宣稱，哪個來源具有最高權威。對大多數軟體專案而言：
- 程式碼目前的實際行為： 程式碼及其測試。
- 已做出的決定及其原因： 決定記錄、Issue 或 PR。
- 計劃中或進行中的事項： Issue 追蹤器或 roadmap。
當頁面與其權威來源不一致時，修正頁面，若舊資訊值得保留則簡短記錄變更內容。絕不修改來源以使其與頁面相符。
頁面
-
每個頁面一個主題，標題清楚明確。應更新現有頁面，而非新增近乎重複的頁面。
-
引用你所宣稱的內容。 連結至來源或指名檔案。讀者應能驗證任何重要陳述。
-
使用相對的 Markdown 連結（例如
[Parser](parser.md)），除非 Wiki 已使用其他樣式。 -
保持 frontmatter 精簡。 一個實用的最低限度範例：
--- title: Parser summary: 如何讀取並驗證輸入檔案。 sources: [sources/issue-42.md] code: [src/parser.ts] updated: 2026-01-31 ---僅在有人或腳本會使用時才增加欄位。
-
每個頁面都應可從索引和至少一個相關頁面到達。
操作
設定新 Wiki
- 檢視已存在的文件及其讀者。不要重複建立一個運作中的文件網站。
- 向使用者提議佈局與結構，在開始撰寫頁面前達成共識。
- 建立
README.md、schema.md、index.md和log.md。 - 為專案最重要的部分撰寫數個頁面，然後暫停並與使用者確認，再繼續填寫其餘部分。
- 將儲存庫的代理程式指示檔案（
AGENTS.md、CLAUDE.md）指向結構檔案，而非將規則複製到其中。
新增來源
- 將原始資料儲存至
sources/下，並註明來源出處與時間。 - 完整閱讀該來源。
- 找出所有受影響的現有頁面，並進行更新。僅在完全沒有相關主題的頁面時，才建立新頁面。
- 注意來源中與現有頁面矛盾之處，並根據權威規則解決。
- 更新索引，並新增一筆日誌記錄。
僅儲存來源而不更新任何頁面，不算完成。頁面才是供人閱讀的內容。
回答問題
- 從索引開始，然後搜尋頁面標題與內容。
- 閱讀相關頁面，並對照其來源或程式碼驗證重要宣稱。
- 回答時附上所使用的頁面與證據連結。說明它們之間是否有不一致之處，或 Wiki 中是否有未解答的部分。
- 如果答案是新的且可能會被再次提問，主動提議將其加入 Wiki。
程式碼變更後更新
當變更改變了某個功能的行為時：
- 在 Wiki 中搜尋變更所觸及的檔案、函式與術語。
- 在與程式碼變更相同的 PR 中更新所有受影響的頁面。
- 若標題或摘要有所變更，則更新索引，並新增一筆日誌記錄。
檢查 Wiki 健康狀態
檢查項目：
- 失效連結，以及已不存在的程式碼路徑；
- 沒有入站連結的頁面；
- 相同主題的重複頁面；
- 沒有任何頁面引用的來源；
- 頁面之間或頁面與程式碼之間矛盾的陳述；
- 索引遺漏了頁面或列出了已刪除的頁面。
直接修復機械性問題（如連結與索引）。將需要判斷的事項（例如合併頁面或決定何者為正確陳述）回報給使用者。
日誌記錄
每次操作在 log.md 末尾新增一筆記錄：
## 2026-01-31 14:05 UTC：攝取 | Issue 42，空輸入行
已將該 Issue 新增為來源，並更新了 Parser 頁面的驗證章節。
務必包含時間與時區，以便同一天的記錄保持順序。
禁止事項
- 在新增來源後編輯它。
- 未經詢問即重組或重新命名 Wiki 的大部分內容。
- 因為頁面過時就刪除它。應將其標記為過時，並連結至取代它的內容。
- 在多個地方撰寫相同的規則。結構（schema）是唯一的規則副本。
- 將 Wiki 視為比其所描述的程式碼更高的權威。
- 未經使用者同意即寫入外部系統（Confluence、Notion、Issue 追蹤器）。