ai-rulebook

一份规则源，自动生成 CLAUDE.md / AGENTS.md / Copilot 指令 —— 让仓库里的 AI 助手按同一套工程纪律干活。

你大概率遇到过这些事

• 让 AI 修个 bug，它没复现就动手改了，改完说「已修复」，可你根本不知道原来到底有没有这个问题；
• 让 AI 改个后端接口，它把 provider_accounts 顺手删了几行，因为它觉得「反正是一起的」；
• 让 AI 部署到测试环境，它把 localhost:3000 的截图当成证据发给你，你在自己电脑上根本打不开；
• 换个新仓库开新会话，同样的要求又得从头交代一遍，而它上次明明答应过；
• 团队里三个人用 Claude Code、两个人用 Copilot，每个人手里的「规矩」都不一样，代码风格随人走。

根本原因不是模型不行 —— 是你没有一套写下来的、它能读到、且每次都会遵守的规则。

ai-rulebook 做什么

把工程纪律写成一份源文件 AGENTS.base.md，然后：

AGENTS.base.md  ──┐
                  ├──►  ai-rulebook sync  ──►  CLAUDE.md                    （Claude Code 自动读）
AGENTS.private.md ┘                     ──►  AGENTS.md                    （Cursor / Claude Code 自动读）
                                        ──►  .github/copilot-instructions.md   （VS Code Copilot 自动读）
                                        ──►  .github/instructions/*.md         （按文件类型条件加载）
                                        ──►  .claude/skills/*                  （Claude Code 技能，按需调用）

改规则只改一处，所有 AI 工具的规则文件同时更新，不会出现「CLAUDE.md 改了、Copilot 那边还是老的」。

自带的规则集里有什么

不是空壳模板，是一套真在多个生产仓库跑过的工程纪律。举几条：

| 规则 | 拦住的事 | |---|---| | 缺陷复现铁律 | 不许「照着描述直接改」。必须先在改动前的代码上复现、截图留证，再动手 | | 数据库 DELETE 铁律 | 每条 DELETE 都要在注释里回答「删什么/为什么在这删/最多影响几行」，副作用范围必须 ≤ 用户意图范围 | | 可部署性自包含铁律 | 建表、迁移、初始化数据一律内嵌部署脚本，上线只跑一个脚本，禁止「代码完成、部署待办」 | | 验收环境铁律 | 证据必须来自别人能打开的环境。localhost 的截图不算证据 | | 取证报告铁律 | 除了证明「该变的变了」，还得证明「不该动的一行没动」 | | 反模式清单（11 条） | 缓存失效没恢复展开态、白名单查询的 OR 分支绕过了守卫、2xx 就当成功…… 每条都有真实事故出处 | | 上线安全六环 | 环境对账 → 脚本自检 → 回滚演练 → 先下不发 → 渐进切流 → 观测窗口 | | 审稿边界 | 明确告诉 AI reviewer「什么必须报、什么不许报」，这是让循环 review 能收敛的关键 |

完整清单见 AGENTS.base.md。不喜欢某条？直接删 —— 它就是你自己的文件。

快速开始

# 在任意 git 仓库根目录执行
npx ai-rulebook init

跑完你会得到：

你的仓库/
├── AGENTS.private.md                    ← 新建，写本项目专属规则（初始是模板）
├── CLAUDE.md                            ← 个人级，不入库
├── AGENTS.md                            ← 个人级，不入库
└── .github/
    ├── copilot-instructions.md          ← 团队级，入库
    ├── instructions/
    │   ├── frontend.instructions.md     ← 只在改前端文件时加载
    │   ├── go-backend.instructions.md
    │   ├── devops.instructions.md
    │   └── review-boundary.instructions.md
    └── PULL_REQUEST_TEMPLATE.md
└── .claude/skills/                      ← 13 个技能：建 PR / 部署 / 写文档 / 复现报告…

改完 AGENTS.base.md 或 AGENTS.private.md 后：

npx ai-rulebook sync     # 重新生成全部输出文件
npx ai-rulebook watch    # 或者挂个监听，改完自动同步

按域加载：别让改 CSS 的会话读计费规则

.github/instructions/*.instructions.md 带 applyTo 前置声明，Copilot 只在编辑匹配的文件时才加载：

---
name: "前端规则"
applyTo: ["**/*.ts","**/*.tsx","**/*.vue","**/*.css"]
outputName: "frontend"
---

在 AGENTS.base.md 里用一行标记划定域边界：

<!-- @domain: frontend -->

## 前端规则
...（这一整节只会进 frontend.instructions.md）

不标域的章节归到 global.md，进全局规则。

个人级 vs 团队级

| | 文件 | 是否入库 | 说明 | |---|---|---|---| | 个人级 | CLAUDE.md、AGENTS.md | ❌ 不入库（.gitignore） | 你本机 AI 自动读的规则。默认对所有人生成，装上即用，零配置 | | 团队级 | .github/*、.claude/skills/* | ✅ 入库 | 团队共享 / 云端 PR review 用，始终生成 |

想只让部分人生成个人级文件（比如公司统一采购、只授权给特定账号）？在包里放 enabled-users.json 写名单，本机 git config user.name / user.email 命中任一字符串才生成：

["[email protected]", "bob"]

不配这个文件 = 对所有人启用。

自定义

加项目专属规则 —— 编辑 AGENTS.private.md，会合并进所有输出文件（git remote 会自动填进去）。

改输出路径 / 关掉某个产物 —— 在仓库根目录放 ai-rulebook.config.json：

{
  "claudeOutput": "docs/CLAUDE.md",
  "skillsSrc": "tools/my-skills"
}

换掉整套规则 —— AGENTS.base.md 就是普通 Markdown，你想全部重写、或者只留几条，都行。

命令

| 命令 | 作用 | |---|---| | ai-rulebook init | 初始化规则文件，缺失时创建 AGENTS.private.md 模板 | | ai-rulebook sync | 重新生成全部输出文件 | | ai-rulebook watch | 监听 AGENTS.private.md，变更后自动同步 | | ai-rulebook doctor | 体检：输出是否与源一致、watch 是否在跑、钩子是否已装（exit 1 = 有待处理项） | | ai-rulebook hook | 安装 git post-checkout 钩子（新建 worktree 后自动补同步） | | ai-rulebook update | 升级到最新版并重新生成 |

常见问题

Q：它会不会覆盖我已有的 CLAUDE.md？

会。CLAUDE.md / AGENTS.md 是生成物，每次 sync 整个重写。你手写的内容请挪进 AGENTS.private.md —— 那才是给人编辑的文件。

Q：AGENTS.base.md 里那些 ⚠️ 是干嘛的？

是给 AI 看的强调标记。规则文件很长，AI 在上下文被压缩后容易漏掉后面的条目，⚠️ 是给它的提醒锚点。

Q：能只用生成器、不要自带规则吗？

能。把 AGENTS.base.md 清空成你的规则即可，生成器不关心内容。

Q：支持哪些 AI 工具？

Claude Code（CLAUDE.md + Skills）、Cursor / 通用 AGENTS 协议（AGENTS.md）、GitHub Copilot（.github/copilot-instructions.md + 按域 instructions）。

License

MIT