更新專案文件
兩項職責：
- CLAUDE.md — 簡潔的專案概覽（總是載入）
- .llmdocs/ — 詳細的按概念劃分的文件（按需載入）。此處所有文件均為持久性的設計文件。
1. CLAUDE.md — 地圖
範圍
找出專案中的所有 CLAUDE.md 和 .llmdocs/ 目錄並進行更新。 請注意子資料夾的層級、範圍和有限上下文。不要在不同層級的文件之間洩漏概念。每個 CLAUDE.md 和 .llmdocs/ 只涵蓋其自身目錄層級及以下，不涉及上層的關注點。
如果使用者提供了具體的指引或關注領域，請在決定更新哪些文件以及強調什麼內容時應用該上下文。
收集上下文
永遠不要直接執行 git。此插件附帶的基礎腳本已涵蓋此技能所需的所有 git 操作。從儲存庫根目錄執行每個命令，並且每次都寫入腳本的完整路徑，因為 shell 變數在命令之間不會保留。
從計劃開始。它會找到每個 CLAUDE.md 及其 .llmdocs/，包括尚不存在的必要文件，解析每個文件的基準線，列出自該基準線以來的變更，並說明每個文件該如何處理。當使用者的指引指定了要關注的目錄時，請在 llmdocs 後面傳入它們。否則不傳入任何參數。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" plan llmdocs [<focus-dir>...]
計劃會為每個動作列印一個區塊。
## update指出一個基準線、一個範圍以及共享該基準線的文件，接著是自該基準線以來的提交、差異統計和狀態。將這些文件更新到最新。變更未影響到的文件則保留其內容。## new列出需要根據當前程式碼編寫的文件。它們不需要歷史記錄。## unchanged和## outside the focus列出需保持原樣的文件。
head none 表示儲存庫沒有提交。每個文件都是新的。
對於一個更新區塊，計算其統計中的檔案數量。超過 20 個時，跳過完整差異，直接讀取變更過的檔案。20 個或更少時，讀取差異。未追蹤的檔案（標記為 ??）不會出現在差異中，因此無論如何都需直接讀取它們。範圍可以是區塊的範圍或單個檔案，因為它是一個 git 路徑規範。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" diff <sha> <scope>
然後，對於每個需要更新或編寫文件的 CLAUDE.md/.llmdocs/ 配對：
- 讀取當前的
CLAUDE.md和.llmdocs/中的每個檔案（如果它們存在） - 探索該目錄層級及以下的程式碼庫
- 檢視對話歷史以獲取相關的決定、變更或經驗教訓
- 使用變更和對話上下文來辨識發生了什麼變化。llmdocs 是當前狀態的規格說明，不是變更日誌，不是決策日誌，也不是歷史記錄。永遠不要記錄歷史資訊或所做的選擇，只記錄在撰寫 llmdocs 時的當前規格。
編寫/更新 CLAUDE.md
目標：500 行以內。每一行都必須有其存在的價值。
# <名稱>
<此目錄/元件的 1-2 行目的說明>
## 技術棧
<條列項目：此層級相關的語言、框架、關鍵依賴>
## 佈局
<此層級的關鍵目錄及其內容>
## 命令
<僅限命令：建置、測試、檢查、部署>
## 慣例
<樣式、命名、模式 — 僅限能預防錯誤的內容>
## 關鍵概念
<Claude 在此層級必須了解的領域術語、業務邏輯>
## LLM 文件
`.llmdocs/` 中的詳細文件：
- @.llmdocs/architecture.md — <一行描述>
- @.llmdocs/data-model.md — <一行描述>
CLAUDE.md 規則
- 不要詳細解釋 — Claude 會自行推斷
- 不要重複 .llmdocs/ 的內容 — 僅引用並附上簡短描述
## LLM Docs章節必須列出所有 .llmdocs/ 檔案，並為每個檔案附上一行描述- 一個在其
## Docs下列出 .llmdocs/ 檔案的 CLAUDE.md 是使用舊版標題。每當你更新該檔案時，請將該標題重新命名為## LLM Docs - 保留現有的自訂說明（git 工作流程、環境變數等）
- 僅當程式碼與其矛盾時才移除內容，並在摘要中說明每個移除項
- 當程式碼移除了一個函式、標誌或模組時，在該層級的每個文件中 grep 搜尋其名稱，然後重新閱讀每個匹配項以及每個文件的用途行，以取得針對同一事物的平實語言描述。僅從一個文件中移除名稱是不夠的
grep -rn '<已移除的名稱>' <dir>/CLAUDE.md <dir>/.llmdocs
- 永遠不要在您編寫或編輯的文字中包含標記行。完成腳本會在完成寫入後添加它。當編輯一個已經以標記結尾的文件時，請保留該行
- 使用
@.llmdocs/filename.md匯入可讓某個文件始終被載入
2. .llmdocs/ — 領域
流程
除了七個必要檔案之外的概念檔案可由你自行添加，且計劃永遠不會提到它。完成腳本仍然會為它以及在此次執行中建立的該層級的所有其他文件加上時間戳記。
- 評估：使用計劃的更新區塊來辨識哪些文件受到影響
- 識別：確定哪些現有文件受到影響，或者是否需要一個新文件
- 更新 CLAUDE.md：確保
## LLM Docs章節列出了任何新的文件檔案
如果沒有任何變更需要更新文件，請說明情況並繼續。
位置
使用 CLAUDE.md 的 ## LLM Docs 標題下第一個匯入指向的路徑，或者在較舊的 CLAUDE.md 的 ## Docs 下的路徑。否則，預設為目標目錄層級的 .llmdocs/。CLAUDE.md 和 .llmdocs/ 可以存在於專案中的任何目錄層級。
結構
扁平結構，每個概念一個檔案。前 7 個檔案是必需的且必須始終存在。testing.md 在專案具有測試套件時建立，在沒有時則省略。根據需要建立其他概念檔案。
.llmdocs/
architecture.md # 元件、互動、資料流程（必要）
api.md # 端點、請求/回應、認證、授權（必要）
data-model.md # 架構、模型、關係（必要）
deployment.md # 部署流程、環境（必要）
ops.md # 操作手冊、維護、故障排除（必要）
observability.md # 日誌、指標、追蹤、健康檢查、儀表板、警報（必要）
security.md # 信任邊界、機密處理、身份驗證/授權、威脅模型（必要）
testing.md # 測試佈局、測試執行器、測試裝置、如何執行測試套件（當專案有測試時）
<概念>.md # 根據需要添加領域特定概念
文件格式
# <概念>
<一行用途>
## <章節>
<內容：標題、表格、程式碼區塊 — 不含散文段落>
.llmdocs/ 規則
- 每個檔案最多 500 行 — 如果更長則拆分
- 在有用處包含檔案路徑和行號引用（
src/auth/login.ts:42） - 增量更新現有文件，不要重寫
- 如果文件準確且未受最近的變更影響，請保留其內容。完成腳本仍會更新其標記
- 準確性勝過覆蓋範圍：僅記錄可從程式碼驗證的內容
observability.md包含系統發出的信號，而ops.md包含操作者採取的行動。健康檢查端點、日誌格式或警報屬於observability.md。沒有指標或追蹤的專案仍應記錄其標準輸出、標準錯誤和退出碼- 永遠不要在您編寫或編輯的文字中包含標記行。完成腳本會添加它。你建立的概念檔案是這裡的陷阱，因為你剛剛讀取的每個同級檔案都以一個標記結尾。複製該行會寫入一個過時的雜湊，聲稱該文件已針對一個它從未見過的提交進行了檢查。在新檔案的最後一行內容處結束，讓完成腳本添加標記
3. 完成
每次執行完成腳本，包括沒有任何寫入的執行。plan 會留下一個計劃檔案，只有完成腳本會移除它，因此跳過完成腳本的執行會留下狀態，導致下一次執行時出錯。
bash "${CLAUDE_SKILL_DIR}/../../scripts/doc-baseline.sh" finish llmdocs
它會為計劃標記為「新增」或「更新」的每個文件，以及自計劃以來建立的每個文件（例如 testing.md），加上計劃檢查的 HEAD 的時間戳記。時間戳記是文件末尾的一個標記行，一個命名了該提交的 HTML 註釋。完成腳本會保留未更改的文件和焦點範圍外的文件，並且當儲存庫沒有提交時不加上任何時間戳記。退出碼 4 表示一個計劃中的文件缺失。請寫入該文件並再次執行完成腳本。
- 永遠不要直接呼叫
stamp，也永遠不要手動編寫或編輯標記行。完成腳本會寫入它。 - 標記是元資料。禁止記錄歷史的規則不適用於它。
4. 摘要輸出
執行完成後，輸出此摘要。根據執行情況填寫每一行，如果列表為空則寫入「none」。在「已添加時間戳記」下方，逐字複製完成腳本自己的行，每個文件一行。永遠不要在那裡寫入 sha，也不要添加任何完成腳本未列印的詞語。
一個為了刪除某項功能而重新措辭的句子屬於移除。請在「已移除」下方列出消失的措辭，即使同一行仍然存在。
填寫完成的範例，來自一個程式碼移除了字元計數的執行。
建立的檔案：無
修改的檔案：CLAUDE.md, .llmdocs/api.md
CLAUDE.md 新增、更新或移除的章節：關鍵概念已更新
因程式碼矛盾而移除：
- CLAUDE.md：從用途行移除了「或字元」，以及 --chars 關鍵概念
- .llmdocs/api.md：移除了 count_chars 行
已添加時間戳記：
- stamped CLAUDE.md (marker)
- stamped .llmdocs/api.md (marker)
當變更不需要更新文件時，請在摘要上方寫入「無需文件變更」。