Communitygithub.com

dubbl-a/house-rules

將會話的學習內容路由到對應的規則檔案,並將帶有日期的紀錄歸檔到儲存庫的存檔層級,永遠不寫入根指令檔案;當收到「修訂文件」、「記錄此經驗」、「這該放哪」等指令時觸發。

house-rules 是什麼?

此技能專為修正官方指令檔案管理外掛中 `revise` 指令的缺點而設計。官方外掛會將學習內容直接附加到根指令檔案,導致檔案過於龐大而失去可讀性,且學習記錄難以為後續工作階段所用。本技能保留了該外掛中對宣稱進行程式碼審計的優點,但將「附加」改為「路由」:分類學習內容為「規則」或「事件」,規則路由到範圍匹配的規則檔案,事件則歸檔到儲存庫的存檔層。支援 Claude Code 等 AI 編碼代理平台,透過特定觸發詞如「修訂文件」(revise the docs)啟動。它強制使用者在寫入前先驗證所有錨點(Anchor)、路徑、腳本名稱是否確實存在於當前程式碼庫中,避免寫入未經檢查的宣稱。此外,若目標檔案是受管理的廠商規則檔案(位於 `.claude/rules/house/**`),則不直接編輯,而是建議向上游提案修改,以確保同步一致性。

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

在你喜歡的 AI 中提問

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

說明文件

修訂文件

官方指令檔案管理外掛的修訂指令會將會話的學習內容附加到根指令檔案中。本技能存在的目的正是取代這種行為。只會增長的根指令檔案最終不會被讀完,而且附加在上面的學習內容,很少會是未來工作階段在需要它時所尋找的關鍵事實。本技能保留了該外掛中有用的部分——在寫入前先對宣稱進行程式碼審計——並捨棄了附加部分,改用路由機制。由於框架自身的機器本地記憶體筆記已經記錄了會話學到的內容,並跳過指令檔案中已提及的部分,因此本技能負責路由的是可分享、需簽入的部分:將規則送到與其觸及範圍匹配的規則檔案,將事件送到儲存庫的存檔層。

預設流程

  1. 為本次會話所產生的值得保留的內容命名:一個修正、一項約定的慣例、一個錯誤及其修復、一個測量結果、兩個方法之間的取捨。
  2. 將其分類為規則或事件。
    • 規則在任何符合情境重現時都適用。只需陳述一次,且在下一次重構後仍應成立。
    • 事件只發生過一次,附有日期、名稱或測量數字。它是規則存在的原因,而不是規則本身。
  3. 將規則路由到匹配的規則檔案。
    • 根據作用域和標題搜尋現有規則檔案,而不僅僅是依賴檔名。開啟其 paths: 已涵蓋該學習內容觸及範圍的檔案。
    • 如果該檔案已涵蓋,則新增一個標題或將要點納入現有標題。遵循規則的格式:一個祈使句形式的標題(本身就是規則)、一條理由、一個 Anchor: 行(標明強制執行此規則的依據)、一個 Receipts: 行(指向存檔條目),並確保檔案以 ## 不要做 結尾。
    • 寫入前先驗證。檢查 Anchor: 行中的每個標記、每個路徑、每個腳本名稱,是否確實存在於此時的程式碼庫中。這正是從上述外掛繼承而來的審計習慣:絕不寫入未經檢查的宣稱。
    • 如果沒有任何檔案涵蓋,則說明情況,並建議建立一個新的規則檔案或擴大現有檔案的作用域。不要僅僅因為接近就將要點塞進最近的檔案。
  4. 將事件路由到儲存庫的存檔層。
    • 存檔層是儲存庫用來儲存帶日期證據的文件:手冊章節、設計歷史檔案、事後檢討紀錄。將日期、名稱、測量數字寫入該處,標題設為一行總結,使條目讀起來像一個宣稱,而不是一個檔案名稱。
    • 讓規則檔案使用帶引號的標題指向該條目。不要在規則內文中重述事件的具體細節;日期或數字出現在規則中,就像是穿著規則外衣的歷史記錄。
    • 如果儲存庫尚無存檔層,則說明情況,並建議建立一個。不要因為沒有合適位置而將事件塞入規則檔案或根指令檔案中。
  5. 永遠不要觸碰根指令檔案。如果規則檔案和存檔層都不適合,這表示該事實還不值得保留,而不是將其預設放入根指令檔案的理由。直接清楚地說明並停止。
  6. 在儲存編輯內容前先顯示。列印您建議的標題和段落,或顯示與現有檔案的差異,並等待確認,除非您被明確告知可以直接進行更改。

當匹配項目是受管理的規則(Managed House Rule)

如果已涵蓋該主題的檔案是受管理的規則(帶有 managed-file 標頭,位於 .claude/rules/house/**),請勿在此儲存庫中編輯它。對受管理檔案的本機編輯會在下一次 /house-rules:sync 執行時被靜默覆寫,而這種靜默丟失正是 House 機制所要防止的情況。

請改為向上游提案更改。起草相同的標題和段落,然後說明應將其作為對 House 儲存庫的更改來提交,而非此儲存庫。如果該要點確實是此儲存庫特有,而非適用於所有儲存庫的規則,則在 house.json 中記錄為偏離項,而不是 Fork 該受管理的檔案。這兩種路徑都能保持受管理檔案同步;直接原地編輯則無法做到。

例外處理

  • 學習內容與既有規則衝突。 直接說明情況,引用既有規則的標題,並詢問哪個規則優先,然後再寫入任何內容。不要靜默地用一條新規則覆寫另一條。
  • 學習內容是儲存庫特有的一次性事項,不具有規則形式,例如針對供應商錯誤的解決方案,或僅需注意一次的備註。將其作為事件路由到存檔層,而不是用未來工作階段無需遵守的內容來弄亂規則檔案。
  • 不確定某內容是規則還是事件。 傾向於歸檔。一個錯誤歸檔的規則,未來有人可以將其提升為標題;一個錯誤歸類為規則的事件,則會變成無人提醒的陳舊文字。
  • 儲存庫中既沒有規則檔案也沒有存檔層。 直接說明情況並停止,而不是從此技能內部建立其中之一。那是 /house-rules:bootstrap 的職責,而非此技能。

不要做

  • 不要附加到根指令檔案。那正是官方指令檔案外掛的修訂指令所做的事,也是此技能存在的原因。
  • 不要寫入一條其錨點(Anchor)尚未在程式碼庫中檢查過的規則陳述。
  • 不要在規則內文中重述事件的日期、名稱或數字;請指向存檔層。
  • 不要原地編輯受管理的規則檔案。請向上游提案或記錄偏離項。
  • 不要儲存使用者尚未看過的編輯內容,除非他們明確告訴您可以直接進行更改。
  • 當儲存庫中既沒有規則檔案也沒有存檔層時,不要自行建立。

Individual skills in this repo

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

相關技能