SuperAPI AI 工具集

create-rule

编程与开发

查看项目

更新于 10-16 10:19

技能介绍

用途

create-rule 是一份指导文档,用于创建有效的 .claude/rules 规则文件。规则文件是模块化的、始终加载的指令,放置在 .claude/rules/ 目录中,用于强制执行一致的行为。它们相当于“常备命令”——每个智能体会话都会自动继承这些规则。

核心原则:有效的规则使用对比示例(Incorrect 与 Correct)来消除歧义。

必要背景:规则是行为护栏,会加载到每个会话中,塑造智能体在所有任务中的行为方式。技能(Skills)是按需加载的。如果指导内容针对特定任务,应创建技能而不是规则。

规则提供的内容

  • 行为约束——应该做什么和不应做什么
  • 代码标准——格式、模式、架构决策
  • 质量门禁——继续之前必须满足的条件
  • 领域约定——项目特定的术语和实践

规则 vs 技能 vs CLAUDE.md

  • 加载时机:规则每个会话加载(或按路径范围加载);技能在触发时按需加载;CLAUDE.md 每个会话加载。
  • 目的:规则是行为约束;技能是程序性知识;CLAUDE.md 是项目概览。
  • 范围:规则是窄而聚焦的主题;技能是完整工作流;CLAUDE.md 是广泛的项目背景。
  • 大小:规则较小(每个 50-200 词);技能中等(200-2000 词);CLAUDE.md 中等(项目摘要)。
  • 格式:规则使用对比示例;技能使用分步指南;CLAUDE.md 使用键值/要点列表。

何时创建规则

创建规则的情况:

  • 某个行为必须适用于所有智能体会话,而不仅是特定任务
  • 智能体在纠正后仍反复犯同样的错误
  • 某个约定有明确的正确/错误模式(可以写出对比示例)
  • 需要对特定文件类型提供路径范围指导

不要为以下情况创建规则:

  • 特定任务的工作流(改用技能)
  • 一次性指令(放在提示词中)
  • 宽泛的项目背景(放在 CLAUDE.md 中)
  • 需要多步骤程序的指导(改用技能)

规则类型

全局规则(无 paths frontmatter):每个会话加载,用于通用约束。

路径范围规则(带 paths frontmatter):仅当智能体处理匹配文件时加载,用于文件类型特定的指导。

优先级规则(评估器/裁判指导):显式的高层规则,设定评估优先级。

规则结构:对比模式

每条规则必须遵循 Description-Incorrect-Correct 模板。该结构通过同时展示不应做什么和应该做什么来消除歧义。

必需部分包括:YAML frontmatter(含 title,可选但推荐 paths)、规则名称标题、1-2 句描述、Incorrect 部分(含代码示例)、Correct 部分(含代码示例)、可选的 Reference 部分。

对比示例为何有效

研究表明,同时包含正面和负面示例的规则比只有正面指导的规则具有显著更强的区分能力。Incorrect/Correct 配对可以:消除歧义、防止合理化、支持自我纠正。

编写有效规则

规则描述原则:显式的高层指导,例如“优先正确性而非风格”“不要奖励幻觉细节”“惩罚自信的错误”“要具体而非模糊”“说明 WHY”。

Incorrect 示例应展示智能体可能实际产生的模式,而非明显损坏或语法错误的代码。

Correct 示例应展示修复 Incorrect 模式所需的最小改动,而非完全不同的代码或过度设计的方案。

令牌效率

规则每个会话都会加载,每个令牌都很重要。目标:每个规则文件 50-200 词(不含代码示例);每个文件一条规则;使用路径范围避免加载无关规则;代码示例每个保持在 20 行以内。

目录结构

.claude/ 下包含 CLAUDE.md(项目概览)和 rules/ 目录。rules/ 中可放置全局规则文件(如 code-style.md、error-handling.md、testing.md、security.md、evaluation-priorities.md),也可用子目录按领域分组(如 frontend/、backend/)。命名约定:使用小写加连字符;按关注点命名而非解决方案;每个文件一个主题;用子目录分组相关规则。

规则创建流程

按顺序执行以下步骤:

  1. 识别行为差距:在写规则前,明确需要纠正的具体智能体行为。来源可以包括观察到的失败、代码库分析、评估发现、用户反馈。将差距记录为具体陈述:“智能体做了 X,但应该做 Y。”

  2. 确定规则范围:判断是全局规则、路径范围规则还是用户级规则(~/.claude/rules/)。

  3. 编写对比示例:这是最关键的一步。先写 Incorrect 和 Correct 示例,再写描述。质量检查包括合理性、最小性、清晰性、具体性、有据可依。

  4. 编写规则描述:用 1-2 句连接对比示例,说明规则强制什么、为什么重要,使用祈使形式。

  5. 组装规则文件:按结构模板创建文件,添加 YAML frontmatter,写入标题和描述,添加 Incorrect 和 Correct 部分,可选添加 Reference 部分,放在 .claude/rules/ 中。

  6. 验证规则:检查文件位置、frontmatter、对比示例、令牌预算、路径范围、是否重叠。

  7. 根据反馈或观察迭代:在完成前应用 Decompose → Filter → Reweight 精炼循环,包括分解检查、错位过滤、冗余过滤、影响重新加权,并根据用户反馈继续迭代直至规则完善。

完整规则示例

文档给出了“使用提前返回减少嵌套”的完整规则示例,包含 frontmatter、标题、描述、Incorrect 示例(嵌套条件中守卫语句埋在三层深处)、Correct 示例(错误条件优先用提前返回处理)、Reference 链接。

还给出了完整的路径范围规则示例:“API 端点必须验证输入”,paths 为 src/api//*.ts 和 src/routes//*.ts,Incorrect 示例信任请求体不做验证,Correct 示例使用 zod schema 验证并在无效时返回 400。

反模式

  • 没有示例的模糊规则:如“保持函数简短可读”,没有具体边界,没有 Incorrect/Correct 来校准行为。
  • 应该是技能的规则:把多步骤流程放进规则。规则应是约束,而非工作流。
  • 重复规则:同一指导出现在两个地方,冲突时智能体无法确定优先级。
  • 过宽的路径范围:paths 设为 */ 等同于全局规则但增加了路径匹配开销,应直接去掉 paths 字段。

规则创建检查清单

  • 行为差距已用“做了 X,应该做 Y”的具体陈述识别
  • 规则类型已确定:全局、路径范围或用户级
  • 对比示例已编写:Incorrect 展示合理的智能体错误
  • 对比示例已编写:Correct 展示最小修复
  • 描述说明 WHAT 和 WHY,使用祈使形式
  • frontmatter 至少包含 title 和 impact
  • 令牌预算在 50-200 词内(不含代码)
  • 路径范围已设置(如适用)且 glob 模式匹配目标文件
  • 没有与 CLAUDE.md 或其他规则重叠