rulemason

让 AI 写的代码，读起来像人写的。

中文 · English

用 AI 写代码很快，难的是几个月以后。功能一个个加上去，代码越堆越多，写法越来越绕：同一段逻辑复制了好几份，没人调用的函数和参数留在原处，为了“以后可能用到”套了一层又一层抽象。到最后，连工程师自己都很难看懂，读起来完全不像人写的代码。出了问题不好查，想整理成材料拿出去也拿不出手。

rulemason 是给 AI 编码工具定的一套规矩，外加每次改动都要过的关卡。 支持 Claude Code、Cursor、Codex、OpenCode。规矩写在项目里，AI 写方案、写代码、写文档时照着做；写完代码，关卡会让 AI 先精简、请一个独立的审查者看一遍，再跑 lint 和测试，过了关才算完成。

我为什么做这个

我平时用 AI 写代码，也用它写 PRD、写方案、写文案。项目功能越加越多以后，代码越来越多，语法越来越复杂，连工程师都很难理解，完全不像人写的。冗余、重复、死代码也越来越多。

所以我做了这套规则来约束 AI：让代码更精简，逻辑简单易懂，方便调试，后期申请软著、整理专利材料也更方便。

接入后你会得到

• 更少的代码：每次写完，AI 先把这次改动里的重复、死代码、多余的抽象和绕弯的逻辑精简掉，需求和对外行为保持不变。
• 看得懂的逻辑：九条写法规矩，比如每个文件第一行写它是干什么的、主流程按步骤写注释、同一段逻辑出现第二次就抽成函数、不留没人调用的参数和函数。Python 由 ruff 自动检查，React 由 ESLint 自动检查。
• 好调试：错误不在内部被悄悄吞掉，只在最外层统一处理；修 bug 前先复现、找根因，说“修好了”之前必须在当次跑过验证命令。
• 文档也受约束：PRD、方案、规格有固定写法，比如必须写“这次不做什么”、每个决策要写被否决的备选方案、风险要写对策、上线要写回滚方式。中文排版和套话也可以用命令检查。
• 代码拿得出手：结构清楚、注释到位、每次改动都留有检查记录，申请软著、整理专利材料时更省事。rulemason 只管代码和文档质量，不保证任何申请能通过。

三步上手 · 用和不用的区别 · 怎么工作 · 一次真实整理 · 常见问题

三步上手

需要 uv，Python 3.11 或更高。方案和代码的关卡需要 OpenSpec（npm install -g @fission-ai/openspec@latest）；没装也能先只接入规矩和 lint，装好后运行 rulemason update 补齐。

uv tool install rulemason    # 1. 每台机器装一次
rulemason init               # 2. 在项目根目录运行：勾选你用的 AI 工具，看一眼计划，确认后写入

默认接入当前目录。目录不对时写成 rulemason init <项目根>。终端不能提问时要同时带上工具和确认：rulemason init --tools claude,cursor --yes。工具 id 是 opencode、claude、cursor、codex。

/rulemason                   # 3. 在 AI 工具里运行一次：核对项目简介、确认红线和命令表

之后照常开发。走 OpenSpec 时，关卡由 AI 按规矩执行，不用记命令：

/opsx:propose 功能名         # 写方案（Cursor、OpenCode 里是 /opsx-propose；Codex 是 $openspec-propose）
/opsx:apply 功能名           # 写代码，写完自动精简、审查、lint、测试
/opsx:archive 功能名         # 归档

init 只写计划里列出的文件，不提交、不推送。结尾会给出 check 的结论、这次改了哪些文件、还要你处理的事，以及下一步。

用和不用，差在哪

	不用 rulemason	用 rulemason
代码越写越多	重复、死代码、多余抽象慢慢堆积	每次写完先精简这次的改动，再交给独立审查者
规矩放在哪	CLAUDE.md、AGENTS.md 各写一份，手动同步	只在一处维护；每个工具读同一份只读副本，随项目提交
AI 说“写完了”	你自己跑 lint、跑测试、逐行审	ruff、测试、前端 lint 自动跑完，必须修的问题修好再审一遍
写代码之前	方案好不好全靠你看	开启判断后，方案写完、写代码前各查一次，碰到红线就停下等你
规矩被改了	没人发现	rulemason check 以非 0 退出，放进 CI 就能拦住
老项目接入	lint 一片红，无从下手	先建基线，之后只修每次改动新引入的问题
换工具或账号	规矩重写一遍	rulemason init 加上新工具，规矩和关卡原样带过去
密钥与线上操作	看 AI 自觉	读可以直接做；改东西每次都要你同意；删除只给入口，由人操作；密钥不进对话

怎么工作

flowchart TB
  subgraph rules["内置规则（全程生效）"]
    direction LR
    R1["九条写法<br/>外部操作与密钥"]
    R2["Python / React 落法<br/>界面文案三档<br/>按项目复制"]
    R3["方案写法 · 编码审慎<br/>产品产物审慎 · 文案卫生<br/>中文排版"]
    R1 ~~~ R2 ~~~ R3
  end
  subgraph plan["方案"]
    direction LR
    A["/opsx:propose<br/>写方案"] --> B{"判断方案<br/>有 key 才用 Jev"}
    B -- 格式问题 --> A
    B -- 碰到红线 --> U["停下问你"]
    B -- 通过 --> C["/opsx:apply<br/>写代码前再查一次<br/>有 key 才用 Jev"]
    B -- 无 key --> N["不调用 Jev<br/>格式在本机，其余待人工<br/>--lint-only 只查格式"]
  end
  subgraph build["写代码与自动检查"]
    direction LR
    D["写代码"] --> E["自动精简"] --> F["独立审查"] --> G["ruff"] --> H["测试"]
  end
  subgraph finish["收尾归档"]
    direction LR
    I["前端 lint"] --> J["文案检查（需开启判断）<br/>长文案：Jev（需 key）"] --> K["写检查记录<br/>verification.md"] --> L["/opsx:archive<br/>归档"]
  end
  rules --> plan
  rules --> build
  rules --> finish
  plan --> build
  build --> finish

• 自动精简：只动这次改动里的重复、死代码、多余抽象和过于复杂的逻辑，需求、对外行为和接口保持不变。Claude Code 里这一步用它自带的 /simplify。
• 独立审查：审查者拿不到文件和命令，只看交给它的改动和方案，从需求符合、正确性、安全、代码质量、测试、改动是否干净六个方面逐项给出结论。必须修的问题，以及改动范围内能安全修的意见，会自动修好再审，最多两轮。两轮后还有必须修的，就停下来说明。不把逐条审代码交给你。
• lint 与测试：只修这次改动新引入的问题；改动前就有的问题列出数量，不顺手乱改。
• 判断：方案写完、写代码前各查一次，可选。有 key 才把方案交给 Jev。设计文档的格式（否决理由、风险对策、回滚）始终在本机检查，不调用 Jev；--lint-only 只做这一段。没有 key 时不调用 Jev，其余规则记为待人工。
• 文案检查：改了界面文案、并且已经开启判断时才跑。禁词和短标签在本机查；较长的文案有 key 才交给 Jev。没开判断就跳过，汇报里写明“判断层未装”。没有 key 时不调用 Jev。
• 不走 OpenSpec 的小改动：项目有 openspec/ 时，AI 先读已写好的规格。会破坏已承诺的行为就先停下问你；不会就直接改，改完跑 ruff 和测试。没有 OpenSpec 时不跑方案判断，直接改完同样只跑 ruff 和测试。这两种情况都不做自动精简和独立审查，也不写 verification.md。

接入后多出哪些文件

全部随项目提交，同事、云端 agent 和 CI 不装 rulemason 也能读到：

文件	作用
.rulemason/rules/	规矩正文的只读副本，只放项目用得上的（Go 项目不会收到 Python、React 的规矩）
.rulemason/lint/	ruff、ESLint 的基础规则，你项目里的配置继承它们
.rulemason/result-check/	文案和文档检查的预设（只在第一次写入，不覆盖你改过的）
AGENTS.md	项目简介、红线、命令表，以及指向规矩的标记块
CLAUDE.md	选了 Claude Code 时生成
.claude/skills/rulemason/、.agents/skills/rulemason/	/rulemason 这个 skill。Cursor、Codex、OpenCode 共用 .agents/ 那一份
opencode.jsonc	选了 OpenCode、而且项目里还没有 OpenCode 配置时生成；已有配置就只补上缺的引用
ruff.toml 等 lint 配置	新建，或在你已有的配置里补上继承
openspec/config.yaml、openspec/specs/workflow-gates/spec.md	有 OpenSpec 时补上方案写法规则和关卡说明
.rulemason.yaml	记录选了哪些工具、rulemason 版本、接入日期，以及每个副本的校验值

AGENTS.md、CLAUDE.md 里，只有 <!-- rulemason:… --> 和 <!-- /rulemason:… --> 之间的内容归 rulemason 管。块外是你自己的内容，它不碰。

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗