rulemason

中文 · English

给 AI 编码工具（Claude Code、OpenCode、Cursor、Codex）的共享规则与检查点。它只管三件事：

• 规则：AI 写方案和代码时要守的写法规矩（九条、各语言落法（Python、React）、界面文案三档、方案写法）。规则只在本仓库维护，每个项目里是一份随项目提交的只读副本，克隆项目的人、云端 agent 与 CI 不装 rulemason 也能读到。
• 检查点：方案写完、写代码前、写完代码后，AI 按规矩自动检查——判断方案、精简代码、独立审查、lint 与测试。不走 OpenSpec 的小改动也先读主规格：动到已写的承诺才代起 change 并问你一次，其余直接改、改完跑 lint 与测试；归档时自动并入主规格，不再问。
• 判断（可选）：用 TypeSafe 的 Jev 模型判断方案是否违反已写下的规矩，输出 pass / review / block；没有 key 时人工逐条判断。

安装（每台机器一次）

从 PyPI 安装（需要 uv）：

uv tool install rulemason
rulemason --version

常用命令

第一次接入

在项目根目录运行：

rulemason init                              # 空格勾选工具，看一眼计划摘要（d 展开明细），确认一次后写入
rulemason init --tools claude,codex --yes   # 非交互：不提问

init 只做能确定做对的事：按项目用到的语言生成规则副本（Go 项目不会收到 Python、React 的落法）、各工具的入口、.gitignore 放行、ruff / ESLint 继承；有 openspec/ 时再补方案写法规则、OpenSpec apply / archive 时给 AI 的检查点提示（config.yaml 的 operations）与项目的检查点规格。ruff 配置已继承项目里的其他配置时，把基础规则接到继承链末端那份配置里；引用的是旧位置的基础配置副本（例如卸载时移到 lint/ 的那份）时改回 .rulemason/ 下的副本。改不了的（例如 ruff 配置写了 select、继承了项目外的配置、ESLint 用了认不出的写法）只报告，写明文件、行号、原文与改法。不提交、不推送，不碰计划以外的文件。

没有 openspec/ 时会问要不要代为运行 openspec init；--yes、拒绝或本机没有 openspec 命令时只接入规则与 lint，装好 OpenSpec 后运行 rulemason update 补齐检查点。

写完只给三行：check 的结论、需要你处理的事、下一步。AGENTS.md 的项目简介从 README 第一段预填，红线先写「暂无」；然后在 AI 工具里运行 /rulemason，核对简介、确认红线（注明出处并逐条确认）与命令表。判断条件满足而本机没有 key 时，init 结尾会问一句要不要配置（key 在 https://typesafe.ai/ 申请）。

日常

日常开发走 OpenSpec，检查点由 AI 自动运行，不用记命令：

/opsx:propose 功能名   方案写完 -> 判断：格式问题 AI 自己改，碰红线的报告给你
/opsx:apply 功能名     写代码前再判断一次，有 block 就停下等你
                       写完 -> 自动精简 -> 独立只读审查 -> ruff -> 测试 -> 前端 lint -> 文案检查
/opsx:archive 功能名   归档，提交

自动精简只处理本次改动里的重复、死代码、冗余抽象或过复杂逻辑，保持需求、外部行为与 API 不变；Claude Code 下这一步用内置的 /simplify。独立审查者拿不到文件与命令工具，只看提供给它的改动与方案；必须修的问题自动修复并重新审查，不要求你逐条审核代码。

已有大量代码的项目接入后，ruff 往往报出很多改动前就有的问题；先在 AI 工具里运行 /rulemason 建立 ruff 基线（自动修复 import、声明框架写法、其余按文件记为「接入前遗留」，都等你确认），之后检查点只修每次改动新引入的问题。

看现状

rulemason check     # 只读，在项目任意子目录运行都可以

第一行就是结论和下一步，照着做即可，例如：

补项目信息：在 AI 工具中运行 /rulemason
接入：运行 rulemason update
接入：手动修改 web/.eslintrc.json（rulemason update 改不了）：……
日常巡检：一切一致

尚未接入、规则副本被改或与本机版本应生成的不一致、工具入口缺失、lint 没有继承基础规则或引用的基础配置不存在时以非 0 退出；只有版本号落后、副本内容相同时照常 0 退出。可以直接放进 CI（CI 钉的版本与项目记录一致，不会因本机升级而失败）：

- uses: astral-sh/setup-uv@v6
- run: uv tool install rulemason==0.8.12
- run: rulemason check

给 AI 与脚本

rulemason check --json          # 结构化结果：next.code 是稳定的动作代码，text 是上面的报告全文；退出码同上
rulemason init --plan [--json]  # 只列接入计划：不写文件、不提问、不运行 openspec init
rulemason update --dry-run [--json]   # 只列升级与补齐计划，不写文件

/rulemason 读的就是 check --json；AI 替你接入前会先用 init --plan 给你看计划。

升级

uv tool upgrade rulemason
rulemason update

update 直接刷新 rulemason 自己管的规则副本与入口；副本只保留本项目用得上的文件，升级到 0.8.4 之后第一次 update 会删掉用不到的（例如没有 React 的项目里的 react.md），项目后来加了语言也由它补上。你自己的文件（ruff、ESLint、openspec/config.yaml 等）缺了配置时，它先列出补齐计划，确认后才写，非交互环境里要加 --yes。之后在项目里跑一遍 lint 与测试再提交。

判断（可选）

判断要求项目在 git 里、已归档至少 3 个 change；rulemason check 的「判断」一行会写明还差什么。要启用时在 AI 工具里运行 /rulemason 并说明要启用判断，它会整理候选判断规则让你逐条确认。

配 key（在自己的终端里运行，输入不显示，不会进命令历史）：

rulemason key

key 写在 ~/.config/rulemason/env（权限 600），只在本机，不进任何仓库；环境变量 TYPESAFE_API_KEY 优先。

手动运行判断：

rulemason judge --change 功能名               # 审 openspec/changes/功能名（已归档的也能直接用名字）
rulemason judge --change 功能名 --lint-only   # 只跑正则检查，不联网
rulemason judge --copy                        # 审新增或改过的界面文案（项目配了 openspec/judge.yaml 才有）
rulemason judge --change 功能名 --dry-run     # 打印将要发送的请求，不发送
rulemason judge --template judgments          # 打印启用判断用的模板（judgments、judge、judge_cases）

项目代码也可以把引擎当库用：from rulemason.judge import load_rules, verdict_or_pending。

卸载

rulemason remove --plan   # 只看计划，不改任何文件
rulemason remove          # 列出计划，确认后卸载；非交互环境加 --yes

remove 删掉 rulemason 生成的东西：规则副本、各工具的 skill、.rulemason.yaml、AGENTS.md / CLAUDE.md 里的 rulemason 标记块、OpenCode 配置里指向 .rulemason/ 的条目，以及没被改过的 operations 提示。ruff、ESLint 还在继承基础规则时，会把这两个文件移到项目的 lint/ 并改好路径，lint 结果不变。手改过的副本保留；产物写法规则、项目的检查点规格、命令表和红线已是项目内容，只在汇报里列出，不删。本机装的 rulemason 不受影响，不用了再运行 uv tool uninstall rulemason。卸载后再接入时，lint/ 下没改过的基础配置会改回引用 .rulemason/ 下的副本，旧文件留给你确认后删除。

出了问题怎么办

rulemason 往项目里写三类东西，都由它管理，不要手改：

• 规则副本：.rulemason/ 与各工具目录下的 skills/rulemason/SKILL.md。
• 标记块：AGENTS.md、CLAUDE.md 里 <!-- rulemason:… --> 与 <!-- /rulemason:… --> 之间的内容；块外是你自己的内容，rulemason 不碰。
• 清单：.rulemason.yaml，记录选了哪些工具、rulemason 版本与每个副本的校验值。

参与修改

改共享规则会影响所有接入项目：在本仓库开 OpenSpec change，在受影响的项目里验证，发布新 tag 后各项目运行 rulemason update。

启用提交前钩子，拦截本机绝对路径（每个 clone 一次）：

git config core.hooksPath .githooks

本地开发：

uv sync
uv run ruff check .
uv run pytest

许可证

Apache-2.0。版权声明见 NOTICE。