RuleDoctor 用户指南

1. 这个 Skill 是什么？

RuleDoctor 是一个装在 Claude / Codex / Cursor 里的 Skill（一文件夹说明，教 Agent 怎么做事）。

它不是替你写代码的工具，而是让助手：

在改文件、跑命令之前，先找到并阅读你项目里的规则；
在要违反规则时停下来，告诉你违反了哪一条，并给出更安全的做法；
在长对话、上下文变短之后，重新读规则，而不是凭印象乱来。

2. 它解决什么真实问题？

你可能写过：

CLAUDE.md
AGENTS.md
.cursorrules
.cursor/rules/*.mdc

但助手仍然：不问就用错机器别名、执行 git push --force、跳过「先读某份文档」的约定。

Skill 要减少的是「助手根本没按项目规矩来」，而不是替你做代码审查。

3. 你为什么需要它？

没有 Skill	有 Skill
助手直接改代码	助手先说明「我读了哪些规则、本场硬约束是什么」
违禁命令可能直接执行	助手应拒绝并解释（如 force push）
聊久了规则像「忘了」	你说上下文变短 → 助手应重新读规则文件
你只能事后猜	可选 CLI 用本地聊天记录生成报告（见下文）

4. 适用于哪些 Agent？

Agent	安装位置
Claude Code	`~/.claude/skills/ruledoctor/`
OpenAI Codex	`~/.codex/skills/ruledoctor/`
Cursor	`~/.cursor/skills/` 或项目 `.cursor/skills/`

同一套 SKILL.md，用 CC Switch 也可以一键同步到多个 App。见 CC-Switch-安装.md。

5. 怎么安装？

git clone https://github.com/syf2211/ruledoctor.git
cp -R ruledoctor/skills/ruledoctor ~/.claude/skills/
cp -R ruledoctor/skills/ruledoctor ~/.codex/skills/

或用 CC Switch / npx skills add（见 README）。

6. 怎么触发？

你不用记命令名。满足下面任意一条，Agent 应按 Skill 行事：

项目里有 CLAUDE.md、.cursorrules 等规则文件，且你在该项目里让它写代码；
你要 git push、部署、删大量文件等敏感操作；
你说「上下文被压缩了」「好像忘了规则」。

新开一场对话更容易让 Skill 被加载（装完后请重启或新会话）。

7. 触发后 Agent 会做什么？

按顺序（Skill 正文里的要求）：

步骤	Agent 应做的事	你在聊天里应看到
开场	Read 根规则 + `required_reads` 清单里的文件	默认：已读文件列表 + 最多 3 条硬约束（不长篇复述）
你要求「展开全部规则」时	再发完整摘要	较长规则说明
动手前	对照规则检查即将执行的命令	违禁时不执行，并说明改用什么
上下文变短后	重新 Read 规则文件	用一句话复述仍生效的规矩
仅当你要求「体检/报告」时	运行 `ruledoctor --last-session`	终端或 HTML 报告路径

Skill 不会自动在每次对话末尾刷报告——除非你要求，或你另外装了 ruledoctor setup 的结束 Hook。

8. 怎么判断已经生效？

在有规则的项目里新开对话，试这三件事：

小任务：「加个 README 一行」→ 助手是否先提规则来源？
违禁试探：「帮我 force push」→ 是否拒绝？
压缩：「刚才上下文压缩了，按规则重来」→ 是否重新读规则文件？

三项里有两项符合，通常说明 Skill 在工作。

9. 没生效怎么办？

现象	可能原因	怎么办
助手从不提规则	Skill 没装进对应目录	检查 `~/.claude/skills/ruledoctor/SKILL.md` 是否存在
仍执行 force push	只靠 Skill 文字，无 Hook	可选：`ruledoctor setup -p .` 启用命令拦截
项目无规则文件	空目录、Downloads 临时聊	运行 `ruledoctor setup -p .` 生成 `CLAUDE.md`
旧对话里没变化	Skill 装在新会话才加载	新开对话
Cursor 不加载	未开 Agent Skills	Cursor 设置 → Rules → 打开 Agent Skills（视版本而定）

10. 三层：Skill / CLI / Hook

	Skill	CLI	Hook
作用	读规则 + 简短汇报 + 口头拒绝	事后用 jsonl 核对	Bash 硬拦截 + 规则注入；CLI 可用时结束报告
抽象行为（中文、汇报、验证说明）	主战场	仅启发式	做不到实时拦回复
命令式（force push）	软拒绝	事后核对	可硬拦

npm i -g ruledoctor 目前 404（尚未发布到 npm registry）。不要依赖 npx ruledoctor 生成报告；要用 CLI 请 clone 仓库并 build。

Hook 机制（触发时机、抽象规则能不能 hook）： Hook是什么.md

11. `required_reads`

在 .ruledoctor.json 列出必读路径（如 CONTRIBUTING.md、docs/agent_workflow_protocol.md）。不扫全库；README.md 只有写进清单才强制读。

12. 分数说明

分数是什么意思.md

可选：项目里生成规则模板 + Hook

git clone https://github.com/syf2211/ruledoctor.git && cd ruledoctor && npm i && npm run build
node dist/index.js setup -p /path/to/your-project

会生成 CLAUDE.md、.ruledoctor.json（含 required_reads 字段），并可配置 Hook。

FilesExpand file tree

用户指南.md

Latest commit

History