sync-project-docs
稽核並更新 Claude Code 的專案層級上下文檔案。CLAUDE.md、技能和記憶的部分可自動處理；設定部分則僅提供建議，因為這些需要明確的使用者授權。
第一階段 — 了解現狀
如果專案使用 git：
git log --oneline -20
git status --short
然後執行 git diff HEAD~5 -- <下方的重要檔案> 來查看最近的基礎架構變更。
如果沒有 git 倉儲，直接讀取目錄結構和重要檔案。
找出哪些檔案存在：
| 尋找目標 | 範例 |
|---|---|
| 套件/依賴設定 | package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, requirements.txt, Gemfile |
| 指令 | Makefile, justfile, scripts/, package.json 中的 scripts, taskfile.yml |
| 基礎架構 | docker-compose.yml, fly.toml, render.yaml, Procfile, vercel.json, k8s/ |
| 應用程式設定 | config.*, settings.*, config/, application.yml |
| 環境變數範本 | .env.example, .env.template, .env.sample |
目標：了解哪些工作已完成、哪些正在進行中，以及哪些重要檔案已變更。
第二階段 — 稽核並更新 CLAUDE.md
檢查所有專案層級的指令檔案：
ls CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md .claude/rules/ 2>/dev/null
如果 CLAUDE.md 不存在：叫用 sub-skills/init/SKILL.md 中的 init 技能，然後繼續。
如果 CLAUDE.md 存在，讀取它並針對第一階段的來源交叉檢查每個章節：
指令 — 與實際的指令來源比對。修正已變更的指令，新增有用的指令，移除已刪除的指令。
架構/結構 — 將描述的模組和重要檔案與磁碟上實際存在的內容比對。新增新增的項目；移除已刪除或重新命名的項目。
設定/環境變數 — 與實際的設定檔案比對。新增新的執行時期相關設定；移除或修正過時的設定。
限制與注意事項 — 檢查近期工作是否解決了任何已記錄的限制。
環境變數範本：確認它列出了設定所需的所有變數。遺漏的變數會導致全新環境設定失敗。
@import 參考：掃描 @path/to/file 行，並確認每個匯入的檔案仍然存在。遺失的匯入會默默地破壞上下文載入。
檔案大小：如果檔案超過 200 行，標記它 — 超過此大小，遵循度會下降，上下文成本會增加。建議將詳細內容移至 .claude/rules/ 中的主題檔案。
.claude/rules/：如果此目錄存在，檢查是否有任何路徑限定的規則檔案參考了不再符合當前程式碼庫的指令、模組名稱或檔案路徑。修正或標記過時的規則。
CLAUDE.local.md：如果此檔案存在，對它執行與 CLAUDE.md 相同的檢查 — 它是被 gitignore 忽略的個人補充檔案，也可能會過時。
精準修改：更新過時的內容，保留準確的內容不變。未來的 Claude 工作階段會讀取它。
第三階段 — 稽核專案技能
ls .claude/skills/ 2>/dev/null
讀取每個技能。分為兩類：
與基礎架構耦合的技能（執行、部署、遷移、CI、整合）參考具體的項目 — 指令、服務、連接埠、環境變數、檔案路徑。針對第一階段的結果進行交叉檢查：
- 參考的指令是否仍然存在？
- 服務名稱、連接埠和 URL 是否仍然相符？
- 環境變數是否仍然存在於設定中？
- 檔案路徑和模組名稱是否仍然有效？
直接修正小的差異。對於需要大幅重寫的執行/啟動技能（新的啟動順序、重大的服務變更），先詢問：
「執行技能看起來明顯過時了。要從頭使用
/run-skill-generator重新產生（可能會遺失自訂的注意事項），還是手動重寫過時的章節？」
如果不存在執行技能且啟動方式不簡單：建議使用 /run-skill-generator（如果可用），否則使用 /run 作為備案。
流程/工作流程技能（PR 範本、提交風格）：僅在 git 紀錄顯示所描述的流程已變更時才檢查；否則保留不變。
第四階段 — 記憶
記憶路徑是根據 git 倉儲根目錄（如果在倉儲外則為 pwd）推導出來的：
REPO=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "$HOME/.claude/projects/$(echo "$REPO" | sed 's|/|-|g')/memory/"
如果記憶存在：叫用 consolidate-memory。
如果不存在：在建立之前先詢問 —
「目前沒有專案記憶。自動記憶功能已經開啟，Claude 會隨著時間累積記憶 — 但你想我現在就用這個程式碼庫的關鍵事實來播種嗎？這樣你下次工作階段一開始就能直接進入狀況。」
如果同意：用未來工作階段可能會浪費時間重新推導的非顯而易見的事實來播種：
- 令人驚訝的限制（並行模型、版本鎖定、非預期的預設值）
- 目前進行中的工作及原因
- 程式碼中非顯而易見的決策
建立 MEMORY.md，以一行一個條目的簡潔索引格式。詳細的筆記放在獨立的主題檔案（例如 architecture.md、constraints.md）— MEMORY.md 保持在 200 行以下，以便容納在工作階段的上下文視窗中。
第五階段 — 設定
檢查 .claude/settings.json 中是否有參考不再存在的腳本或指令的過時鉤子。
識別經常使用的唯讀指令（測試執行器、linter、健康檢查、git log、git diff），這些指令可以安全地允許執行而無需提示。
不要寫入 settings.json — 把它們作為建議提出。指向：
update-config：用於新增權限、環境變數或修正鉤子fewer-permission-prompts：從實際的對話紀錄中發現權限
第六階段 — 壓縮
所有發現都已寫入磁碟。在結束之前，提醒使用者執行 /compact 指令來處理上下文，以便從全新的狀態開始。
總結
列印變更摘要：
## 專案同步完成
**CLAUDE.md**：<變更內容，或「無需變更」>
**技能**：<已更新項目，或「準確」>
**記憶**：<已合併 / 已播種 /「無變更」>
**設定建議**：<建議的允許項目，或「無新增項目」>
**Git 狀態**：<未提交的檔案 + 進行中的工作，一句話>
執行 `git diff` 來檢視檔案變更。