文件建立
根據當前對話內容與資料夾內容撰寫 Markdown 文件。
README 是為人類使用者撰寫的當前狀態規格，不是變更日誌、不是決策記錄、也不是歷史紀錄。絕不記錄歷史資訊或做過的選擇，只記錄撰寫 README 當下的規格。
範圍
找出專案中所有的 README.md 檔案並逐一更新。 資料夾內容範圍是 README 所在的層級及其下層（同層與子資料夾），絕不包含上層（父資料夾）。 注意子資料夾的層次、範圍與邊界脈絡。不要在位於不同層級的文件之間洩漏概念。每個 README 只涵蓋其自身目錄層級與以下內容，不涉及上層事務。
如果使用者提供了特定的指引或重點領域，在決定文件中應強調哪些內容時套用該脈絡。
收集脈絡
絕不直接執行 git。此外掛隨附的基準腳本已涵蓋本技能所需的一切 git 操作。每次從儲存庫根目錄執行指令，並每次都寫入腳本的完整路徑，因為 shell 變數在指令之間不會保留。
從計畫開始。它會找出每個 README，在沒有根 README 時建立一個，解析每個 README 的基準，列出自該基準以來的變更，並說明每個 README 該如何處理。當使用者的指引指定了要聚焦的目錄時，在 readme 之後傳入這些目錄。否則不傳入任何內容。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan readme [<focus-dir>...]
計畫會為每個動作列印一個區塊。
## update列出一個基準、一個範圍、以及該 README，後面接著自該基準以來的提交、差異統計與狀態。將 README 更新至最新狀態。若變更不影響的 README，則保留其內容。## new列出需要根據當前程式碼撰寫的 README。它們不需要歷史記錄。## unchanged與## outside the focus列出完全保持不變的 README。
head none 表示儲存庫沒有任何提交。每個 README 都是全新的。
對於更新區塊，計算其統計資料中的檔案數。如果超過 20 個，則跳過完整差異，直接讀取已變更的檔案。如果等於或少於 20 個，則讀取差異。未追蹤的檔案（標記為 ??）不會出現在任何差異中，因此無論如何都應直接讀取它們。範圍可以是區塊的範圍或單一檔案，因為它是一個 git 路徑規格。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>
然後，對於每個需要更新或撰寫的 README，在其目錄範圍內：
-
讀取現有 README（如果存在）
-
探索該目錄層級及以下層級的程式碼庫
-
檢閱對話歷史中的相關決策、變更或經驗教訓
-
使用變更與對話脈絡來識別需要更新的章節。驗證程式碼與文件的一致性，以及文件與程式碼的一致性。當程式碼中移除了一個函式、標誌或模組時，在每個 README 中 grep 搜尋其名稱，然後重新讀取每個搜尋結果以及每個 README 的概覽，以尋找以白話文描述相同事物的部分。
grep -rn '<dropped name>' <dir>/README.md
絕對不要在你撰寫或編輯的文字中包含標記行。finish 會在寫入後加上它。當編輯一個結尾已有標記行的 README 時，保留該行不動。
如果沒有任何變更需要更新 README，請說明並繼續。finish 仍然會執行。
README.md 大綱
README.md 的章節順序與內容。每個章節都應填入目標專案的內容。如果專案中沒有對應內容，則省略該章節。
# 標題與不超過五個句子的概覽- 可選的圖片或影片
## 架構- 以項目列表呈現的元件，每個元件附帶其用途## 前提條件- 帳戶、金鑰、憑證、工具、執行階段、CLI，每個都附帶需要它的原因## 專案結構- 僅資料夾，不包含檔案，每個資料夾附帶一行用途說明## 安裝- 安裝它的指令## 使用方式- 執行它的指令## 測試- 當專案沒有測試時省略
目標是少於 500 行。如果 README 較長，則將細節移到位於其所描述程式碼旁巢狀的 README 中。
範例格式
# 標題
簡要概覽。不超過五個句子。
<!-- 可選的圖片或影片重點 -->
<img src="demo.png" alt="示範" width="800"/>
## 架構
高層級元件與用途
- 元件 - 用途
- 元件 - 用途
## 前提條件
- 前提條件 - 描述與原因（帳戶、金鑰、憑證、工具、執行階段、CLI）
## 專案結構
顯示資料夾結構。不包含檔案。
```text
project/
├── src/
│ ├── component-a/ # 用途 - 請參閱 src/component-a/README.md
│ └── component-b/ # 用途 - 請參閱 src/component-b/README.md
├── scripts/ # 用途
└── tests/ # 用途
```
## 安裝
```bash
# 專案的安裝方式
<install command>
```
## 使用方式
```bash
# 專案的執行方式
<run command>
```
## 測試
```bash
# 測試的執行方式
<test command>
```
完成
每次都要執行 finish，包括沒有寫入任何內容的執行。plan 會在背後留下一個計畫檔案，只有 finish 會將其移除，因此跳過 finish 的執行會將狀態遺留給下一次執行，導致問題。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish readme
它會為計畫標記為「new」或「update」的每個 README，以及自計畫執行後建立的每個 README，蓋上計畫所檢查的 HEAD 戳記。戳記是 README 結尾處的一行標記，一個命名該次提交的 HTML 註解。finish 會保持不變的 README 與範圍外的 README 不動，並且在儲存庫沒有提交時不蓋任何戳記。退出碼 4 表示計畫中的 README 遺失。寫入它並再次執行 finish。
- 絕不直接呼叫
stamp，也絕不手動撰寫或編輯標記行。finish 會寫入它。 - 標記是中繼資料。禁止記錄歷史的規則不適用於它。