create-rule

ルールの作成

エージェントの精度を高める対比例を用いて、効果的な .claude/rules ファイルを作成するためのガイドです。

概要

基本原則： 効果的なルールでは、対比例（誤りと正しい例）を使って曖昧さをなくします。

必須の前提知識： ルールは行動を制御するガードレールであり、すべてのセッションで読み込まれ、あらゆるタスクでエージェントの振る舞いを形作ります。スキルは必要に応じて読み込まれます。ガイダンスが特定のタスクに限られる場合は、代わりにスキルを作成してください。

ルールについて

ルールは、.claude/rules/ に配置するモジュール式の常時読み込み指示であり、一貫した振る舞いを徹底します。「常設の指示」として機能し、すべてのエージェントセッションに自動的に引き継がれます。

ルールで定める内容

1. 行動上の制約 — 何をすべきか、何をすべきでないか
2. コード標準 — 書式、パターン、アーキテクチャ上の決定事項
3. 品質ゲート — 次に進む前に満たすべき条件
4. ドメインの規約 — プロジェクト固有の用語や慣行

ルール、スキル、CLAUDE.md の比較

項目	ルール（.claude/rules/）	スキル（skills/）	CLAUDE.md
読み込み	毎回のセッション（またはパスを対象に指定）	起動条件を満たしたときに必要に応じて	毎回のセッション
目的	行動上の制約	手順に関する知識	プロジェクトの概要
範囲	限定的で、特定のトピックに集中	ワークフロー全体	プロジェクトの広範な背景情報
サイズ	小（各50～200語）	中（200～2000語）	中（プロジェクトの要約）
形式	対比例	手順ごとのガイド	キーと値／箇条書き

ルールを作成するタイミング

次の場合に作成します：

• 特定のタスクに限らず、すべてのエージェントセッションで振る舞いを適用する必要がある
• 修正しても、エージェントが同じ間違いを繰り返す
• 規約に明確な正誤のパターンがある（対比例を提示できる）
• 特定のファイル形式に対して、パス固有のガイダンスが必要である

次の場合は作成しないでください：

• タスク固有のワークフロー（代わりにスキルを使用してください）
• 一度限りの指示（プロンプトに記載してください）
• プロジェクト全体に関する背景情報（CLAUDE.md に記載してください）
• 複数の手順が必要なガイダンス（代わりにスキルを使用してください）

ルールの種類

グローバルルール（paths フロントマターなし）

毎回のセッションで読み込まれます。普遍的な制約に使用します。

# Error Handling

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

パスを対象に指定したルール（paths フロントマターあり）

エージェントが一致するファイルを扱う場合にのみ読み込まれます。ファイル形式固有のガイダンスに使用します。

---
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. 曖昧さをなくす — 許容されるものと許容されないものの境界を、エージェントが正確に把握できます
2. 正当化を防ぐ — 誤ったパターンが明示されているため、「これでも十分近い」と主張しにくくなります
3. 自己修正を可能にする — エージェントは、自分の出力を両方のパターンと比較できます

効果的なルールの書き方

ルールの説明に関する原則

明確で高レベルなガイダンスにします。

原則	例
スタイルより正確さを優先する	「機能的に正しいが見栄えの悪い解決策は、洗練されているが動かない解決策よりも優れています」
幻覚による詳細を評価しない	「コードベースに根拠のない追加情報は、評価するのではなく減点してください」
自信に満ちた誤りを減点する	「自信たっぷりに述べた誤答は、不確かでも正しい答えより悪いものです」
曖昧にせず、具体的にする	「関数は50行を超えてはなりません」とし、「関数は短く保ってください」としない
理由を説明する	「早期リターンを使ってネストを減らしてください。深くネストしたコードは認知負荷を高めます」

不適切な例：示すべき内容

不適切な例では、エージェントが実際に生成しそうなパターンを示す必要があります。抽象的、または不自然に作られた悪い例には価値がありません。

効果的な不適切な例：

• このシナリオでエージェントが最もよく犯すミスを示す
• エージェントが使いそうな正当化の理由を含める（「こちらの方が簡単です」など）
• コードベースにある実際のコードパターンを反映する

効果のない不適切な例：

• エージェントが生成しそうにない、明らかに壊れたコード
• 構文エラー（エージェントはすでにこれを避けています）
• ルールの対象と無関係なパターン

適切な例：示すべき内容

適切な例では、不適切なパターンを修正するために必要な最小限の変更を示す必要があります。大規模な書き換えは、実際の教訓をわかりにくくします。

効果的な適切な例：

• 不適切な例と同じシナリオを示し、修正する
• 重要な変更箇所を強調する
• こちらの方が優れている理由を説明する簡潔なコメントを含める

効果のない適切な例：

• 不適切な例とはまったく異なるコード
• 不要な複雑さを追加する、過剰に設計された解決策
• 示されていない追加のコンテキストが必要なパターン

トークン効率

ルールはすべてのセッションで読み込まれます。すべてのトークンが重要です。

• 目安： コード例を除き、ルールファイルあたり50～200語
• ファイルごとに1つのルール — 無関係な制約をまとめない
• 関係のないルールが読み込まれないよう、パスを指定する
• コード例： 不適切な例、適切な例ともに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

命名規則：

• 小文字とハイフンを使用する：ErrorHandling.mdではなく、error-handling.md
• 解決策ではなく、対象となる課題に基づいて命名する：try-catch-patterns.mdではなく、error-handling.md
• モジュール性を保つため、ファイルごとに1つのトピックにする
• 関連するルールを分野ごとにまとめるには、サブディレクトリを使用する

ルール作成プロセス

明らかに該当しないステップのみを省略し、次の手順に従ってください。

ステップ1：動作上のギャップを特定する

ルールを書く前に、修正が必要な具体的なエージェントの動作を特定します。この理解は、次のような情報から得られます。

• 観察された失敗 — エージェントが特定のミスを繰り返し犯している
• コードベースの分析 — プロジェクトに、コードだけでは明らかでない規約がある
• 評価で判明した点 — ジャッジまたはメタジャッジが品質上のギャップを特定した
• ユーザーフィードバック — エージェントの動作に対する明示的な修正

ギャップを具体的な記述として文書化します。「エージェントはXをするが、Yをすべきです。」

修正する動作が明確かつ具体的になったら、このステップを完了します。

ステップ2：ルールの適用範囲を決める

このルールを次のどれにするか決めます。

1. グローバル（pathsフロントマターなし）— プロジェクト内のすべての作業に適用
2. パス指定（globパターンを含むpathsフロントマター）— 一致するファイルを扱う場合にのみ適用
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. 不適切なパターンから始める — 修正が必要な、エージェントが生成するコードや動作をそのまま書く
2. 適切なパターンを書く — 問題に対処する最小限の修正を示す
3. 対比が明確か確認する — 不適切な例と適切な例の違いが明白で、1つの概念だけに焦点を当てている必要がある

対比する例の品質チェック：

チェック項目	合格基準
妥当性	エージェントは実際に不適切なパターンを生成するか？
最小限性	適切な例では必要な箇所だけを変更しているか？
明確さ	読者は5秒以内に違いを見分けられるか？
具体性	各例は1つの概念だけを示しているか？
根拠	例は実際のコードベースのパターンに基づいているか？

ステップ 4: ルールの説明を書く

次に、対比的な例をつなぐ 1～2 文の説明を書きます。説明は次の条件を満たす必要があります。

• そのルールが何を強制するかを述べる
• なぜそれが重要か(影響や結果)を述べる
• 命令形を使用する(「早期リターンを使用する」であり、「早期リターンを使用すべきです」ではない)

ステップ 5: ルールファイルを組み立てる

構造テンプレートに従ってルールファイルを作成します。

1. title、impact、tags、および任意で paths を含む YAML frontmatter を追加する
2. 見出しと説明を書く
3. 説明とコードを含む Incorrect セクションを追加する
4. 説明とコードを含む Correct セクションを追加する
5. 任意でリンクを含む Reference セクションを追加する

ファイルを .claude/rules/ に、内容を表すファイル名で配置します。

ステップ 6: ルールを検証する

完了する前に、次を確認します。

1. ファイルの場所 — ルールが .claude/rules/<rule-name>.md に存在する
2. frontmatter — 少なくとも title と impact を含む
3. 対比的な例 — Incorrect と Correct の両方のセクションがコードブロック付きで存在する
4. トークン予算 — 説明が 50～200 語である(コードを除く)
5. パスのスコープ — paths が設定されている場合、glob パターンが対象ファイルに一致する
6. 重複がない — ルールが CLAUDE.md や他のルールのガイダンスを重複していない

ステップ 7: フィードバックまたは観察に基づいて反復する

ルールを書いた後、確定する前に Decompose → Filter → Reweight の改善サイクルを適用します。

7.1 Decompose チェック

複雑なルールを複数の焦点を絞ったルールに分割することを検討します。

あなたが書いたルールについて、自問してください:「このルールは複数の概念をカバーしようとしていないか?」

• はいの場合、それぞれが正確に 1 つの概念を扱う、焦点を絞った複数のルールに分割する
• Incorrect の例が複数の異なるアンチパターンを示している場合、それぞれに対して別々のルールを作成する

7.2 Misalignment フィルター

あなたが書いたルールについて、自問してください:「このルールは許容できるバリエーションにペナルティを与えたり、プロンプトが求めていない行動に報酬を与えたりする可能性はないか?」

• はいの場合、スコープを狭めるか、対比的な例を書き直す
• 検証: エージェントは実際に Incorrect パターンを生み出すか?(そうでなければ、そのルールは不自然である)

7.3 Redundancy フィルター

既存のすべての .claude/rules/ ファイルに重複がないか確認します。

• 同じ概念をカバーするルールがすでに存在する場合、既存のルールを更新し、今作成した重複ルールを削除する
• 2 つのルールが実質的に重複している場合(同じ行動の境界を強制している)、それらを統合する
• 潜在的な重複を見つけるには ls -R .claude/rules/ と grep -r "relevant-keyword" を使用する

7.4 Impact の再重み付け

次に基づいて 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.

なぜ悪いか: 具体的な境界がない。「短い」はエージェントによって意味が異なります。行動を調整するための Incorrect/Correct がありません。

スキルであるべきルール

# 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
...

なぜ悪いか: ルールはワークフローではなく制約であるべきです。これはスキルに属します。

重複したルール

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

なぜ悪いか: ガイダンスが競合すると、エージェントはどちらが優先されるかを判断できません。各ガイダンスは正確に 1 か所に保ちます。

過度に広いパスのスコープ

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

なぜ悪いか: グローバルルールと同等ですが、パスマッチングのオーバーヘッドがあります。グローバルルールの場合は paths フィールドを完全に削除します。

ルール作成チェックリスト

• 具体的な「X をするが、Y をするべき」という文で行動上のギャップを特定している
• ルールの種類を決定している：全体、パス指定、またはユーザーレベル
• 対比例を記述している：誤りの例では、エージェントがしそうなもっともらしい間違いを示している
• 対比例を記述している：正しい例では、最小限の修正を示している
• 説明で、ルールが適用する内容とその理由を述べている
• フロントマターに title と impact が含まれている
• トークン数：50～200 語（コード例を除く）
• ルールファイルごとにトピックが1つである
• CLAUDE.md や他のルールファイルと重複していない
• パス指定に適切な glob パターンを使用している（該当する場合）
• わかりやすいハイフン区切りの名前を付けて .claude/rules/ に配置している

要点

効果的なルールは、ただ指示するのではなく、実例を示します。 誤りと正しい例を対比するパターンを使うことで、文章による説明だけでは残る曖昧さをなくせます。避けるべきことと、どのように出力すべきかの両方をエージェントが確認できると、遵守状況が大幅に改善します。

すべてのルールは、次の3つの問いに答える必要があります。

1. 何を適用するのか？
2. なぜ重要なのか？
3. どのように正しい例と誤った例が異なるのか？（対比例で示す）

Claude Code 公式ルールガイドライン

大規模なプロジェクトでは、.claude/rules/ ディレクトリを使って、指示を複数のファイルに整理できます。これにより指示がモジュール化され、チームでのメンテナンスが容易になります。また、ルールを特定のファイルパスに限定できるため、Claude が一致するファイルを扱うときだけコンテキストに読み込まれ、ノイズを減らしてコンテキスト領域を節約できます。

ルールは各セッションの開始時、または一致するファイルを開いたときにコンテキストに読み込まれます。常にコンテキストに含める必要のないタスク固有の指示には、代わりに[スキル](/en/skills)を使用してください。スキルは、呼び出したとき、または Claude がプロンプトに関連すると判断したときにのみ読み込まれます。

ルールを設定する

プロジェクトの .claude/rules/ ディレクトリに Markdown ファイルを配置します。各ファイルでは1つのトピックを扱い、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 フロントマターのないルールは、起動時に .claude/CLAUDE.md と同じ優先度で読み込まれます。

パス指定ルール

paths フィールドを含む YAML フロントマターを使って、特定のファイルにルールを限定できます。この条件付きルールは、指定したパターンに一致するファイルを 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 コンポーネント

複数のパターンを指定できます。また、波括弧展開を使うと、1つのパターンで複数の拡張子に一致させられます。

---
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

ユーザーレベルのルールはプロジェクトルールより先に読み込まれるため、プロジェクトルールの優先度が高くなります。