Communitygithub.com

dubbl-a/house-rules

为仓库首次设置 House 规则,生成 house.json 清单、内联规则和 CLAUDE.md 骨架,默认仅进行试运行。用于“初始化 house”或“在此采用 house”。

house-rules 是什么?

这是一个用于将未管理仓库转变为 House 规则消费者的 AI 技能。它通过探测仓库内容,生成并提议一个 `house.json` 清单,并在用户确认后写入内联规则、模板以及一个独立的 CLAUDE.md 骨架文件。该技能的核心设计原则是安全性和用户控制:它永远不会修改现有的 CLAUDE.md,也绝不会对同一清单执行两次;它只在用户明确要求 (`--apply`) 时才执行写入操作,并且如果 `house.json` 已存在则会拒绝执行。技能支持所有基于 AI agent 的终端和 IDE 平台(如 Claude Code, Cursor, Codex),通过分析项目目录结构、依赖和配置文件来生成个性化提议,并输出用于集成到 `package.json` 和 CI 流程的配置代码块。

兼容平台✓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 的一半,作为单独的骨架文件,而将另一部分留给平台自身的 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 和工作流文件进行调整。

添加到 package.json 脚本中:
  "check:docs": "node .house/check.mjs --only=drift,todo"
  "check:house": "node .house/check.mjs"

添加一个执行以下操作的 CI 步骤:
  node .house/check.mjs

每台机器安装一次插件:
  claude plugin marketplace add dubbl-a/house-rules
  claude plugin install house-rules@house-rules --scope user

每个克隆库启用一次 git 钩子(render --apply 和每次会话启动时也会执行此操作):
  git config core.hooksPath "$(pwd)/.githooks"

core.hooksPath 位于 .git/config 中,任何克隆或 PR 都不会携带该配置,因此内联的 .githooks/ 目录在全新的检出中是无效的,直到某些内容设置了它。render --apply 和插件的 SessionStart 钩子都会启用它;上面的行适用于没有这两者的克隆库。这行命令或操作者都不应覆盖其他工具已拥有的 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.

相关技能