Communitygithub.com

dubbl-a/house-rules

將未管理的儲存庫首次設定為 House 消費者,提議 house.json 清單、供應規則和 CLAUDE.md 骨架,預設為試運行。使用於「bootstrap house」或「adopt house here」。

house-rules 是什麼?

這個名為「Bootstrap」的技能會自動將一個尚未受 House 管理的儲存庫轉變為 House 消費者。它首先探測儲存庫的結構、框架、預設分支和現有規則,然後生成一個包含所有偵測到模組的 `house.json` 提案。預設情況下,它只會以「試運行」模式顯示提案內容而不寫入任何檔案,只有在使用者明確要求 `--apply` 時,才會寫入選定的規則、範本和一個單獨的 `CLAUDE.md.house-skeleton` 骨架檔案。此技能嚴格保護現有檔案:絕不編輯或覆蓋已存在的 `CLAUDE.md`,也絕不會對已有 `house.json` 的儲存庫二次運行。它專為 Claude Code、Cursor、Windsurf 和 Copilot 等 AI 代理設計,提供可預測且安全的自動化初始設定流程。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dubbl-a/house-rules/tree/HEAD/plugins/house/skills/bootstrap

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Bootstrap

Bootstrap 將一個未管理的儲存庫轉變為 House 消費者。它探測儲存庫,提議一個 house.json,並在 --apply 時寫入供應的規則、範本以及一個 CLAUDE.md 骨架。它絕不會編輯現有的 CLAUDE.md,也絕不會對同一個清單運行兩次。它僅將 CLAUDE.md 的 house 部分作為單獨的骨架檔案寫入,而將程式碼庫衍生的部分留給 harness 自己的 init 命令,該命令會生成一個起始的 CLAUDE.md 或對現有的檔案提出改進建議。

此技能會對磁碟產生副作用,因此絕不會自行觸發。僅在被要求時運行。

預設路徑

  1. 試運行:探測儲存庫並列印提議的 house.json。不寫入任何內容。
  2. 向運行此技能的人顯示提案,並等待他們表示要應用它。
  3. 應用:寫入 house.json,然後渲染規則、範本和骨架。
  4. 列印下方的接線區塊,以便使用者可以將其貼入 package.json、CI 和他們的終端機。

請勿跳過步驟 2。使用者從未見過的提案不是提案,而是驚喜。

當清單已存在時拒絕

在探測任何內容之前,請檢查 house.json 是否已存在於儲存庫根目錄。

如果存在,則拒絕。列印該儲存庫已有清單,並引導至 /house-rules:sync。即使在試運行模式下也是如此:bootstrap 絕不會在第一個提案之上起草第二個提案,即使第一個提案尚未被應用。一個儲存庫只會有一次 bootstrap。

探測儲存庫

以試運行模式執行 CLI 以收集提案所需的資訊:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house init --repo <path>

探測過程會讀取(但不會寫入):

  • 堆疊:package.json 是否存在、其腳本,以及根目錄下任何框架的設定檔。
  • 預設分支:git symbolic-ref refs/remotes/origin/HEAD,若失敗則回退到目前分支。
  • 頂層目錄,以猜測哪些可選模組適用(db/ 暗示 database,部署設定暗示 deployment,以此類推)。
  • .claude/rules/ 或分支守護鉤子是否已存在,以便提案可以說明 bootstrap 會新增什麼,以及儲存庫已有什麼。
  • 儲存庫目前的文件掃描是否已排除封存層,以便根據觀察到的行為(而非猜測)來設定 scanArchive。
  • git check-ignore 是否指出任何 house 寫入目標(.claude/rules/house/、.house/)被忽略。檢查器會遍歷 git ls-files,因此被忽略的規則檔案對它是不可見的,而第一次運行會列印一個它從未賺取到的零。探測器會發出警告並指出修正方法:僅忽略 .claude/settings.local.json,絕不忽略 .claude/ 或 .house/。

提議 house.json

探測器無法排除的每個模組都會以 "detect" 而非 true 或 false 加入提案。"detect" 意味著儲存庫在渲染時決定,而不是技能替它猜測。核心模組(docs、engineering、github、claude-code)始終啟用。請列印完整的提議 house.json 主體,而非摘要,以便審查的人在被寫入任何內容前可以閱讀每個欄位。

應用:寫入清單、規則和骨架

僅在使用者表示要應用之後:

node ${CLAUDE_PLUGIN_ROOT}/scripts/house init --repo <path> --apply
node ${CLAUDE_PLUGIN_ROOT}/scripts/house render --repo <path> --apply

init --apply 寫入 house.json。render --apply 寫入供應的規則檔案、範本、.house/check.mjs、.house/lock.json、.house/INDEX.md,以及一個更多檔案:

  • 如果儲存庫有 CLAUDE.md,則在其旁邊寫入 CLAUDE.md.house-skeleton。請勿開啟現有的 CLAUDE.md,也請勿寫入其中。
  • 如果儲存庫沒有 CLAUDE.md,仍然寫入 CLAUDE.md.house-skeleton,而非 CLAUDE.md 本身。Bootstrap 絕不會產生儲存庫的根檔案。使用者需手動將骨架合併進去。

無論哪種情況,現有的 CLAUDE.md 在每次 bootstrap 運行前後都應是字節完全相同的。這是此技能被要求的控制項:在應用前比較差異,應用後再次比較,如果有任何變動,則停止並報告而非報告成功。

骨架每個儲存庫僅提供一次:render 將其記錄在 .house/lock.json 的 scaffolds 下,因此一旦它被合併到 CLAUDE.md 並刪除後,後續的渲染不會再寫入它。render --apply --scaffold 是再次請求它的方式。

確保儲存庫的 .gitignore 包含 .claude/worktrees/ 和 .superpowers/,並附加缺少的那一行。出現在 git status 中的工具暫存檔,一個 git add -A 就可能被提交。

列印接線資訊

成功應用後,逐字列印以下區塊,使其可以複製貼上到一個純文字終端機中。請勿填寫任何內容;使用者會自行將其調整到他們的 package.json 和工作流程檔案中。

Add to package.json scripts:
  "check:docs": "node .house/check.mjs --only=drift,todo"
  "check:house": "node .house/check.mjs"

Add a CI step that runs:
  node .house/check.mjs

Install the plugin once per machine:
  claude plugin marketplace add dubbl-a/house-rules
  claude plugin install house-rules@house-rules --scope user

Arm the git hooks once per clone (render --apply and every session start also do this):
  git config core.hooksPath "$(pwd)/.githooks"

core.hooksPath 存在於 .git/config 中,沒有任何 clone 或 PR 會攜帶它,因此供應的 .githooks/ 樹在全新的檢出中是不活動的,直到有東西設定它。render --apply 和插件的 SessionStart hook 都會啟用它;上面的行是為了那些兩者都沒有的 clone。它們和使用者都不應覆寫另一個工具已擁有的 core.hooksPath。

如果儲存庫沒有 .claude/settings.local.json,請在列印的輸出中說明。該檔案是儲存庫層級選擇退出某個 house 模組或鉤子的地方,其不存在意味著該儲存庫僅使用預設值運行。

Bootstrap 之後

告知使用者尚未完成的事項:骨架仍需手動合併到 CLAUDE.md 然後刪除(它不會再被寫入),接線區塊仍需貼上,並且在首次提交前值得在本機運行 node .house/check.mjs,以便儲存庫從一個乾淨的關卡開始,而非繼承的失敗。請按路徑暫存渲染的檔案(house.json .house/ .claude/rules/house/,加上僅當 render 在該路徑下列出檔案時的 scripts/house/,因為 git 會拒絕與任何內容都不匹配的路徑規格):在它們被暫存之前,清單系列會為每個檔案警告 [untracked],而整體的 .claude/ 或 .house/ 忽略則是一個 [gitignored] 的發現,因為 git 看不到的檔案就是沒有系列會檢查的檔案。這些都不是此技能的工作;bootstrap 在渲染後就停止了。

禁止事項

  • 請勿在試運行期間寫入 house.json 或任何渲染的檔案。試運行僅列印。
  • 請勿在任何旗標下覆寫或附加到現有的 CLAUDE.md。
  • 請勿對已存在 house.json 的儲存庫重新提議。請引導至 /house-rules:sync。
  • 當探測結果不明確時,請勿猜測模組是開啟或關閉。提議 "detect" 並讓儲存庫決定。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

相關技能