基本操作：Claude Codeとの正しい対話の仕方

こんにちは、松山です。
Claude Codeのインストールと設定が終わった後、多くの方が最初に思うのは：「どうやって使えばいいの？」

これは車を買って、エンジンのかけ方は分かるけど、目的地までどうやって運転すればいいか分からない状態に似ています。

今日の記事では、Claude Codeとの効果的な対話方法を教えます。AIにあなたの意図を正確に理解させて、高品質なコードを生み出させましょう。

覚えておいてください：AIとの対話も、技術なのです。

Claude Codeの作業画面

Claude Codeを起動すると、以下のような画面が表示されます：

$ claude

Claude Code v1.2.0
Connected to Claude 3.5 Sonnet

Ready to help! I can read, write, and edit files in your project.
What would you like to work on?

>

画面の説明：

• > は入力プロンプト。ここに要件を入力します
• 複数行入力に対応（Shift+Enterで改行）
• /helpを入力すると全コマンドを表示
• /exitを入力するかCtrl+Dを押すと終了

基本コマンド早見表

コマンド	機能	例
/help	ヘルプ情報を表示	/help
/clear	対話履歴をクリア	/clear
/files	現在のプロジェクトファイルを表示	/files
/exit	Claude Codeを終了	/exit
/undo	前回の操作を取り消し	/undo
/diff	ファイルの変更を表示	/diff

明確な要件を伝える5つの原則

原則1：具体的に、抽象的でなく

❌ 悪い例：

このプロジェクトを最適化して

✅ 良い例：

src/utils/parser.pyファイルのparse_json関数をリファクタリングして
要件：
1. エラー処理を追加
2. 大きなファイルの分割読み込みに対応（1回最大10MB）
3. 型アノテーションを追加
4. 既存のAPIは変更しない

なぜ？

• ファイルと関数を明確に指定
• 具体的な要件をリストアップ
• 制約条件を説明

原則2：コンテキストを提供

❌ 悪い例：

ログインAPIを書いて

✅ 良い例：

Flaskアプリケーションを開発中で、ユーザーログインAPIを追加したい：
- JWT認証を使用
- データベースはPostgreSQL、ユーザーテーブルは既存（usersテーブル）
- メールアドレスとパスワードを検証
- ログイン失敗3回で15分間アカウントロック
- 既存の/api/registerエンドポイントのコードスタイルを参考に

なぜ？

• 技術スタックを説明
• ビジネスロジックを記述
• 参考コードを指示

原則3：複雑なタスクを段階的に実行

❌ 悪い例：

完全なECサイトを作って

✅ 良い例：

ECサイトを開発したい。まず最初のステップから：
データベースschemaを設計・作成する。含むもの：
- ユーザーテーブル（users）
- 商品テーブル（products）
- 注文テーブル（orders）
- 注文明細テーブル（order_items）
MySQLを使用して、migrationファイルを生成

なぜ？

• 大きなタスクを小さなステップに分割
• 各ステップで結果を検証できる
• 方向調整が容易

原則4：期待する出力を説明

❌ 悪い例：

この関数の性能を分析して

✅ 良い例：

src/core/processor.pyのprocess_batch関数の性能ボトルネックを分析：
1. 時間計算量を指摘
2. 潜在的な性能問題を見つける
3. 具体的な最適化提案（できればコード例も）
4. ベンチマークが必要なら、テストコードを書いて

なぜ？

• 分析の具体的な内容を明確化
• 期待する出力形式を説明
• 追加要件も明記

原則5：既存コードを活用

❌ 悪い例：

APIクライアントを書いて

✅ 良い例：

src/clients/example_client.pyを確認して、
このファイルのパターンを参考に、新しいAPIクライアントを書いて：
- エンドポイント：https://api.example.com
- サポートするメソッド：GET /users, POST /users, PUT /users/:id
- 同じエラー処理とリトライ機構を使用
- 同じコードスタイルを維持

なぜ？

• AIに既存パターンを理解させる
• コードスタイルの一貫性を保つ
• 説明コストを削減

Claude Codeのワークフロー

AIのワークフローを理解すると、より良い協力ができます：

あなたの要件
    ↓
Claudeが要件を分析
    ↓
関連ファイルを読み取る（必要な場合）
    ↓
案を提示して意見を求める
    ↓
あなたが確認または調整
    ↓
Claudeが操作を実行（コード作成/修正）
    ↓
変更を表示、承認を要請
    ↓
あなたがレビューして承認
    ↓
完了！

実際の対話例

シナリオ：ログ機能の追加

あなた：app.pyにログ機能を追加して

Claude：プロジェクトにログ設定がまだないことに気づきました。いくつか質問があります：
1. ログはファイルとコンソール、どちらに出力しますか？（または両方？）
2. ログレベルの要件は（DEBUG/INFO/WARNING/ERROR）？
3. ログローテーションは必要ですか（ログファイルが大きくなりすぎないように）？
4. 特定のログフォーマット要件はありますか？

あなた：
1. ファイルlogs/app.logに出力、開発環境では同時にコンソールにも
2. 本番環境はINFO、開発環境はDEBUG
3. ログローテーションが必要、1ファイル最大10MB、30日間保持
4. フォーマットには時刻、レベル、ファイル名、行番号、メッセージを含む

Claude：了解しました。以下を行います：
1. logging設定ファイルconfig/logging.pyを作成
2. app.pyでインポートして初期化
3. 環境変数の検出を追加（開発/本番）
4. ログローテーションを設定
5. いくつかの重要なポイントにログのサンプルを追加

続けてよろしいですか？

あなた：はい、続けて

Claude：[作成/修正するファイルの内容を表示]
これらの変更で大丈夫ですか？

あなた：大丈夫です

Claude：✓ config/logging.pyを作成しました
✓ app.pyを修正しました
✓ requirements.txtを更新しました（python-logging-lokiを追加）

完了しました！app.pyで以下のようにログを記録できます：
logger.info("メッセージ")

あなた：ありがとう！主要なAPIエンドポイント全てにリクエストログを追加して

Claude：[作業を続ける...]

ポイント：

• Claudeは不明な詳細を積極的に質問
• 各操作の前に確認を求める
• 変更は透明で、いつでも調整可能

ファイル操作のコツ

AIにファイルを読み取らせる

方法1：暗黙的な読み取り（推奨）

src/api/users.pyのget_user関数を最適化して

Claudeは自動的にそのファイルを読み取ります

方法2：明示的な要求

まずsrc/models/user.pyを読んで、Userモデルの構造を理解してから、
ユーザー登録APIを書いて

方法3：複数ファイルの分析

src/ディレクトリ下のすべての.pyファイルを分析して、
エラー処理がないデータベースクエリを全て見つけて

AIの変更をレビュー

Claudeがファイルを修正する前に、diffを表示します：

--- src/api/users.py
+++ src/api/users.py
@@ -10,6 +10,12 @@

 def get_user(user_id: int):
+    """ユーザー情報を取得
+
+    Args:
+        user_id: ユーザーID
+    Returns:
+        UserオブジェクトまたはNone
+    """
     try:
         user = db.query(User).filter(User.id == user_id).first()
+        if not user:
+            logger.warning(f"User {user_id} not found")
         return user
     except Exception as e:
-        print(f"Error: {e}")
+        logger.error(f"Error fetching user {user_id}: {e}")
         return None

できること：

• yes/yを入力して確認
• no/nを入力して拒否
• 具体的な修正意見を入力：「最後の行以外は承認」

操作の取り消し

# 前回の操作を取り消し
/undo

# 最近の変更履歴を表示
/history

# 特定の履歴ポイントにロールバック
/rollback 3

実践ケース：AIに古いコードをリファクタリングさせる

シナリオ： 3年前のコードを現代化したい

ステップ1：AIにまずコードを理解させる

あなた：まずlegacy/data_processor.pyを読んで、
このコードの主な機能と潜在的な問題を教えて

Claude：ファイルを読みました。このコードの機能は：
1. CSVファイルからデータを読み取る
2. データのクリーニングと変換を行う
3. SQLiteデータベースに保存

潜在的な問題：
1. 型アノテーションがない
2. エラー処理が不完全（printのみ）
3. 非推奨のpandasメソッドを使用（例：.append()）
4. ファイルパスがハードコーディング
5. ユニットテストがない
6. SQL結合にインジェクションのリスク
7. メモリ効率が低い（ファイル全体を一度に読み込む）

優先的に処理すべき：エラー処理、SQLインジェクション、非推奨メソッド

ステップ2：リファクタリング計画を立てる

あなた：いいね！まずこの3つの問題を処理して、他は後で。
関数のインターフェースは変更しないで、呼び出し元に影響しないように。

Claude：了解です。以下を行います：
1. 適切なエラー処理とログを追加
2. パラメータ化クエリを使用してSQLインジェクションを回避
3. .append()をconcat()またはlistに変更
4. 型アノテーションを追加
5. 関数シグネチャは変更しない

リファクタリング案の準備ができました。表示しますか？

ステップ3：レビューして実行

あなた：リファクタリング後のコードを表示して

Claude：[完全なリファクタリングコードを表示]

主な変更：
- loggingモジュールを追加
- すべてのSQLをパラメータ化クエリに変更
- DataFrame操作は最新のAPIを使用
- 型アノテーションを追加
- 関数インターフェースは変更なし

これらの変更を適用しますか？

あなた：はい、適用して

Claude：✓ legacy/data_processor.pyを更新しました
✓ tests/test_data_processor.pyを作成しました（ついでに基本的なテストも書きました）

あなた：（テストを実行して検証）
あなた：完璧！ありがとう

よくある対話の落とし穴と回避方法

落とし穴1：一度に多くを要求

問題：

プロジェクト全体をリファクタリングして、パフォーマンスを最適化して、テストを追加して、
依存関係を更新して、ドキュメントを書いて、Dockerもサポートして

結果： AIが詳細を見落としたり、方向性がずれたりする可能性

正しいやり方：

まずパフォーマンス最適化から始めて、
src/core/ディレクトリ下の主なボトルネックを分析して、
最適化案を提示して

落とし穴2：説明が曖昧すぎる

問題：

ここにバグがある、修正して

結果： AIがバグが何か分からず、推測で対応する可能性

正しいやり方：

test_api.pyを実行すると、test_create_userテストが失敗：
エラーメッセージ：KeyError: 'email'
問題はapi/users.pyの45行目にあると思われる
調査して修正して

落とし穴3：コンテキストの無視

問題：

ソート関数を書いて

結果： AIはソートするデータ、言語、性能要件などが分からない

正しいやり方：

utils/helpers.pyに関数を追加して、
商品リストを価格で降順ソート、
商品オブジェクトの構造はmodels/product.pyを参照、
性能要件：10万件のデータを処理可能

クイックリファレンスカード

要件を説明するテンプレート：

[背景] XXXプロジェクトを開発中
[目標] YYY機能を実装したい
[要件]
- 具体的な要件1
- 具体的な要件2
[制約]
- 制約条件1
- 制約条件2
[参考] ZZZファイルの実装を参考にできる

コードレビューのチェックポイント：

• [ ] ロジックは正しいか？
• [ ] セキュリティリスクはないか？
• [ ] エラー処理は十分か？
• [ ] パフォーマンスは許容範囲か？
• [ ] コードスタイルは統一されているか？
• [ ] 見落としている境界ケースはないか？

次回予告

次回の『AIにあなたのプロジェクトを理解させる：コンテキスト管理のテクニック』では、以下を教えます：

• AIに大規模プロジェクトの構造を素早く理解させる方法
• 複数ファイル変更シナリオでコンテキストを保つ方法
• 複雑なコード依存関係を説明する方法
• 実践：AIに実際のプロジェクトで新機能を追加させる

対話のテクニックをマスターしたら、次はAIにプロジェクト全体を理解させましょう！

---

💬 インタラクションタイム

今日の内容で一番の収穫は何でしたか？

• A. 要件を明確に説明する方法を学んだ
• B. AIのワークフローを理解した
• C. ファイル操作とレビューのテクニックを習得
• D. 自分の今までの質問の仕方が間違っていたことに気づいた

ミニ演習： 今日学んだテクニックを使って、Claude Codeに小さなタスクを完了させてみて、コメント欄で体験をシェアしてください！

このブログをフォローして、AI開発スキルを継続的に向上させましょう！ 🚀

---

このシリーズについて

これは「AI駆動開発実践」シリーズの第3回です。前2回でClaude Codeを学びインストールを完了し、今回は対話のテクニックをマスターしました。次回はさらに深い実践に入ります！

練習を始めましょう。次回もお楽しみに！ 👋