authoring-claude-md

CLAUDE.md とルールの作成

AI コーディングエージェント向けのプロジェクト固有のメモリーとして機能する、効果的な CLAUDE.md ファイルと .claude/rules/ ルールファイルを作成します。

目的

CLAUDE.md ファイルとルールファイルは、AI エージェントに次の情報を提供します。

• 自明ではない規約、アーキテクチャパターン、注意点
• 繰り返し発生する問題への確認済みの解決策
• 標準的なドキュメントには記載されていない、プロジェクト固有のコンテキスト
• 関連するファイルを編集する場合にのみ読み込まれる、パスを対象とした指示

対象外：明白なパターン、ドキュメントの重複、汎用的なコーディングのアドバイス。

基本原則

• ノイズより有用な情報を：すべての文に、自明ではない価値を持たせてください。AI エージェントがコードベースを読めば推測できる内容は省きます。
• 実行可能なコンテキスト：「何をすべきか」と「なぜ重要か」に焦点を当て、既存のものの説明にとどめないでください。
• 理論上の懸念ではなく、実際の摩擦を解消する：仮定上のシナリオではなく、実際に遭遇した問題に基づいて CLAUDE.md に追加します。Claude に同じことを何度も説明しているなら、記録してください。まだ問題に遭遇していないなら、先回りして解決しようとしないでください。

構成

見出しを使って明確に整理します。一般的なセクションは、アーキテクチャ、規約、注意点、テストです。2〜4 個のセクションを使い、価値を加える内容だけを含めてください。

.claude/rules/ を使用する場合

大規模なプロジェクトでは、指示を .claude/rules/ 配下の複数のファイルに分割します。各 .md ファイルでは、1 つのトピックを扱います。次の場合は、単一の CLAUDE.md よりもルールファイルを優先してください。

• 指示が 200 行を超えて増えている
• コードベースの部分ごとに異なるルールが適用される（フロントエンドとバックエンド、API と CLI など）
• 複数のチームメンバーが異なるセクションを管理している
• 特定のファイル形式を扱う場合にのみ必要な指示がある

ルールファイルの基本

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main project instructions
│   └── rules/
│       ├── code-style.md   # Always loaded
│       ├── testing.md      # Always loaded
│       └── security.md     # Always loaded

ファイルは再帰的に検出されるため、frontend/ や backend/ などのサブディレクトリも使用できます。paths フロントマターのないルールは、.claude/CLAUDE.md と同じ優先度で起動時に読み込まれます。

ルールファイルにも、ノイズより有用な情報を優先する、実行可能なコンテキストを示す、自明な情報を含めないという、同じ作成原則が適用されます。

パス固有のルール

paths フィールドを含む YAML フロントマターを使って、特定のファイルにルールを適用します。これらのルールは、Claude が glob パターンに一致するファイルを読み込むときにのみ読み込まれるため、ノイズを減らし、コンテキストを節約できます。

---
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/rules/ に保存します。これらはプロジェクトのルールより先に読み込まれるため、プロジェクトのルールがより高い優先度になります。

~/.claude/rules/
├── preferences.md    # Personal coding preferences
└── workflows.md      # Preferred workflows

ルールとスキルの違い

ルールは毎回のセッションで読み込まれる（または一致するファイルが開かれたときに読み込まれる）ものです。常にコンテキストとして必要ではない、タスク固有の指示にはスキルを使用してください。スキルは、呼び出されたとき、または Claude が関連すると判断したときにのみ読み込まれます。

含める内容

アーキテクチャ上の決定：モノリスではなくマイクロサービスを選ぶ理由、イベント駆動型パターン、状態管理

自明ではない規約：

• 「リンターで検出されないプライベート API には _internal 接尾辞を使う」
• 「日付フィールドは常に UTC とし、書式設定はクライアント側で行う」
• 「レポートには ORM を使わず、/queries で生の SQL を使う」

繰り返し発生する問題：

• 「認証での TypeError：verify() が Buffer.from(secret, 'base64') を使っていることを確認する」
• 「キャッシュの競合状態：状態を確認する前にロックを取得する」

プロジェクトのパターン：エラー処理、ロギング、API のバージョン管理、マイグレーション

除外する内容

• 行番号：ファイルは変更され、参照が壊れるためです。「42 行目」ではなく、「src/auth/middleware.ts にあります」のように説明的なパスを使います
• 明白な情報：「React を使用しています」（package.json を見ればわかります）。LLM はコンテキスト内学習を行い、コードベースを調べることでパターンを把握します
• コードスタイルのガイドライン：フォーマット規則、命名規則、リンターで適用されるパターンなどです。ESLint、Prettier、Black、golangci-lint などを使い、Claude Code Hooks でフォーマッターを実行します
• 一般的なアドバイス：「よいテストを書きましょう」では、プロジェクト固有の価値がありません
• セットアップ手順：README に記載します。標準から大きく外れる場合を除きます
• 重複した内容：README や既存のドキュメントに記載されている場合は、繰り返すのではなくリンクします
• タスク固有の細かな情報：データベーススキーマ、API 仕様、デプロイ手順は、それぞれ専用のドキュメントに記載します。重複させず、リンクします
• 一時的なメモ：TODO、一度限りのバグ修正、一時的な回避策は、コードコメントに記載します
• 冗長な説明：項目は簡潔にし、長い説明は省きます
• あれもこれも詰め込んだ項目：あらゆる注意点をここに記載する必要はありません。「ほとんどのコーディングセッションで役立つか？」と考えてください。そうでなければ、コードコメントか専用のドキュメントに記載します
• 強調の多用：すべての文や箇条書きの冒頭を太字にせず、本当に注意が必要な場合に限って強調します

矛盾の監査

項目を追加する前に、すでに読み込まれているほかの内容（ユーザーレベルの ~/.claude/CLAUDE.md、兄弟ルールファイル、同じ内容を扱うスキル）と照らし合わせてください。「必要に応じてドキュメントを残す」と「コメントを決して追加しない」のように指示が食い違っていると、エージェントは作業を始める前に矛盾を解決する必要があり、毎回同じように解決するとは限りません。

各トピックは、1 か所にまとめます。

• ほかの場所ですでに説明されている場合：繰り返さず、そこに記載したままにします
• 既存のルールより適用範囲が狭い場合：どのルールの例外なのかを明記します（「リポジトリ全体では Prettier を使用しますが、/legacy では既存のフォーマットを維持します」）
• ユーザーレベルまたはグローバルのルールと実際に矛盾する場合：黙って上書きせず、ユーザーに伝えます

パスの範囲を指定したルールは、対象ファイルに対してルートの CLAUDE.md を補足するものであり、覆すものではありません。

既存のドキュメントへのリンク

内容を重複させず、既存のドキュメントを参照してください。いつ読むべきかも説明します。

良い例：

# Architecture
Event-driven architecture using AWS EventBridge.

- For database schema: see src/database/SCHEMA.md when working with data models
- For auth flows: see src/auth/README.md when working with authentication

悪い例：スキーマ表をコピーしたり、デプロイ手順を貼り付けたり、API の流れを CLAUDE.md に重複して記載したりすること

書き方

具体的に書きます：

• 悪い例：「認証システムには注意してください」
• 良い例：「認証トークンの有効期限は 1 時間です。バックグラウンドジョブでは、src/auth/refresh.ts の refreshToken() を使ってトークンを更新してください」

簡潔に書きます：

• 悪い例：「データベース層を扱う際に、次の点に注意することが重要です……」
• 良い例：「データベースクエリ：CRUD には Prisma を使い、複雑なレポートには /queries の生 SQL を使います」

能動態を使います：

• 悪い例：「デプロイ前にマイグレーションを実行する必要があります」
• 良い例：「デプロイ前にマイグレーションを実行します：npm run migrate:prod」

更新するタイミング

次の場合は CLAUDE.md に追加します。

• コードベースの調査や複雑な問題の解決を通じて、明白ではないパターンを見つけた場合
• かなりの調査を要した問題を解決し、ほかのエージェントも同じ問題に遭遇すると考えられる場合
• コードを見ただけではすぐにわからない注意点を見つけた場合

「除外する内容」に挙げた内容（一度限りの修正、一時的な回避策、ドキュメントにすでにある情報、冗長な説明）は追加しません。

スペリングの規則

常にオーストラリア英語のスペリングを使います

構成例

# Architecture
Event-driven architecture using AWS EventBridge. Services communicate via events, not direct calls.

Auth: JWT tokens with refresh mechanism. See src/auth/README.md for detailed flows when working on authentication.
Database schema and relationships: see src/database/SCHEMA.md when working with data models.

# Conventions
- API routes: Plural nouns (`/users`, `/orders`), no verbs in paths
- Error codes: 4-digit format `ERRR-1001`, defined in src/errors/codes.ts
- Feature flags: Check in middleware, not in business logic
- Dates: Always UTC in database, format client-side via src/utils/dates.ts
- Documentation: Use DocBlocks for public functions, never use "smart" formatting markdown

# Gotchas

**Cache race conditions**: Always acquire lock before checking cache status

**Background job authentication**: Tokens expire after 1 hour. Refresh using
`refreshToken()` in src/auth/refresh.ts before making API calls.

# Testing

- Tests should never have external API calls or dependencies.
- Run `make test` before committing.

トークンの予算

CLAUDE.md は1k～4kトークンを目安にしてください。ほとんどのプロジェクトでは100～300行に収まります。ほとんどのプロジェクトでは CLAUDE.md は1つで十分です。予算を超える場合は、.claude/rules/ ファイルへの分割が役立つか検討してください（特に、一部の内容が特定のファイル形式にのみ適用される場合）。予算を超える場合は、次の対応を行ってください。

1. より簡潔な表現に書き換える
2. 一般的なアドバイスを削除する
3. 内容が重複していないことを確認する

wc -c CLAUDE.md でトークン数を推定し、文字数をおよそ4で割ります。

レビューチェックリスト

最終化する前に、次を確認してください。

• 除外対象から何も紛れ込んでいないこと（行番号、コードスタイル、重複したドキュメント、一時的なメモ、冗長なガイダンス）
• 表現が簡潔で、重複がないこと
• 各セクションに、ひと目では分からない価値があること
• 書式がシンプルであること（スマートクォート、ダッシュの多用、過剰な太字を避ける）
• 情報がすぐに古くなる可能性が低いこと
• 単なる禁止事項（「emダッシュを使わない」）より、代替案を示した肯定的なルール（「節の区切りにはセミコロンまたはピリオドを使う」）を優先すること
• 安定した長期的なパターンに焦点を当てていること
• 内容が引き締まっており、簡潔で実行可能なこと（冗長な説明に終始しない）