AI 開発ツールの使いこなし

はじめに

AI コーディングツールは急速に進化している。しかし、ツールの選択よりも重要なのは「どのツールをどの場面で使うか」という判断だ。本モジュールでは、主要な AI 開発ツールの特性を理解し、場面に応じた最適な使い分けを学ぶ。

ツールの全体像

                   自律性が高い
                       ↑
                       |
         Claude Code ●
                       |
              Cursor ●  (Agent Mode)
                       |
              Cursor ●  (Chat Mode)
                       |
     GitHub Copilot ●  (Chat)
                       |
     GitHub Copilot ●  (Inline)
                       |
                       ↓
                   自律性が低い

  ← 小さな変更                    大きな変更 →

Claude Code

特徴

CLI ベース: ターミナルから実行する
高い自律性: ファイルの読み書き、コマンド実行を自律的に行う
マルチファイル対応: 複数ファイルにまたがる変更に強い
CLAUDE.md 対応: プロジェクトの規約を永続的に認識

セットアップ

# インストール
npm install -g @anthropic-ai/claude-code

# プロジェクトルートで実行
cd /path/to/raica-backend
claude

CLAUDE.md の設定

プロジェクトルートに CLAUDE.md を配置:

# CLAUDE.md

## Project
raica IDP backend - 医療 SaaS の患者管理システム

## Commands
- Build: make build
- Test: make test
- Lint: make lint
- Single test: go test ./src/domain/patient/... -run TestPatientSearch

## Architecture
- src/domain/ - Business logic (no external deps)
- src/api/ - HTTP handlers
- src/infra/ - DB, external services
- Dependency direction: api → domain ← infra

## Conventions
- Error wrapping: always include context
- Tests: table-driven, same directory as source
- Logging: use slog with structured fields
- See docs/conventions/ for details

効果的な使い方

1. 実装計画に基づく開発

# exec plan を先に書いておく
claude "docs/exec-plans/patient-search.md の計画に従って実装してください"

2. リファクタリング

# 複数ファイルの一括変更
claude "src/api/handlers/ 内のすべてのハンドラで、
エラーレスポンスを pkg/response.Error() を使うように統一してください。
現在の respondError() 関数を置き換える。"

3. テスト生成

claude "src/domain/patient/service.go のすべての公開メソッドに対して
テーブル駆動テストを書いてください。
既存のテストパターンは src/domain/medication/service_test.go を参照。"

4. 並列作業（Worktree 活用）

# Worktree を作成
git worktree add ../raica-patient feature/patient-api

# 別ターミナルでエージェントを実行
cd ../raica-patient
claude "患者検索 API を実装して"

# メインの作業ディレクトリでは別の作業を継続

Tips

Headless モード: -p フラグで非対話的に実行できる
コスト管理: 大規模な変更は計画を分割して段階的に実行する
出力の検証: 変更後に make check を実行して品質を確認する
コンテキスト制御: 不要なファイルを .claudeignore で除外する

Cursor

特徴

IDE 統合: VS Code ベースのエディタに組み込まれている
対話的: コードを見ながらリアルタイムで編集できる
コンテキスト自動取得: 開いているファイルが自動的にコンテキストに
複数モード: Inline, Chat, Agent の 3 つのモード

セットアップ

1. Cursor をインストール (cursor.com)
2. プロジェクトを開く
3. .cursorrules を作成（後述）

.cursorrules の設定

# .cursorrules

You are working on raica IDP backend, a medical SaaS application.

## Architecture
- Clean Architecture: domain/ has no external dependencies
- Handlers use domain interfaces, never infra directly
- See docs/architecture/overview.md for details

## Coding Style
- Go 1.22+
- Error wrapping with context
- Table-driven tests
- slog for structured logging

## Important
- Patient data requires auth middleware
- All DB queries need context and timeout
- Follow existing patterns in the same directory

モード別の使い分け

Inline Mode (Tab 補完)

コードを書いている流れの中での補完。

// コメントで意図を書くと良い補完が得られる

// SearchPatients は名前の部分一致で患者を検索する。
// cursor-based pagination をサポートする。
func (s *PatientService) SearchPatients(
    ctx context.Context,
    query string,
    cursor string,
    limit int,
) (*PaginatedResult[Patient], error) {
    // ← ここで Tab を押すと実装が提案される
}

Chat Mode (Cmd+L)

質問したり、小さな変更を依頼する。

「この関数にエラーハンドリングを追加して。
エラーメッセージには patient ID と検索クエリを含めて。」

Agent Mode (Cmd+I)

より大きな変更を自律的に実行する。

「@patient_handler.go のすべてのエンドポイントに
リクエストログを追加して。slog を使い、
method, path, duration, status_code を記録する。
既存のパターンは @medication_handler.go を参照。」

Tips

@file / @folder: コンテキストを明示的に指定できる
@docs: ドキュメントを参照させることができる
Diff view: 変更を Accept/Reject する前にdiff を確認する
イテレーション: 小さな変更を繰り返すスタイルに向いている

GitHub Copilot

特徴

幅広い IDE サポート: VS Code, JetBrains, Neovim など
インライン補完が高速: タイピングの流れを妨げない
Copilot Chat: 対話的なコード生成も可能
PR 連携: Copilot for Pull Requests でレビュー支援

効果的な使い方

関数の補完

// 関数シグネチャと doc comment を先に書くのが最も効果的

// ValidatePatientAge は患者の年齢が有効範囲内かチェックする。
// 年齢は 0-150 の範囲で、整数でなければならない。
// 無効な場合、理由を含むエラーを返す。
func ValidatePatientAge(age int) error {
    // Copilot が続きを提案
}

テストの補完

func TestValidatePatientAge(t *testing.T) {
    tests := []struct {
        name    string
        age     int
        wantErr bool
    }{
        // Copilot がテストケースを提案
    }

Copilot Chat (/explain, /fix, /test)

/explain この関数のロジックを説明して
/fix このエラーを修正して
/test この関数のテストを生成して

Tips

良いコメントが良い補完を生む: doc comment を丁寧に書く
同じファイル内の例: 類似コードが同じファイルにあると良い補完が得られる
Accept/Reject の判断を素早く: 良い提案は Accept、微妙なら自分で書く

ツールの使い分けガイド

タスク別の推奨ツール

タスク	推奨ツール	理由
新機能の実装（複数ファイル）	Claude Code	マルチファイルの自律的変更
既存コードの小さな修正	Cursor (Chat)	ファイルを見ながら対話的に
リファクタリング（大規模）	Claude Code	一貫した変更を複数ファイルに
リファクタリング（小規模）	Cursor (Agent)	IDE 内で確認しながら
テスト生成	Claude Code or Cursor	パターンに応じて
コード補完（書いている最中）	Copilot	最もスムーズ
バグ修正	Cursor (Chat)	エラーを見ながら対話的に
コードの理解	Cursor (Chat)	@file で参照しながら
設計ドキュメント作成	Claude Code	既存コードを読んで生成
PR レビュー支援	Copilot for PR	GitHub 統合

ワークフロー例: 新機能の開発

1. 設計: docs/exec-plans/ に実装計画を書く（人間）
2. 実装: Claude Code で計画に基づいて実装
3. 微調整: Cursor で細かい修正
4. テスト: Claude Code でテスト生成
5. 補完: Copilot でテストケースを追加
6. レビュー: make check で品質確認
7. PR: GitHub Copilot で PR description 生成

コスト効率の考え方

トークン消費の意識

AI ツールはトークン（≒テキスト量）に基づいて課金される。効率的に使うことでコストを抑えられる。

コスト削減のテクニック

コンテキストの最適化
- 不要なファイルを含めない
- .claudeignore / .cursorignore を設定する
- 参照ファイルはパスで指定し、内容のコピーを避ける
タスクの適切な分割
- 大きすぎるタスクは無駄な試行が増える
- 小さすぎるタスクはオーバーヘッドが増える
- 「1 つの明確な目標」が最適な粒度
CLAUDE.md / .cursorrules の活用
- 毎回のプロンプトで繰り返す情報を永続化
- プロンプトが短くなり、トークン消費が減る
適切なツールの選択
- 単純な補完に高機能ツールを使わない
- インライン補完で済むなら Copilot で十分

ROI の考え方

AI ツールのコスト < エンジニアの時間コスト

判断基準:
- 30 分以上かかるタスク → AI ツールを積極的に活用
- 5 分で終わるタスク → 自分で書いた方が早い場合も
- 繰り返しタスク → 必ず AI ツールを活用

セキュリティの考慮事項

医療 SaaS での注意点

患者データを AI に送信しない
- テストデータにはダミーデータを使用する
- 本番データベースの内容をプロンプトに含めない
認証情報の取り扱い
- .env ファイルを .claudeignore に含める
- API キーやシークレットをプロンプトに含めない
コード送信の範囲
- どのコードが AI サービスに送信されるか理解する
- 機密性の高いビジネスロジックの扱いを検討する

# .claudeignore
.env
.env.*
credentials/
secrets/
*.pem
*.key

Try This: ツールの使い分け練習

Exercise 1: Claude Code でのマルチファイル変更

docs/exec-plans/ に小さな機能の実装計画を書く
Claude Code に計画を渡して実装を依頼する
make check で品質を確認する
必要な修正を依頼する

Exercise 2: Cursor での対話的編集

既存のハンドラファイルを Cursor で開く
Chat Mode でエラーハンドリングの改善を依頼する
Diff を確認して Accept/Reject する
Agent Mode で関連するテストの更新を依頼する

Exercise 3: ツール切り替えの練習

1 つの機能開発を通じて、3 つのツールを使い分けてみる:

Claude Code: 基本的な実装を生成
Cursor: 生成されたコードを確認し、微調整
Copilot: テストケースの追加補完

Exercise 4: CLAUDE.md と .cursorrules の最適化

現在の CLAUDE.md / .cursorrules を見直す
不要な情報を削除し、必要な情報を追加する
同じプロンプトで、最適化前後の出力品質を比較する

まとめ

AI 開発ツールを効果的に使うための原則:

タスクに合ったツールを選ぶ: 万能なツールはない
永続的な設定を活用する: CLAUDE.md, .cursorrules で反復を減らす
コンテキストを最適化する: 必要な情報だけを効率的に提供する
セキュリティを意識する: 医療データの取り扱いに注意
コスト効率を考える: 適切な粒度でタスクを分割する

ツールは急速に進化する。特定のツールの使い方を覚えることよりも、「どのような場面でどのようなツールが有効か」という判断力を養うことが重要だ。

次のステップ

レビューと品質管理 - エージェント生成コードの品質管理
チームワークフロー - チームでの AI ツール活用