House sync 是做什麼的?
將儲存庫中供應商提供的 house 規則檔案更新至已安裝外掛程式的最新版本,同時永遠不無聲丟棄本地編輯。僅能透過 /house-rules:sync 呼叫此技能。它不是查詢技能,且會寫入檔案,因此絕不會因關於慣例的一般性問題而觸發(請使用 /house-rules:conventions 處理該情況)。
此技能驅動的 CLI:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house <init|render|check> [--repo <path>] [--apply] [--force-managed <path>]
--repo 預設為目前目錄。除了 init、render、check 之外,不會發明任何子命令。
預設路徑:規劃,然後套用
每次同步都只遵循一個預設路徑。每次請依此順序執行。
1. 確認儲存庫已採用 house
讀取儲存庫根目錄的 house.json。缺少 house.json 表示此儲存庫從未初始化:請停止並告知使用者先執行 /house-rules:bootstrap。不要將缺少清單視為「沒有要同步的內容」。
2. 規劃(dry run)
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path>
未使用 --apply 時,這僅是規劃。它會讀取 .house/lock.json(每個條目包含 path、module、source、bodySha256),並比較磁碟上每個受管檔案的目前內容雜湊與鎖定檔中的記錄,然後與新呈現的內容進行比較。將每個受管檔案精確分類到一個類別中:
- 乾淨。 磁碟上的雜湊與鎖定檔相符。規劃:用新呈現的內容覆寫。
- 遺失。 檔案不存在於磁碟上。規劃:還原它。
- 本地修改。 磁碟上的雜湊與鎖定檔或呈現的 no-op 都不相符。規劃:拒絕。請參閱下方的三個出口。
在執行任何其他操作之前,先列印規劃。即使對於乾淨或遺失的檔案,也請勿在此步驟中套用任何內容。
3. 本地修改:三個出口,絕非無聲選擇
本地修改的受管檔案不會被合併、覆寫或靜默保留。列印磁碟上的檔案與 house 會呈現的內容之間的差異,然後精確列印這三個出口,依此順序,並針對該檔案停止(在 --apply 下它也不會被觸碰,僅是從寫入作業中排除):
- 上游優先。 針對 house 套件儲存庫本身(
dubbl-a/house-rules)開啟一個 PR,攜帶預期的變更,使該編輯成為所有人的新 house 規則,而不是一個私有分支。這是首選出口。 - 記錄偏差並取消管理。 在
house.json的deviations陣列中新增一個條目,並附上why,將該檔案從受管集合中移除,並將其鏡像到儲存庫的CLAUDE.md中的## Deviations from house章節。當編輯確實是儲存庫特定的,且永遠不會提交到上游時使用。 - 強制覆寫。 執行:
僅在確認本地編輯是可丟棄的時使用,絕不將其作為預設選項,因為它是最快的。在執行前要求使用者確認;絕不要在未經提示的情況下自行選擇。node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --force-managed <path>
不提供第四個選項,也不要將其變成一個等待選擇的互動式選單。將三個出口陳述為執行的結果,然後讓使用者(或此技能的後續呼叫)對其中一個採取行動。
4. 套用
一旦乾淨和遺失的檔案被處理完畢,且每個本地修改的檔案都已路由到三個出口之一(或故意保持拒絕狀態),即可套用:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply
這會寫入乾淨和遺失的檔案。它永遠不會寫入仍被拒絕的本地修改檔案;--force-managed 是唯一能做到這一點的路徑,且僅針對指定的單一路徑。
如果 render 列印了 warning: ... is git-ignored 行,請先停下來修正忽略規則再繼續:Git 看不見的目的地永遠無法送達檢查程式或 CI。僅忽略 .claude/settings.local.json,絕不忽略 .claude/ 或 .house/。
如果 render 或檢查程式列印了 warning: module is not in house.json, but <dir>/ exists here,表示在此儲存庫的 house.json 撰寫之後發布了一個模組,且其規則在儲存庫於 modules 下加入 "<name>": {"enabled": true} 之前不會被供應商提供。不要自己新增該鍵:將警告行逐字複製到同步 PR 的主體中,並位於一行說新模組適用於此儲存庫且需要採用者選擇的文字之下。
4b. 按路徑暫存 render 寫入的內容
git add house.json .house/ .claude/rules/house/
僅在 render 規劃列出了 scripts/house/ 中的檔案時,才將該路徑加入命令;否則,當任何路徑規格不符時,Git 會拒絕整個命令。使用明確的路徑,永遠不要使用 git add -A:檢查程式和 CI 會讀取 git ls-files,因此未暫存的呈現檔案是無人檢查的,而 blanket add 會掃入樹中任何其他存在的內容。
Render 的 Scaffolded 清單(.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/pr-checks.yml、CLAUDE.md 骨架)不是受管檔案,因此 [untracked] 警告無法看到它們:請檢閱這些檔案,然後也按路徑暫存它們。
每個儲存庫只提供一次 Scaffold,而不是每次 render 提供一次。鎖定檔的 scaffolds 清單記錄了此儲存庫已經被給予哪些範本;已記錄的範本永遠不會被再次寫入,無論其檔案是否仍在磁碟上。因此,被合併到 CLAUDE.md 中並被刪除的 CLAUDE.md.house-skeleton 將保持刪除狀態,且重新同步不需要使用 rm 刪除它。如果儲存庫想要恢復某個 Scaffold,render --apply --scaffold 會寫入任何遺失的 Scaffold,且仍然永遠不會覆寫已有的檔案。預計 scaffolds 鍵會在 0.2.3 或更高版本上的首次同步時出現在鎖定檔差異中;它是一個記錄,而不是一個雜湊,且沒有任何東西會拒絕它。
4c. Git 忽略工具暫存檔案
確保儲存庫的 .gitignore 包含 .claude/worktrees/ 和 .superpowers/,並附加任何遺失的行。出現在 git status 中的工具暫存檔案距離被 git add -A 提交只有一步之遙。
5. 確認 pin 版本
確認 house.json 現在包含已載入的外掛程式版本;render 會寫入它,永遠不要手動編輯。render --apply 會將 version 欄位設定為以下檔案中的外掛程式版本:
${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json
永遠不要讀取 installed_plugins.json 來檢查此項。它記錄跨儲存庫的安裝狀態,且可能落後或與目前載入的內容不同;CLAUDE_PLUGIN_ROOT 下的 plugin.json 是實際執行此同步的版本。
6. 使用供應商的檢查程式驗證
以 CI 和 prebuild 實際執行的方式執行檢查程式,而不是外掛程式自己的副本:
node .house/check.mjs
node ${CLAUDE_PLUGIN_ROOT}/scripts/house check --repo <path> 會針對外掛程式自己的 payload 執行相同的邏輯,並且在 .house/check.mjs 被供應商提供到儲存庫之前(首次同步)很有用。一旦供應商的副本存在,直接執行它可以證明實際發送的檔案是通過檢查的檔案,而不是一個看起來相同的副本。
此處的 [untracked] 警告表示步驟 4b 跳過了該檔案;請暫存它並重新執行。[gitignored] 結果表示步驟 4 中的忽略規則仍然吞噬了一個受管檔案。
7. 列印 doctor 輸出
在檢查執行後,執行 doctor 並報告其輸出:
node ${CLAUDE_PLUGIN_ROOT}/scripts/house doctor --repo <path>
每行列印的含義(標籤與 doctor 列印的相同):
effective branch guard: plugin | repo | NONE。NONE:沒有house.json也沒有儲存庫本地的鉤子。目前沒有任何東西在保護對受保護分支的直接提交。repo:存在儲存庫本地的.claude/hooks/no-direct-master.sh檔案,或.claude/settings.json包含hooks區塊。遷移期間儲存庫鉤子優先;外掛程式鉤子會讓步並以退出碼 0 退出。plugin:house.json存在且沒有儲存庫本地鉤子訊號。外掛程式鉤子是實際執行branchPolicy和protectedBranches的那個。當house.json包含guard記錄時,它會列印為plugin (recorded <date>),而當不包含時則列印為plugin (unrecorded);這僅關係到檢查程式的guard警告是否被清除:無論如何,鉤子都執行相同的強制。
git-hook floor: ...。 供應商的.githooks/樹是否實際連接到此克隆中的 Git。core.hooksPath存在於.git/config中,因此它是機器狀態,任何克隆、render 或 PR 都無法攜帶;檢查程式永遠不會讀取它(ADR 0008 將檢查程式限制為僅儲存庫),而 doctor 是報告它的地方。armed (core.hooksPath=<path>, <scope>):Git 在此處執行 floor。無需採取任何動作。NOT armed -- core.hooksPath is unset in this clone:floor 已呈現但處於非活躍狀態。house render --apply會啟用它,並且在安裝了外掛程式的儲存庫中啟動一個 session 也會啟用它。NOT armed -- core.hooksPath is <other>:另一個工具(husky、lefthook、monorepo 慣例)擁有此儲存庫唯一的 hooksPath。House 永遠不會覆寫它。從那裡的鉤子鏈接 floor,或取消設置並重新執行 render。not rendered here (missing: <paths>):七個 floor 檔案中至少有一個缺失,且該行列出了哪些。全部七個缺失僅僅是一個尚未呈現 floor 的儲存庫。缺失一個比看起來更糟:每個 guard 都會引用.githooks/house-lib.sh,並在該引用失敗時以非零退出碼退出,因此一個僅缺少程式庫的 floor 會導致每次提交關閉時失敗,而不是失敗時保持開放。任一情況,請執行 render。not applicable:此根目錄沒有house.json,或branchPolicy不是pr。- 縮排的後續行報告了會使 floor 靜默而非保護的原因。
foreign hooks in this clone's .git/hooks:拒絕啟用,因為core.hooksPath會完全取代.git/hooks並靜默禁用它們。not executable:Git 會靜默忽略沒有執行位元的鉤子,因此遺失的模式是失敗時保持開放;render 會恢復它(僅為能夠讀取該檔案的類別新增位元,因此一個故意設為 0600 的鉤子會以 0700 返回,且永遠不會被擴展)。reference-transaction: supported by git <version> (>= 2.28)或inert on git <version> (needs 2.28):在 2.28 及更新版本上,floor 有一個無法關閉的成員,而 inert 行是一個真正的差距,而不是一個修飾問題。低於 2.28 時,--no-verify會跳過pre-commit和pre-push,且沒有其他東西可以捕捉它,因此在該 Git 版本上,該標誌僅被 session-time PreToolUse 鉤子拒絕,而當沒有 session 在循環中時,該鉤子就不存在。將此行視為升級 Git 的提示,而不是一個備註。
jq on PATH: yes | no。 鉤子在沒有它的情況下仍然會拒絕(手寫的拒絕 JSON),但請報告差距以便修復。pin vX matches plugin vY|pin vX differs from installed plugin vY。house.json的version與外掛程式自己的plugin.json進行比較,與步驟 5 相同。differs表示 pin 版本提升尚未生效或已被跳過。npm wiring (.house/check.mjs referenced by): <scripts> | none found。 期望一個呼叫.house/check.mjs --only=drift,todo的check:docs(或等效的輕量級)腳本,以及一個呼叫完整.house/check.mjs的check:house腳本。如果任一腳本缺失,請列印可複製貼上的片段,而不是直接編輯package.json:"check:docs": "node .house/check.mjs --only=drift,todo" "check:house": "node .house/check.mjs"rule-load positive control: ...。 是否已接線一個InstructionsLoaded鉤子,以及它自己的日誌實際見證了什麼;如果沒有,一個其 glob 永遠不匹配的規則看起來就像一個什麼都不做的規則。repo (.claude/settings.json):儲存庫宣告了自己的鉤子。plugin hook; log <path>: last load <ts>, <n> of <m> vendored rules seen:外掛程式自己的鉤子已接線且已記錄至少一次載入,並附有實際載入的供應商規則檔案數量的真實計數。當<n>少於<m>時,該行會以; not seen in this log: <names>繼續,列出日誌中沒有載入記錄的每個供應商規則,因為僅靠計數只能說明有問題,而無法指出要打開哪個檔案。將該清單視為線索而非結論:日誌會自我修剪,因此一個規則可能僅在很久以前載入後出現在那裡,而誠實的下一步是打開規則的paths:所聲稱的檔案並重新執行 doctor。一個在該操作後仍然存在的名稱,表示其規則的範圍未觸及其所針對的檔案。plugin hook declared; no log yet for this checkout:外掛程式的鉤子已接線,但尚未在此處記錄任何內容 -- 在此儲存庫中啟動一個 session 並重新執行 doctor。none wired:沒有東西宣告該鉤子。git-ignored house destinations: none | <paths>。 除了none之外的任何內容都是檢查程式無法看到的目的地;請像步驟 4 中那樣修復忽略規則。
8. 路由儲存庫無法修復的上游問題,每個項目一個 issue
同步或合規通過通常會發現只有套件才能處理的結果和警告:檢查程式差距、針對此處不存在之檔案的規則錨點名稱、儲存庫需要但結構描述缺少的配置插槽。對於每個此類項目,可以在同一個 session 中(針對套件儲存庫建立分支和 PR,與步驟 3 中相同的上游優先出口)在上游修復它,或者在套件儲存庫中為每個可操作項目提交一個 issue,其規模要小到可以透過單一變更來關閉。
永遠不要將它們批次處理成一個多項目的摘要 issue:摘要 issue 無法在其最慢的項目完成前關閉,其項目無法獨立設定優先級,且部分解決的摘要會不斷累積。僅將此儲存庫可以修復的內容保留在此儲存庫中。
逃生口
這些是在上述預設路徑中內聯出現的例外情況,而不是一個可以事先選擇的獨立選單:
- 沒有
house.json:在步驟 1 停止,指向/house-rules:bootstrap。 - 本地修改的檔案:步驟 3 中的三個出口。
- 確認可丟棄的本地編輯:
--force-managed <path>,僅在詢問後使用。 - 儲存庫中的首次同步,
.house/check.mjs尚未被供應商提供:在步驟 6 中使用house check --repo <path>而不是供應商的路徑,並請注意這是一次性的替代,而不是穩定狀態。
禁止事項
- 不要合併本地修改
…
[為翻譯而截斷]