これって書くべき？ チームでCLAUDE.md/.cursorrulesを育てる
はじめに
Claude CodeやCursorと一緒に開発しているときに、
「あ、またAIが標準的な実装をしてきた。プロジェクトのルールに合わせて修正しないと...」
「これ、CLAUDE.md/.cursorrulesに書いた方がいいのかな？」
「でも、書くべきかどうかわからない...」
という迷いを抱えたことはありませんか？
迷っているうちに実装に集中してしまい、結局ルールを書かずに、次のメンバーも同じ苦労を繰り返す...
そんなとき、「書くべき判断」が明確になれば迷わず追記でき、チーム全体の知識が自然と蓄積されていきます。
本記事では、CLAUDE.md/.cursorrulesに書くべきかどうかの判断を属人化させず、AIが会話履歴を分析して客観的に提案してくれる仕組み（スラッシュコマンド）を紹介します。
注: 以下はClaude（Claude Code、CursorのClaude拡張機能）の使用を前提に書かれています。CursorでCodexやComposerなどの他のモデルを使う場合も、基本的な考え方は同じですので適宜読み替えてください。
/suggest-claude-mdコマンド
/suggest-claude-mdコマンドは、Claude自身が会話履歴を分析して内省し、「このルールをCLAUDE.mdに追記した方がいいのでは？」と提案してくれる自作のスラッシュコマンドです。
Cursorの.cursorrulesとスラッシュコマンドについては以下をご覧ください。
- Cursor Rules for AI - .cursorrulesファイルの使い方
- Cursor Commands - Cursorのカスタムコマンドの設定方法
今回はClaudeでの使用を想定して書いていきます。以下のコードを.claude/commands/suggest-claude-md.mdに保存してください。
スラッシュコマンドの全文
# CLAUDE.md更新提案コマンド
**あなたの役割**: 会話履歴を分析し、CLAUDE.mdに追記すべき新しいルールやパターンを提案すること。
**重要**: 会話の要約や説明ではなく、「CLAUDE.mdに追記する内容の提案」を出力してください。
## 使用方法
```bash
/suggest-claude-md
```
## 分析基準
以下の3つのトリガー条件に該当する内容を検出してください。
### 1. プロジェクト独自のルール
**検出パターン**:
- 「〜ではなく〜を使ってください」
- 「このプロジェクトでは〜のようにしています」
- 標準的なコードを生成後、プロジェクト固有の方法に修正指示
**例**:
- 環境変数の直接参照ではなく、プロジェクト独自の Config モジュールを使ってください
- このプロジェクトではController内でparamsを直接渡さないルールです
- ORMの標準メソッドではなく、既存のfinderメソッドを使ってください
### 2. 同じような修正指示の繰り返し
**検出パターン**:
- 同じ種類の修正指示が2回以上出現
- 類似のコード修正が複数ファイルで発生
- 同じアドバイスが複数回行われた
**例**:
- 複数のテストで同じセットアップ処理の追加を指示
- 複数のコントローラーで同じパターンの修正
- 複数のモデルで同じfinderメソッドの使用を指示
### 3. 関連箇所で揃えるべきパターン
**検出パターン**:
- 「こことここは実装を合わせてください」
- 「Web側とAPI側で統一してください」
- 「通常版とWebView版で揃えてください」
- 関連する複数箇所での統一を指示
**例**:
- 「Web側が `/brands/:brand_id/series` なら、API側も `/api/brands/:brand_id/series` にしてください」
- 「`/xxx`を更新したら、`/webview/xxx`も同様に更新してください」
- 「この画像アップロード処理は他のモデルでも同じパターンで実装してください」
## 出力フォーマット
**必須**: 以下のフォーマットで出力してください。他の形式（要約、報告、説明など）は禁止です。
トリガーに引っかかった場合：
```markdown
会話履歴を分析しました。以下の内容をCLAUDE.mdに追記しませんか？
追記した方がよさそうであれば、「この内容をCLAUDE.mdに追記してください」のように指示してください。
[提案する具体的な内容]
理由: [プロジェクト独自のルール / 同じような修正指示の繰り返し(N回) / 関連箇所で揃えるべきパターン]
```
トリガーに引っかからなかった場合：
```markdown
会話履歴を分析しました。CLAUDE.mdに追記すべき新しい内容は見つかりませんでした。
```
**禁止事項**:
- 「〜を修正しました」「〜を実装しました」などの完了報告形式で書かない
- 会話の要約や説明を出力しない
- 冒頭の「会話履歴を分析しました。」を省略しない
## 提案基準
### 提案する（○）
- プロジェクト全体で共有すべき普遍的なルール
- 技術的な正確性が保証できる内容
- 明確にルール化できる内容
- 今回のコード変更で新しく生まれたパターン
### 提案しない（×）
- 一時的な判断や個別ケースの対応
- 既にCLAUDE.mdに記載されている内容
- 個人の好みや一時的な試行
- 不明確または曖昧な指示
## 実行後のアクション
1. 提案内容をレビュー
2. 適切と判断した内容をCLAUDE.mdに追記することをClaudeに指示
3. コード変更と同じPRに含める
4. PRレビューでチームメンバーにレビューしてもらう
使い方
会話中に以下のコマンドを実行するだけです。
/suggest-claude-md
すると、AIエージェントが会話履歴全体を分析して、以下のような提案を出してくれます。
会話履歴を分析しました。以下の内容をCLAUDE.mdに追記しませんか？
### Web側とAPI側のルーティング統一
APIエンドポイントを設計する際は、Web側の既存ルーティング構造に合わせてください。
**原則**:
- Web側が `/brands/:brand_id/series` なら、API側も `/api/brands/:brand_id/series`
- 一貫性のあるURL構造により、コードベース全体の理解が容易になります
**例**:
```ruby
# Web側
resources :brands do
resources :series, only: %i[index show]
end
# API側（Web側に合わせる）
namespace :api do
resources :brands do
resources :series, only: [:index], module: :brands
end
end
```
理由: 関連箇所で揃えるべきパターン
エンジニアは提案内容を確認して、よければAIに「この内容をCLAUDE.mdに追記して」と指示すれば完了です。
なぜこの3つのパターンなのか？
/suggest-claude-mdコマンドは、以下の3つのパターンで提案すべきルールを判断しています。
1. プロジェクト独自のルール
標準的な実装方法ではなく、このプロジェクト特有の実装方法がある場合。Claudeは一般的な知識しか持っていないため、プロジェクト固有のルールを明示的に伝える必要があります。
2. 同じような修正指示の繰り返し
会話の中で同じ指摘を何度もしている場合。これは、そのルールがCLAUDE.mdに書かれていない証拠です。一度書いておけば、次回からは自動的に正しい実装ができます。
3. 関連箇所で揃えるべきパターン
関連する複数の箇所で実装を揃えるべきルール。実装漏れを防ぎ、コードベース全体の一貫性を保つために重要です。
これらの3つのパターンは私の経験則によるものです。できるだけあいまいでないことと、これまで1ヶ月ほど運用して提案してほしいことはだいたい漏れなく提案してくれたことを踏まえてこうなっています。ですが、本当はもっと他の書き方もあると思っていて、論文などのきちんとした裏付けがほしいところです。
今後の展開
今回は/suggest-claude-mdコマンドの使い方を紹介しました。
しかし、このコマンドを実行するのを忘れてしまったり、チームメンバー全員に確実に実行してもらうのは難しいですよね。
最初はCLAUDE.mdに「上記のパターンが検出されたときにはこのスラッシュコマンドを実行してください」と書いてみたのですが、実際には実行してくれませんでした😭
このコマンドの実行が必ず行われるようにする必要がありそうです。
次回の記事では、ClaudeのHookを使った自動実行の仕組みについて書く予定です。
- セッション終了時に自動で会話を内省
- コンテキスト圧縮前に中間チェックポイントで内省
CLAUDE.mdが自動で育っていく仕組みをお楽しみに！
Discussion