create-rule

创建规则

通过正反示例编写有效 .claude/rules 文件的指南，以提高 Agent 的准确性。

概述

核心原则： 有效规则使用正反示例（错误与正确）来消除歧义。

必需背景： 规则是行为准则，会加载到每个会话中，并塑造 Agent 在所有任务中的行为。技能按需加载。如果指导仅适用于特定任务，请改为创建技能。

关于规则

规则是放在 .claude/rules/ 中的模块化指令，始终加载，用于规范一致的行为。它们相当于“常设命令”——每个 Agent 会话都会自动继承。

规则的作用

1. 行为约束 — 规定应该做什么，以及不应该做什么
2. 代码标准 — 格式、模式和架构决策
3. 质量关卡 — 继续操作前必须满足的条件
4. 领域规范 — 项目专属的术语和实践

规则、技能与 CLAUDE.md 的区别

方面	规则（.claude/rules/）	技能（skills/）	CLAUDE.md
加载方式	每个会话（或按路径范围加载）	触发时按需加载	每个会话
用途	行为约束	流程性知识	项目概览
范围	狭窄、聚焦的主题	完整工作流	广泛的项目背景
规模	小型（每条 50-200 个词）	中型（200-2000 个词）	中型（项目摘要）
格式	正反示例	分步指南	键值对 / 项目符号

何时创建规则

适合创建规则的情况：

• 某种行为必须适用于所有 Agent 会话，而不仅是特定任务
• 即使经过纠正，Agent 仍反复犯同样的错误
• 某项规范有明确的正误模式（可以提供正反示例）
• 某些文件类型需要特定路径的指导

不适合创建规则的情况：

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

规则类型

全局规则（无 paths frontmatter）

每个会话都会加载。用于通用约束。

# Error Handling

All error handlers must log the error before rethrowing.
Never silently swallow exceptions.

路径范围规则（带 paths frontmatter）

仅当 Agent 处理匹配的文件时加载。用于特定文件类型的指导。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

All API endpoints must include input validation.
Use the standard error response format.

优先级规则（评估者 / 裁判指导）

明确的高层规则，用于设定评估优先级。

# Evaluation Priorities

Prioritize correctness over style.
Do not reward hallucinated detail.
Penalize confident wrong answers more than uncertain correct ones.

规则结构：正反示例模式

每条规则都必须遵循“描述-错误-正确”模板。这种结构通过展示不该做什么和该做什么来消除歧义。

必需部分

---
title: Short Rule Name
paths:                          # Optional but preferable: when it is possible to define, use it!
  - "src/**/*.ts"
---

# Rule Name

[1-2 sentence description of what the rule enforces and WHY it matters.]

## Incorrect

[Description of what is wrong with this pattern.]

\`\`\`language
// Anti-pattern code or behavior example
\`\`\`

## Correct

[Description of why this pattern is better.]

\`\`\`language
// Recommended code or behavior example
\`\`\`

## Reference

[Optional: links to documentation, papers, or related rules.]

正反示例为何有效

研究表明，同时包含正面和负面示例的规则，其区分能力显著强于只提供正向指导的规则。错误与正确的配对：

1. 消除歧义 — Agent 可以看到可接受与不可接受之间的确切界限
2. 避免自我辩解 — 明确展示错误模式后，就更难辩称“这样也差不多”
3. 促成自我纠正 — Agent 可以将自己的输出与两种模式进行比较

编写有效规则

规则描述原则

明确的高层指导：

原则	示例
正确性优先于风格	“功能正确但不够美观的解决方案，胜过优雅但无法正常工作的方案”
不要奖励臆造的细节	“对代码库缺乏依据的额外信息应受到惩罚，而非奖励”
惩罚自信的错误	“自信地给出错误答案，比不确定地给出正确答案更糟”
具体，不要含糊	“函数不得超过 50 行”，而不是“保持函数简短”
说明原因	“使用提前返回来减少嵌套——深层嵌套代码会增加认知负担”

错误示例：展示什么

错误部分必须展示 Agent 有可能生成的模式。抽象或刻意编造的错误示例毫无价值。

有效的错误示例：

• 展示 Agent 在此场景中最常犯的错误
• 包含 Agent 可能使用的理由（“这样更简单”）
• 反映代码库中真实存在的代码模式

无效的错误示例：

• 明显有问题、Agent 不会生成的代码
• 语法错误（Agent 已会避免这类错误）
• 与规则所关注的问题无关的模式

正确示例：展示什么

正确部分必须展示修复错误模式所需的最小改动。大幅重写会掩盖真正要点。

有效的正确示例：

• 展示与错误示例相同的场景，并予以修正
• 突出关键改动
• 添加简短注释，说明这样做的原因

无效的正确示例：

• 与错误示例完全不同的代码
• 添加不必要复杂度的过度设计方案
• 需要额外上下文才能理解的模式

Token 效率

规则会在每次会话中加载。每个 token 都很重要。

• **目标：**每个规则文件包含 50–200 个单词（不包括代码示例）
• 每个文件一条规则——不要将无关约束打包在一起
• 使用路径范围，避免加载无关规则
• **代码示例：**每段不超过 20 行（错误示例和正确示例）

目录结构

.claude/
├── CLAUDE.md                    # Project overview (broad)
└── rules/
    ├── code-style.md            # Global: code formatting rules
    ├── error-handling.md        # Global: error handling patterns
    ├── testing.md               # Global: testing conventions
    ├── security.md              # Global: security requirements
    ├── evaluation-priorities.md # Global: judge/evaluator priorities
    ├── frontend/
    │   ├── components.md        # Path-scoped: React component rules
    │   └── state-management.md  # Path-scoped: state management rules
    └── backend/
        ├── api-design.md        # Path-scoped: API patterns
        └── database.md          # Path-scoped: database conventions

命名约定：

• 使用小写字母和连字符：error-handling.md，而非 ErrorHandling.md
• 按关注点命名，而非按解决方案命名：error-handling.md，而非 try-catch-patterns.md
• 每个文件一个主题，以便模块化
• 使用子目录按领域对相关规则分组

规则创建流程

按顺序执行以下步骤，只有在某个步骤明显不适用时才跳过。

步骤 1：确定行为差距

编写任何规则之前，先确定需要纠正的具体 Agent 行为。可通过以下方式了解这一点：

• 观察到的失败——Agent 反复犯某个特定错误
• 代码库分析——项目存在仅凭代码不易察觉的约定
• 评估结果——评审者或元评审者发现了质量差距
• 用户反馈——用户明确纠正了 Agent 的行为

将差距记录为具体陈述：“Agent 会做 X，但应该做 Y。”

当需要纠正的行为清晰且具体时，即可结束此步骤。

步骤 2：确定规则范围

决定此规则应属于以下哪种范围：

1. 全局（无 paths frontmatter）——适用于项目中的所有工作
2. 路径范围（paths frontmatter 中包含 glob 模式）——仅在处理匹配文件时适用
3. 用户级（~/.claude/rules/）——适用于个人偏好的所有项目

选择指南：

Is this project-specific?
  No  → User-level rule (~/.claude/rules/)
  Yes → Is it relevant to ALL files?
    Yes → Global rule (.claude/rules/rule-name.md)
    No  → Path-scoped rule (.claude/rules/rule-name.md with paths: frontmatter)

步骤 3：编写对比示例

这是最关键的一步。在编写描述之前，先编写错误示例和正确示例。

1. 从错误模式开始——准确写出 Agent 生成且需要纠正的代码或行为
2. 编写正确模式——展示解决问题所需的最小修正
3. 确认对比清晰——错误示例和正确示例之间的差异必须明显，且只聚焦于一个概念

对比示例质量检查：

检查项	通过标准
合理性	Agent 真的会生成这种错误模式吗？
最小性	正确模式是否只做了必要的改动？
清晰度	读者能否在 5 秒内看出差异？
针对性	每个示例是否恰好展示一个概念？
依据充分	示例是否取自代码库中的真实模式？

Step 4: 编写规则描述

现在编写 1-2 句描述，将对照示例联系起来。描述必须：

• 说明规则强制执行的内容
• 说明规则的重要性（影响或后果）
• 使用祈使句（“使用提前返回”，而不是“你应该使用提前返回”）

Step 5: 组装规则文件

按照结构模板创建规则文件：

1. 添加 YAML frontmatter，包含 title、impact、tags，以及可选的 paths
2. 编写标题和描述
3. 添加 Incorrect 部分，包含描述和代码
4. 添加 Correct 部分，包含描述和代码
5. 可选：添加包含链接的 Reference 部分

将文件放在 .claude/rules/ 中，并使用描述性文件名。

Step 6: 验证规则

完成前，请检查：

1. 文件位置——规则是否存在于 .claude/rules/<rule-name>.md
2. Frontmatter——至少包含 title 和 impact
3. 对照示例——Incorrect 和 Correct 部分是否都存在，并包含代码块
4. 令牌预算——描述是否为 50-200 个词（不包括代码）
5. 路径范围——如果设置了 paths，glob 模式是否匹配预期文件
6. 无重叠——规则是否与 CLAUDE.md 或其他规则中的指导重复

Step 7: 根据反馈或观察迭代

编写规则后，在定稿前应用 Decompose → Filter → Reweight 优化循环：

7.1 Decompose 检查

考虑将复杂规则拆分为多个重点明确的规则。

对于已编写的规则，问问自己：“这条规则是否试图涵盖多个概念？”

• 如果是，将其拆分为多个重点明确的规则，每条规则只涉及一个概念
• 如果 Incorrect 示例展示了多个不同的反模式，则为每种模式分别创建规则

7.2 Misalignment Filter

对于已编写的规则，问问自己：“这条规则是否会惩罚可接受的变体，或奖励提示词未要求的行为？”

• 如果是，缩小范围或重写对照示例
• 验证：Agent 实际上会产生 Incorrect 模式吗？（如果不会，这条规则就是牵强附会的）

7.3 Redundancy Filter

检查所有现有的 .claude/rules/ 文件是否存在重叠：

• 如果已有规则涵盖相同概念，更新现有规则，并删除刚创建的重复规则
• 如果两条规则有实质性重叠（强制执行相同的行为边界），则将它们合并
• 使用：ls -R .claude/rules/ 和 grep -r "relevant-keyword" 查找可能重叠的规则

7.4 Impact Reweight

根据以下标准设置或重新设置 impact frontmatter 字段：

• CRITICAL：反模式会导致数据丢失、安全漏洞或系统故障
• HIGH：反模式会导致功能失效、行为错误或难以调试的问题
• MEDIUM：反模式会降低质量、可读性或可维护性
• LOW：反模式只是轻微的风格或惯例问题

7.5 根据反馈迭代

完成优化循环后，向用户征求对规则的反馈。

• 如果用户认为规则不错，可以停止优化循环。
• 如果用户认为规则不好，则应更新规则以弥补不足。

持续迭代，直到规则达到要求。

完整规则示例

---
title: Use Early Returns to Reduce Nesting
paths:
  - "**/*.ts"
---

# Use Early Returns to Reduce Nesting

Handle error conditions and edge cases at the top of functions using early returns. Deeply nested code increases cognitive load and makes logic harder to follow.

## Incorrect

Guard clauses are buried inside nested conditionals, making the happy path hard to find.

\`\`\`typescript
function processOrder(order: Order) {
  if (order) {
    if (order.items.length > 0) {
      if (order.status === 'pending') {
        // actual logic buried 3 levels deep
        const total = calculateTotal(order.items)
        return submitOrder(order, total)
      } else {
        throw new Error('Order not pending')
      }
    } else {
      throw new Error('No items')
    }
  } else {
    throw new Error('No order')
  }
}
\`\`\`

## Correct

Error conditions are handled first with early returns, keeping the happy path at the top level.

\`\`\`typescript
function processOrder(order: Order) {
  if (!order) 
    throw new Error('No order')
  if (order.items.length === 0) 
    throw new Error('No items')
  if (order.status !== 'pending') 
    throw new Error('Order not pending')

  const total = calculateTotal(order.items)
  return submitOrder(order, total)
}
\`\`\`

## Reference

- [Flattening Arrow Code](https://blog.codinghorror.com/flattening-arrow-code/)

完整的路径限定规则示例

---
title: API Endpoints Must Validate Input
paths:
  - "src/api/**/*.ts"
  - "src/routes/**/*.ts"
---

# API Endpoints Must Validate Input

Every API endpoint must validate request input before processing. Unvalidated input leads to runtime errors, security vulnerabilities, and data corruption.

## Incorrect

The handler trusts the request body without validation, allowing malformed data through.

\`\`\`typescript
export async function POST(req: Request) {
  const body = await req.json()
  const user = await db.users.create({
    email: body.email,
    name: body.name,
  })
  return Response.json(user)
}
\`\`\`

## Correct

Input is validated with a schema before use. Invalid requests receive a 400 response.

\`\`\`typescript
import { z } from 'zod'

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
})

export async function POST(req: Request) {
  const parsed = CreateUserSchema.safeParse(await req.json())
  if (!parsed.success) {
    return Response.json({ error: parsed.error.flatten() }, { status: 400 })
  }
  const user = await db.users.create(parsed.data)
  return Response.json(user)
}
\`\`\`

反模式

缺少示例的含糊规则

# Bad: No contrastive examples, too vague
Keep functions short and readable.
Use meaningful variable names.

**为什么不好：**没有具体边界。“简短”对不同 Agent 的含义各不相同。没有 Incorrect/Correct 示例来校准行为。

应该作为 Skills 的规则

# Bad: Multi-step procedure in a rule
When deploying to production:
1. Run all tests
2. Check coverage thresholds
3. Build the project
4. Run integration tests
5. Deploy to staging first
...

**为什么不好：**规则应该是约束，而不是工作流。这应该放在 skill 中。

重复规则

# Bad: Same guidance in two places
# .claude/rules/formatting.md says "use 2-space indent"
# CLAUDE.md also says "use 2-space indent"

**为什么不好：**当指导相互冲突时，Agent 无法判断哪条优先。每条指导都应只放在一个位置。

过于宽泛的路径限定

---
paths:
  - "**/*"
---

**为什么不好：**这相当于一条全局规则，却增加了路径匹配的开销。对于全局规则，请完全移除 paths 字段。

规则创建检查清单

• 识别行为差距，并用具体的“现在会做 X，应该做 Y”语句描述
• 确定规则类型：全局、路径范围或用户级
• 编写对比示例：错误示例展示 Agent 可能犯的合理错误
• 编写对比示例：正确示例展示最小修正
• 描述说明规则强制执行什么以及原因
• Frontmatter 包含 title 和 impact
• Token 预算：50-200 个词（不包括代码示例）
• 每个规则文件只包含一个主题
• 不与 CLAUDE.md 或其他规则文件重叠
• 路径范围使用正确的 glob 模式（如适用）
• 文件放在 .claude/rules/ 中，并使用描述性连字符名称

要点

有效的规则会展示，而不只是告知。 错误/正确的对比模式可以消除文字描述留下的歧义。当 Agent 能同时看到应该避免什么以及应该产出什么时，遵循规则的情况会显著改善。

每条规则都应回答三个问题：

1. 什么行为需要强制执行？
2. 为什么这很重要？
3. 如何区分正确与错误？（通过对比示例展示）

Claude Code 官方规则指南

对于较大的项目，可以使用 .claude/rules/ 目录将指令整理到多个文件中。这样可以让指令模块化，便于团队维护。规则也可以限定到特定文件路径，因此只有当 Claude 处理匹配的文件时，规则才会加载到上下文中，从而减少干扰并节省上下文空间。

规则会在每次会话中加载到上下文，或在打开匹配的文件时加载。对于不需要始终放在上下文中的特定任务指令，请改用[技能](/en/skills)；技能只会在你调用时，或 Claude 判断它们与提示词相关时加载。

设置规则

将 Markdown 文件放在项目的 .claude/rules/ 目录中。每个文件应涵盖一个主题，并使用描述性文件名，例如 testing.md 或 api-design.md。系统会递归发现所有 .md 文件，因此你可以将规则整理到 frontend/ 或 backend/ 等子目录中：

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Code style guidelines
│       ├── testing.md      # Testing conventions
│       └── security.md     # Security requirements

没有 paths frontmatter 的规则会在启动时加载，其优先级与 .claude/CLAUDE.md 相同。

特定路径规则

可以使用包含 paths 字段的 YAML frontmatter，将规则限定到特定文件。这些条件规则仅在 Claude 处理与指定模式匹配的文件时生效。

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

不包含 paths 字段的规则会无条件加载，并适用于所有文件。路径范围规则会在 Claude 读取与模式匹配的文件时触发，而不是在每次使用工具时触发。

在 paths 字段中使用 glob 模式，按扩展名、目录或任意组合匹配文件：

模式	匹配内容
**/*.ts	任意目录中的所有 TypeScript 文件
src/**/*	src/ 目录下的所有文件
*.md	项目根目录中的 Markdown 文件
src/components/*.tsx	特定目录中的 React 组件

你可以指定多个模式，也可以使用花括号展开，在一个模式中匹配多个扩展名：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

使用符号链接在项目间共享规则

.claude/rules/ 目录支持符号链接，因此你可以维护一套共享规则，并将其链接到多个项目中。符号链接会正常解析和加载，并且系统能够检测循环符号链接并妥善处理。

此示例同时链接一个共享目录和一个单独的文件：

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

用户级规则

~/.claude/rules/ 中的个人规则适用于你计算机上的每个项目。可用它们设置与具体项目无关的偏好：

~/.claude/rules/
├── preferences.md    # Your personal coding preferences
└── workflows.md      # Your preferred workflows

用户级规则会先于项目规则加载，因此项目规则具有更高优先级。