@routerhub/agent-rules

给项目生成一套 AI 协作规则文件，让 Claude Code / Cursor / GitHub Copilot 在项目里都按同一套规则干活。

它能干什么

安装后自动生成/同步：

| 层级 | 文件 | 说明 | |---|---|---| | 个人级 | CLAUDE.md / AGENTS.md | 本机 AI 自动读取，默认停用（见下「按人启停」） | | 团队级 | .github/copilot-instructions.md、.github/instructions/*、PULL_REQUEST_TEMPLATE.md、skills | 随仓库入库，始终生成，不受个人启停影响 |

怎么用

在项目里安装，装完自动初始化生成规则文件：

pnpm i -D @routerhub/agent-rules

常用命令：

| 命令 | 作用 | |---|---| | pnpm exec agent-rules init | 初始化 / 生成规则文件 | | pnpm exec agent-rules sync | 改完规则后手动同步一次 | | pnpm exec agent-rules watch | 监听，改规则后自动重新生成（前台进程，只监听启动时所在的目录） | | pnpm exec agent-rules doctor | 体检：输出文件有没有跟上 AGENTS.private.md、watch 有没有在跑、git 钩子装了没（有待处理项时退出码 1） | | pnpm exec agent-rules hook | 安装/升级 git post-checkout 钩子（新建 worktree 后自动补生成个人级文件） | | pnpm update @routerhub/agent-rules --latest | 升级规则包到最新版 |

项目私有规则写在仓库根 AGENTS.private.md（没有会自动建模板）；公共规则在 agent-rules 仓库维护，别写进业务项目。

改完 AGENTS.private.md 没自动同步？

自动同步不是后台常驻功能，它只在 agent-rules watch 这个前台进程运行时生效，而且只监听启动时所在的那个目录——换了目录、新建 worktree、或关掉那个终端，就没人同步了（这是最容易踩的坑）。

不确定当前目录同步状态时，跑一次体检：

pnpm exec agent-rules doctor

它会逐项告诉你：个人级文件是否启用、各产物是否落后于 AGENTS.private.md、本目录有没有 watch 在跑、git 钩子装没装。

新建 worktree 后个人级文件是空的？

CLAUDE.md / AGENTS.md 不入库，git 不会把它们 checkout 到新工作树里——所以每个新 worktree 里都是缺的。安装依赖时（pnpm i）会自动装一个 git post-checkout 钩子，在 checkout（含 git worktree add）之后自动补齐。

• 手动装/升级：pnpm exec agent-rules hook
• 不看医生也知道装在哪：git rev-parse --path-format=absolute --git-path hooks（装进 <repo>/.git/hooks 不一定生效——core.hooksPath 被 husky 或全局配置改过时，git 只认那个目录）
• 关闭：export AGENT_RULES_NO_HOOK=1
• 判断依据是内容比对，不是文件时间：每次同步会把 AGENTS.private.md 的内容快照存到 <repo>/.git/agent-rules/private.snapshot，钩子只是拿它和当前内容逐字节比（快照在 .git 里，同一仓库的所有 worktree 共用一份）。所以「只 touch 没改内容」不会触发同步，「改了内容」一定会触发；快照被删（从老版本升级上来）时首次 checkout 会自动重建。

按人启停（默认停用）

个人级 CLAUDE.md / AGENTS.md 只给命中白名单的人生成。白名单在包内 enabled-users.json，管理员维护；判断用本机 git 身份：

git config user.name
git config user.email

name 或 email 包含白名单里任一字符串即启用；不在名单的人默认不生成（团队级规则照常生效）。

• 想启用：把上面的身份告诉管理员加白名单发版；想立即试用：AGENT_RULES_ENABLED=1 pnpm exec agent-rules init
• 想停用：AGENT_RULES_ENABLED=0 pnpm exec agent-rules init（只删 agent-rules 生成的个人文件，不碰你写的内容）