はじめに
Claude Code を開発に取り入れるチームが、ここ最近かなり増えてきているのではないでしょうか？
私はずっと GitHub Copilot を愛用していたのですが、数ヶ月前から Claude Code を使い始めました。
普段は VS Code で開発しているので、その拡張機能を入れた状態でしばらく使っていました。
便利なツールで開発が捗ることは確かなのですが、時々的外れな動作をしたり、処理に時間がかかったりして、「思っていたほど効率が上がらないな」と感じることが多々ありました。
また、X で多くの方が Claude Code を様々な方法で活用しているのを見て、自分は使いこなせていないなと感じていました。
そこで Claude Code の設定まわりを調べ、いくつかのファイル・ディレクトリを整備していった結果、開発体験が劇的に向上しました。
ざっくり言えば、新入社員のオンボーディングと同じで、Claude Code にも「育成」が必要だったということです。
本記事では、その過程を共有します。
結論から言うと、整備すべきは以下の 3 つです。
-
CLAUDE.md：プロジェクトの前提知識を渡す -
skills/：タスクごとのやり方を定義する -
agents/：専門タスク用のサブエージェントを用意する
それぞれの役割と、実際に整備した中身を順に書いていきます。
少しでも皆様の参考になりますと幸いです。
注意点
Claude Code とは
Claude Code は、Anthropic が提供する AI コーディングエージェントです。
自然言語で指示を出すだけで、ファイルの読み書き・コード生成・デバッグ・コマンド実行を自律的に行い、開発タスクを完結させてくれます。
チャット型 AI とは異なり、ローカルファイルを直接編集・実行できるため、開発効率を大きく向上させてくれるのが特徴です。
育成前に起きていた問題
VS Code の拡張機能を入れただけで使っていた頃、以下のような問題が頻発していました。
問題① 環境を理解していないので的外れなコマンドを提案してくる
「Post というテーブルを追加して」と依頼すると、
テーブルを追加するため以下を実行します
$ rails g migration CreatePosts
を実行しようとし、
Rails がインストールされていないためエラーになりました
Ruby もインストールされていないので、まずはインストールします
と返してきました。
実際にはこのプロジェクトは Docker コンテナ上で Rails を動かしており、ホスト側に Ruby や Rails をインストールする必要はありません。
プロジェクトの実行環境を理解していないため、毎回このような的外れなコマンドを提案してくることが多々ありました。
問題② プロダクトの内容を理解していない
「〜という機能を実装したいので要件定義して」と伝えても、プロダクトの内容を理解していないため、ピントのずれた回答が返ってきます。
そのたびにプロダクトのドメインやユーザー像を一から説明する必要があり、結局自分で要件定義したほうが早いという状態でした。
問題③ 毎回ゼロから把握するので時間がかかる
Claude が実装を進める際、毎回ゼロから既存のコードや仕様を把握するため、実際の修正に取りかかるまでにかなり時間がかかっていました。
Claude Code を育成するためのファイル・ディレクトリ
調べてみると、Claude Code には開発体験を向上させるためのファイル・ディレクトリがいくつも用意されています。
ざっくりまとめるとこんな構成です。
your-project/
├── CLAUDE.md # プロジェクトのルール・コンテキスト（コミット対象）
├── CLAUDE.local.md # 個人用の上書き設定（.gitignore 対象）
└── .claude/
├── settings.json # 権限・設定（コミット対象）
├── settings.local.json # 個人用設定（.gitignore 対象）
├── commands/ # /コマンド名 で呼び出せるカスタムコマンド
├── rules/ # 特定範囲に適用したいルールのファイル
├── skills/ # 特定のタスクの「やり方」を書くファイル群
└── agents/ # サブエージェントの役割（ペルソナ）
それぞれの役割を簡単に整理します。
CLAUDE.md
Claude Code が起動時に自動で読み込むコンテキストファイルです。
プロジェクトの概要・技術スタック・実行環境などを書いておくと、毎回伝えなくても Claude が前提を理解した状態で作業を進めてくれます。
commands/
Claude Code が /コマンド名 で呼び出せるカスタムコマンドを定義するディレクトリです。
よく使う指示や手順をファイルに書いておくと、毎回同じ内容を入力しなくても簡単に実行できます。
rules/
特定のファイルやディレクトリに適用したいルールを定義するためのディレクトリです。
「このディレクトリ配下では〇〇を使う」のように、適用範囲を絞ったルールをまとめておきたいときに向いています。
skills/
特定のタスクの「やり方」をまとめておくディレクトリです。
「テストを書く」「リリースする」など、決まった手順のある作業を書いておくと、Claude がその手順に沿って自動で作業を進めてくれます。
agents/
特化型のサブエージェントを定義するディレクトリです。
役割や使えるツール・モデルを書いておくと、メインの会話とは別のコンテキストで専門タスクを任せられるようになります。
似た役割のファイル・ディレクトリの棲み分け
調べていく中で「これとこれって何が違うの？」と気になったポイントがあったので、整理しておきます。
CLAUDE.md と rules/
- どちらも自動的に読み込まれる点では同じ
- プロジェクト全体に効かせたいことは
CLAUDE.mdにまとめる - 特定のファイルやディレクトリに限定して効かせたいルールは
rules/に書く、という使い分けが分かりやすい
commands/ と skills/
- 新しく作るなら
skills/を優先するのが基本 -
/コマンド名で素早く呼び出したいケースではcommands/も選択肢になる
実際に育成した内容
今回はこれらのファイル・ディレクトリの中でも、特に効果が大きい以下の 3 つを整備しました。
CLAUDE.mdskills/agents/
CLAUDE.md
CLAUDE.md は、いきなり自分で書こうとするとなかなか手が動きません。
そこで Claude Code 自身に書いてもらうのが手っ取り早いです。
このリポジトリ全体を参照して CLAUDE.md を書いて
このプロンプトを投げるだけで、ディレクトリ構成・主要なコマンド・コーディング規約などをまとめた叩き台が出力されます。
そこから不要な情報を削ったり、チーム独自のルールを追記したりして仕上げていきます。
CLAUDE.md には主に以下のような情報を書いておくと効果的です。
- プロジェクトの概要（何のプロダクトか）
- 技術スタック（Ruby のバージョン、主要 gem など）
- ディレクトリ構成と各ディレクトリの役割
- よく使うコマンド（テスト・Lint・マイグレーションなど）
- コーディング規約
- 実行環境の前提（Docker で動かしている、など）
これらを CLAUDE.md に書いておくことで、最初に挙げた問題①〜③がほぼ解消されました。
skills/
私のチームでは、現場でよく繰り返す作業を skills/ に書き出していきました。
具体的には以下のようなスキルを整備しました。
- rspec：RSpec の実行方法・書き方・モックの使い方など
- rubocop：RuboCop の実行方法・違反した時の対処方針
- update-claude-md：CLAUDE.md を最新の状態に保つための更新手順
rspec を整備しておけば、「テスト書いて」と一言伝えるだけで、チームの規約に沿った RSpec が書かれるようになります。
rubocop を整備しておけば、違反時の対処も自動で進みます。
update-claude-md を整備しておけば、「CLAUDE.md 更新して」の一言で常に最新の状態を保てるようになります。
agents/
agents/ には、専門性が高くてメインの会話とは切り離して任せたいタスク向けのエージェントを定義します。
例えば、performance-analyzer というパフォーマンス分析専門のエージェントを作成すると、N+1 クエリの調査やパフォーマンスチューニングを依頼するときに、独立したコンテキストで作業を任せられます。
メインの会話のコンテキストを圧迫せずに済むため、長時間の作業でも安定して使えるようになります。
具体例
ここまで紹介した skills/ と agents/ について、実際に整備したファイルの中身を載せておきます。
社内のドメイン情報は伏せていますが、構成はそのままなので、ご自身のプロジェクトに合わせて書き換えればそのまま使えるはずです。
update-claude-md（skills/ の例）
ファイルの中身
---
name: update-claude-md
description: リポジトリの現在の状態を調査し、CLAUDE.md の各セクションを最新の情報に更新する。CLAUDE.md の整備、更新、メンテナンスを依頼されたときに使用する。
---
リポジトリの現在の状態を調査し、CLAUDE.md を最新の情報に更新する。
## 調査対象
以下の情報源を並列で調査する:
1. **プロジェクト構成**: トップレベルのディレクトリ一覧（`ls` で確認）
2. **技術スタック**: `Gemfile` から主要 gem とバージョン、`.ruby-version` から Ruby バージョン
3. **主要モデル**: `app/models/` 配下のファイル一覧
4. **サービス層**: `app/services/` 配下のファイル一覧
5. **CI/CD**: `.github/workflows/` のワークフロー一覧
6. **ルーティング**: `config/routes.rb` の名前空間構造
## 更新手順
### 1. 現在の CLAUDE.md を読む
まず `CLAUDE.md` の全文を読み、各セクションの内容を把握する。
### 2. 差分の特定
調査結果と CLAUDE.md の各セクションを比較し、以下の差分を洗い出す:
- **プロジェクト構成**: ディレクトリの追加・削除・説明の変更
- **技術スタック**: gem の追加・削除・バージョン変更
- **主要モデル**: モデルの追加・削除・関連の変更
- **サービス層**: サービスクラスの追加・削除
- **CI/CD**: ワークフローの追加・削除
### 3. CLAUDE.md の更新
差分がある場合のみ、該当セクションを Edit ツールで更新する。
更新時のルール:
- 既存のセクション構造（見出し階層）を維持する
- 簡潔な記述を維持する（冗長な説明を追加しない）
- 差分がないセクションは一切変更しない
### 4. 結果の報告
更新した内容を差分の要約として報告する。差分がなかった場合は「CLAUDE.md は最新の状態です」と報告する。
performance-analyzer（agents/ の例）
ファイルの中身
---
name: performance-analyzer
description: Rails アプリケーションのパフォーマンス問題を分析する。N+1 クエリ、不要な eager loading、重いクエリ、メモリ効率の悪いコードを検出する。コード変更後やパフォーマンス改善の依頼時に使用する。
tools: Read, Grep, Glob, Bash
model: opus
---
あなたは Rails パフォーマンス分析の専門家です。応答は常に日本語で出力してください。
このプロジェクトは Rails アプリケーションで、以下の構造を持ちます:
- Docker Compose でローカル開発を行う
- MySQL / ActiveRecord / Paranoia（論理削除）を使用
- 親モデル → 子モデル → 孫モデル → ひ孫モデル の階層構造
- 各レベルに *Summary モデル（日次集計データ）がある
## 分析対象
指定されたファイルまたは変更されたコードに対して、以下の観点で分析する:
### 1. N+1 クエリ
- ループ内での関連モデルアクセス（`each` 内での `.association` 呼び出し）
- `includes` / `preload` / `eager_load` の不足
- ビュー（Slim テンプレート）内での暗黙的なクエリ発行
### 2. クエリ効率
- `where` なしの全件取得
- インデックスが効かないカラムでの検索（対応するマイグレーションを確認）
- `pluck` で代替できる `map` / `select`
- `count` vs `size` vs `length` の不適切な使用
- 不要な `order` や `distinct`
### 3. メモリ効率
- 大量レコードの一括読み込み（`find_each` / `in_batches` を使うべき場面）
- 不要な `to_a` による全件メモリ展開
- 巨大な配列の生成
### 4. eager loading の過不足
- 使われていない `includes`（不要な JOIN）
- ネストが深すぎる eager loading
### 5. キャッシュ
- 同一リクエスト内での重複クエリ
- `Rails.cache` や `instance variable` でキャッシュすべき計算
## 分析手順
1. 対象ファイルを読む
2. 関連するモデルの定義（`has_many`, `belongs_to`, `scope` 等）を確認する
3. 対象ファイルがコントローラの場合、対応するビューも確認する
4. 問題を特定し、修正案を提示する
## 出力形式
問題を優先度順に報告する:
- **Critical**: 本番で確実にパフォーマンス劣化を引き起こす問題（N+1、全件取得等）
- **Warning**: データ量が増えると問題になりうるもの
- **Suggestion**: より効率的な書き方の提案
各問題について:
- 該当箇所（ファイル名:行番号）
- 問題の説明
- 修正例（具体的なコード）
育成してみての所感
ここまで整備したことで、最初に挙げた問題はほぼ解消されました。
- 問題①：CLAUDE.md に実行環境を書いたことで、的外れなコマンドの提案がなくなった
- 問題②：CLAUDE.md にプロダクトの概要を書いたことで、要件定義の精度が上がった
- 問題③：CLAUDE.md にディレクトリ構成や主要コマンドを書いたことで、コードの把握にかかる時間が減った
加えて、skills/ で繰り返し作業を一言で再現できるようになり、agents/ で重い分析タスクをメインのコンテキストを圧迫せずに任せられるようになった点も、日々の作業効率に大きく効いています。
「Claude Code は入れるだけで便利になる」と思っていましたが、実際にはちゃんと育成してこそ真価を発揮するツールでした。
新入社員のオンボーディングと同じで、プロダクトの前提知識・社内のルール・タスクの進め方を渡してあげる必要がある、ということですね。
権限まわりの注意
Claude Code は通常のチャット型 AI と違い、ローカルでのファイル編集やコマンド実行まで自律的に行えます。
便利な反面、設定によっては以下のような操作も実行できてしまうため、許可する範囲はあらかじめ明確にしておくと安心です。
- 本番環境への接続を伴う操作
- ファイル削除や DB 変更といった破壊的なコマンド
- 外部サービスへデータを送信する処理
実行を許可するコマンドや、実行前後にチェックを挟む処理は .claude/settings.json の permissions や hooks で制御できるので、業務で使う場合は特に、チームでルールを揃えておくと事故を防ぎやすくなります。
まとめ
Claude Code を育成して開発体験を向上させた過程を紹介しました。
入れるだけでは真価を発揮できないのが Claude Code のポイントですが、以下の 3 つを整備することで、開発体験を大きく改善できます。
-
CLAUDE.mdでプロジェクトの前提知識を渡す -
skills/でタスクごとのやり方を定義する -
agents/でサブエージェントを用意して、コンテキストを圧迫せず専門タスクを委譲する
導入したけど思ったほど効率が上がっていない方は、ぜひ Claude Code の育成にチャレンジしてみてください。
「具体例」セクションに載せた update-claude-md スキルと performance-analyzer エージェントは、プロジェクトに合わせて書き換えればそのまま使えます。
まずはコピペで動かしてみるのが手っ取り早いと思います。
より詳しく知りたい方は、公式ドキュメントも参考にしてみてください。
皆さんが整備した CLAUDE.md / skills/ / agents/ の工夫があれば、ぜひコメントで教えていただけると嬉しいです。
最後までお読みいただき、ありがとうございました。
Discussion