はじめに

ソフトウェア開発の現場にいる皆さん、日々の業務フローを思い返してみてください。

1. GitHub Issue や Jira のチケットで仕様を確認する。
2. 内容を理解し、ローカルで新しいブランチを作成する。
3. 関連ファイルを特定し、エディタで開く。
4. 仕様に沿ってコードを書き、修正する。
5. 動作確認のためのテストコードを記述する。
6. ローカルでテストを実行し、問題ないことを確認する。
7. 変更をコミットし、リモートにプッシュする。
8. ブラウザで GitHub を開き、Pull Request (PR) を作成する。

この一連の流れは、私たちエンジニアにとって日常茶飯事です。しかし、このプロセスには多くのコンテキストスイッチ（思考の切り替え）が含まれており、特にプロジェクトの初期段階や、新しいコードベースに触れる際には、仕様の理解や関連ファイルの特定といった「準備運動」に多くの時間が費やされます。

「Issue の内容を理解したら、あとはAIが自動でコードを書いてPRまで作ってくれたら最高なのに…」

そんな未来の夢物語が、GitHub Copilot Workspace の登場によって、現実のものとなりつつあります。この記事では、GitHub がテクニカルプレビューとして公開した Copilot Workspace を徹底的に解説し、Issue（仕様書）を起点として、AIと共に実装計画を立て、コードを生成し、Pull Request を作成するまでの一気通貫の開発フローを実践的なハンズオン形式で紹介します。

この記事を読み終える頃には、あなたは Copilot Workspace の強力な機能を理解し、自身の開発プロセスを劇的に効率化させるための具体的なイメージを描けるようになっているでしょう。

なぜ今、Copilot Workspaceが重要なのか？

GitHub Copilot が登場し、私たちのコーディング体験は大きく変わりました。関数名やコメントから意図を汲み取り、驚くほど的確なコードを補完してくれる Copilot は、もはや手放せない相棒となっているエンジニアも多いでしょう。その後、Copilot Chat が登場し、エディタ内で対話形式でコードに関する質問やリファクタリングの相談ができるようになりました。

しかし、これまでの Copilot は、あくまで「コーディング」という実装フェーズに特化した支援ツールでした。開発プロセス全体を見渡すと、実装の前には「仕様の理解」「設計」「実装計画」といった上流工程が存在し、実装の後には「テスト」「PR作成」「レビュー」といった下流工程が存在します。

ここに、現代の開発プロセスが抱える根深い課題があります。

• コンテキストスイッチのオーバーヘッド: Issue、設計ドキュメント、エディタ、ターミナル、ブラウザ… 開発者は複数のツールやウィンドウを絶えず行き来する必要があり、そのたびに集中力が削がれます。
• 定型作業の繰り返し: ブランチ作成、ボイラープレートコードの記述、基本的なテストケースの作成など、創造的とは言えない定型作業に多くの時間が奪われています。
• オンボーディングの壁: 新しいメンバーがプロジェクトに参加した際、広大なコードベースのどこから手をつければ良いのかを把握するのは非常に困難です。

GitHub Copilot Workspace は、これらの課題を解決するために生まれました。それは単なるコード補完ツールではありません。Issue を起点として、開発タスクの全体像をAIが把握し、人間と対話しながら「仕様の明確化」「実装計画の立案」「コード生成」「テスト」までを半自動的に実行する、いわば「AI搭載の開発環境」 なのです。

Copilot Workspace は、開発プロセスの上流から下流までをシームレスに繋ぎ、エンジニアを煩雑な作業から解放します。これにより、エンジニアはより創造的で、本質的な価値を生み出す「設計」や「アーキテクチャの検討」「複雑なビジネスロジックの実装」に集中できるようになるのです。これは、開発の生産性を根底から覆すポテンシャルを秘めた、大きなパラダイムシフトと言えるでしょう。

Copilot Workspaceによる開発フロー徹底解説

それでは、実際に Copilot Workspace を使って Issue から PR 作成までを駆け抜けるプロセスを、具体的なハンズオン形式で見ていきましょう。

Copilot Workspace の全体像

Workspace のフローは、大きく分けて以下の3つのステップで構成されています。この概念を理解することが、Workspace を使いこなすための鍵となります。

graph TD;
    A[📝 GitHub Issue] --> B(🚀 Copilot Workspaceを起動);
    B --> C{1. Spec<br>(仕様の確認・編集)};
    C -- AIと対話し仕様を洗練 --> D{2. Plan<br>(実行計画の生成・編集)};
    D -- 計画に基づき実行 --> E{3. Implementation<br>(コードの自動生成・修正)};
    E -- 人間によるレビュー・微修正 --> F[✅ Pull Request作成];

1. Spec (仕様): Workspace はまず Issue の内容を読み込み、タスクの目的や要件を自然言語でまとめた「仕様」を生成します。開発者はこの仕様を確認し、AI とのチャットを通じて内容をより正確かつ詳細なものに洗練させていきます。
2. Plan (計画): 洗練された仕様に基づき、AI は「どのファイルを新規作成するか」「どのファイルをどう変更するか」「どのコマンドを実行するか」といった具体的な「実行計画」を立案します。この計画はステップバイステップで表示され、開発者は内容を確認・編集できます。
3. Implementation (実装): 開発者が計画を承認すると、Workspace は計画に沿ってファイルの作成、コードの生成・編集、コマンドの実行などを自動で行います。生成されたコードの差分（diff）は即座に確認でき、必要に応じて Workspace 内のエディタやターミナルで直接修正を加えることが可能です。

この**「仕様定義 → 計画立案 → 実装」**という反復的なプロセスこそが、Copilot Workspace の中核です。

実践！IssueからPR作成までのハンズオン

今回は、簡単な REST API を提供する Node.js (Express) プロジェクトを例に、新しいエンドポイントを追加するタスクを Workspace で実行してみましょう。

前提:

• GitHub Copilot Workspace のテクニカルプレビューにアクセスできること。
• Node.js と Express で作られたシンプルな Web API のリポジトリが存在すること。

Step 0: 課題となる Issue の準備

まずは、開発の起点となる Issue を作成します。AI が理解しやすいように、具体的かつ明確に記述することがポイントです。

Issue Title: feat: GET /api/v1/users エンドポイントを追加

Issue Body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

### 概要
ユーザーの一覧を取得するための新しいAPIエンドポイント `GET /api/v1/users` を追加します。

### 背景
クライアントアプリケーションがユーザー情報を一覧表示するために、このAPIが必要です。

### 受け入れ条件
- HTTP GETリクエストを `/api/v1/users` パスで受け付けること。
- レスポンスはJSON形式であること。
- レスポンスボディは、`data` というキーを持つオブジェクトであること。
- `data` の値は、以下の構造を持つユーザーオブジェクトの配列であること。
  - `id` (number)
  - `name` (string)
  - `email` (string)
- 現状、データベース連携は不要。モックデータとして3人分のユーザー情報を返すこと。
- エラーハンドリングは考慮しなくてよい。
- 既存のルーティングファイル (`src/routes/index.js`) に新しいルートを追加すること。

Step 1: Workspace の起動

作成した Issue ページにアクセスすると、Copilot のアイコンと共に「Open in Workspace」というボタンが表示されます（プレビュー有効時）。これをクリックして Workspace を起動します。

(画像はイメージです)

Step 2: “Spec” - 仕様の定義と洗練

Workspace が起動すると、AI が Issue の内容を解析し、以下のような「Spec」を自動生成します。

Initial Specification

The goal is to add a new API endpoint GET /api/v1/users. This endpoint should return a mocked list of users in a specific JSON format.

Acceptance Criteria:

• The endpoint must handle GET requests to /api/v1/users.
• The response should be a JSON object with a data key.
• The data key should contain an array of user objects.
• Each user object must have id, name, and email.
• The implementation should use mock data for three users.
• The new route should be added to the existing file src/routes/index.js.

この時点で、AI がタスクを正しく理解していることが分かります。もし、何か補足したい情報があれば、下部のチャットボックスから AI に指示を出します。

例えば、返すモックデータに具体的な名前を指定したい場合、以下のようにチャットします。

あなた:

Use the following names for the mock data: Alice, Bob, and Charlie.

すると、AI はこの指示を理解し、Spec を更新します。この対話を通じて、実装に入る前に AI との認識合わせを完璧に行うことができます。

Step 3: “Plan” - 実行計画の立案

Spec が固まったら、AI はそれを実現するための具体的な「Plan」を作成します。

Execution Plan

I will perform the following steps to implement the feature:

1. Modify file src/routes/index.js: I will add a new route handler for GET /api/v1/users. This handler will define the mock user data and send it as a JSON response in the required format.

2. Create file tests/users.test.js: To ensure the new endpoint works correctly, I will create a new test file. This test will use a library like supertest to make a request to the new endpoint and assert that the response status is 200 and the body matches the expected structure.

この計画は非常に理にかなっています。実装ファイルの変更だけでなく、その動作を保証するためのテストファイルの作成まで提案してくれている点は素晴らしいです。もし、テストが不要な場合や、別のファイルにロジックを分割したい場合は、この Plan を手動で編集したり、AI に修正を依頼したりすることも可能です。

Step 4: “Implementation” - AIによる自動実装

Plan に納得したら、「Run」ボタンをクリックします。すると、Workspace が計画に沿ってコードの生成とファイルの作成を自動的に開始します。処理が完了すると、変更内容が差分（diff）形式で表示されます。

src/routes/index.js の変更差分:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

  const express = require('express');
  const router = express.Router();

  /* GET home page. */
  router.get('/', function(req, res, next) {
    res.json({ title: 'Express' });
  });

+ router.get('/api/v1/users', (req, res) => {
+   const mockUsers = [
+     { id: 1, name: 'Alice', email: 'alice@example.com' },
+     { id: 2, name: 'Bob', email: 'bob@example.com' },
+     { id: 3, name: 'Charlie', email: 'charlie@example.com' },
+   ];
+
+   res.status(200).json({ data: mockUsers });
+ });
+
  module.exports = router;

tests/users.test.js の新規作成:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

const request = require('supertest');
const app = require('../src/app'); // Express app instance

describe('GET /api/v1/users', () => {
  it('should return a list of users', async () => {
    const res = await request(app).get('/api/v1/users');
    expect(res.statusCode).toEqual(200);
    expect(res.body).toHaveProperty('data');
    expect(Array.isArray(res.body.data)).toBe(true);
    expect(res.body.data.length).toBe(3);
    expect(res.body.data[0]).toHaveProperty('id');
    expect(res.body.data[0]).toHaveProperty('name');
    expect(res.body.data[0]).toHaveProperty('email');
  });
});

生成されたコードは、概ね Issue の要件を満たしています。ここで、Workspace 内に組み込まれたターミナルを開き、テストを実行してみましょう。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

$ npm install
$ npm test

> tests/users.test.js
✓ should return a list of users (5ms)

Test Suites: 1 passed, 1 total
Tests:       1 passed, 1 total
Snapshots:   0 total
Time:        0.5s

テストが成功しました。もしコードに修正が必要な場合は、Workspace 上のエディタで直接編集できます。例えば、レスポンスコードを 201 に変えたい場合、エディタで res.status(200) を res.status(201) に書き換えるだけです。

Step 5: PRの作成

実装とテストに問題がないことを確認したら、画面上部にある「Create Pull Request」ボタンをクリックします。

すると、PR 作成画面に遷移します。驚くべきことに、PR のタイトルと説明文も、AI が Issue とコードの変更内容を基に自動で生成してくれます。

PR Title (自動生成): feat: Add GET /api/v1/users endpoint

PR Body (自動生成):

This pull request introduces a new endpoint GET /api/v1/users to fetch a list of users.

Changes:

• Added a new route to src/routes/index.js to handle the request.
• The endpoint returns a hardcoded list of three users as mock data.
• Added a new test file tests/users.test.js to verify the functionality of the new endpoint.

Closes #123 (Issue番号)

内容を確認し、必要であれば追記して PR を作成します。これで、Issue の起票から PR のマージ準備まで、ほとんどの作業を GitHub の中で、AI の支援を受けながら完結させることができました。

メリットとデメリット

Copilot Workspace は革命的なツールですが、万能ではありません。そのメリットと、現時点でのデメリットや注意点を冷静に評価してみましょう。

メリット

• 圧倒的な生産性向上: これまで手作業で行っていたブランチ作成、ファイル検索、ボイラープレートの記述、テストの雛形作成、PR の文章作成といった一連の定型作業がほぼ自動化されます。これにより、エンジニアはタスクの本質的な部分に集中できます。
• コンテキストスイッチの撲滅: Issue の確認から PR 作成まで、すべての作業が Workspace という単一の環境で完結します。ツール間を行き来する必要がなくなり、思考の分断が起こりにくくなります。
• スムーズなオンボーディング: 新しいプロジェクトに参加した際、Issue を Workspace で開けば、AI が関連ファイルを特定し、変更計画まで立ててくれます。これにより、コードベースの全体像を把握し、最初の貢献を行うまでの時間を大幅に短縮できます。
• 設計と実装の分離: 「Spec」と「Plan」のステップを踏むことで、いきなりコーディングを始めるのではなく、「何を」「どのように」作るのかを明確にしてから実装に進むという、良い開発習慣が自然と身につきます。

デメリット / 注意点

• AI が生成するコードの品質: 生成されるコードは常に完璧ではありません。バグを含んでいたり、プロジェクトのコーディング規約に沿っていなかったり、最適な設計でない場合もあります。最終的な品質を担保するのは、あくまで人間のエンジニアの役割であり、コードレビューの重要性は変わりません。
• 複雑なタスクへの対応限界: 複数のファイルを横断する大規模なリファクタリングや、ドメイン知識が深く要求される複雑なビジネスロジックの実装など、高度な抽象的思考が必要なタスクにはまだ対応しきれない場面があります。
• 思考停止のリスク: AI に頼りすぎることで、エンジニア自身が「なぜこの変更が必要なのか」「他にどんな実装方法があるか」といったことを深く考えなくなる危険性があります。Workspace はあくまで「優秀なアシスタント」であり、思考の主体は人間であるべきです。
• テクニカルプレビュー段階: 現在はまだプレビュー版であり、機能が変更されたり、動作が不安定になったりする可能性があります。本番の重要なプロジェクトに全面的に導入するには、今後の動向を注視する必要があります。

現場で使える実践的なTips

Copilot Workspace のポテンシャルを最大限に引き出すための、いくつかの実践的なヒントを紹介します。

1. 「良いIssue」が「良い実装」を生む

Workspace の出発点は Issue です。AI の性能はインプットの質に大きく左右されるため、精度の高い実装を引き出すためには、AI が理解しやすい Issue を書くことが非常に重要です。

• 背景 (Why) を書く: 「何をするか (What)」だけでなく、「なぜそれが必要なのか (Why)」を記述することで、AI がタスクの文脈をより深く理解し、適切な実装を提案しやすくなります。
• 受け入れ条件 (Acceptance Criteria) を明確にする: 「〜であること」という形式で、タスク完了の定義を箇条書きで具体的に示しましょう。これは AI にとっての仕様書そのものになります。
• 専門用語やファイル名をヒントとして与える: 「UserService クラスを使ってデータを取得すること」「設定は config/features.json を参照すること」のように、コードベース固有の情報を与えると、AI の計画 (Plan) の精度が劇的に向上します。

2. “Plan” を対話的に育てる

AI が生成した最初の Plan が完璧であることは稀です。Plan を鵜呑みにせず、レビューし、AI との対話を通じて改善していくプロセスが重要です。

• ステップの分割・追加を指示する: 「ステップ2を、ロジック部分とルーティング部分の2つに分割して」「テストを実行するステップを最後に追加して」のように、計画をより細かく、より安全に実行できるように指示します。
• 代替案を尋ねる: 「この実装方法以外に、もっと良い方法はありますか？」と尋ねることで、自分では思いつかなかったアプローチを AI が提案してくれることがあります。

3. ローカル環境とのハイブリッド活用

Workspace は強力ですが、全ての作業をそこで完結させる必要はありません。特にデバッグや複雑な修正には、使い慣れたローカルのエディタが適している場合もあります。

Workspace で大枠の実装（80%）を自動生成させ、その後ローカルにブランチをチェックアウトして、細部の調整やデバッグ（残りの20%）を行う、というハイブリッドな使い方が非常に効率的です。

まとめ

GitHub Copilot Workspace は、単なるコーディング支援ツールではなく、開発プロセスそのものを再定義する可能性を秘めたゲームチェンジャーです。Issue という「要求」から Pull Request という「成果物」までを、AI と人間が協調しながらシームレスに繋ぐことで、開発の生産性と体験を新たな次元へと引き上げます。

もちろん、このツールはまだ発展途上であり、人間のエンジニアによるレビューや設計、最終的な意思決定の重要性が失われることはありません。むしろ、AI をいかにうまく「操縦」し、その能力を最大限に引き出すかが、これからのエンジニアに求められる新しいスキルセットになるでしょう。

私たちの役割は、「一行一行コードを書く作業者」から、「AI という優秀な部下を持つプロジェクトマネージャー兼アーキテクト」 へと変化していくのかもしれません。

GitHub Copilot Workspace がもたらす未来の開発スタイルは、もうすぐそこまで来ています。ぜひテクニカルプレビューに登録し、この新しい開発体験をいち早くご自身のプロジェクトで試してみてください。きっと、開発の未来を垣間見ることができるはずです。

はじめに

「もっと速く、もっと賢くコーディングしたい」 「GitHub Copilotは便利だけど、もう少し踏み込んだサポートが欲しい」 「新しい技術のキャッチアップに時間がかかりすぎる」

もしあなたがエンジニアとして、このような課題を感じているなら、この記事はあなたのためのものです。AIがコーディングの世界を根底から変えつつある今、私たちは単にコードを書くだけでなく、「AIをいかに使いこなすか」という新しいスキルセットを求められています。

GitHub Copilotが「AIによるコード補完」という新しい常識を作りましたが、その次世代を担う存在として注目されているのが、AIネイティブエディタCursorです。

Cursorは、単なる補完ツールではありません。あなたのプロジェクト全体を理解し、対話を通じてリファクタリング、デバッグ、ドキュメント生成、さらには複数ファイルにまたがる複雑な機能実装までをサポートしてくれる、まさに「AIペアプログラマー」と呼ぶにふさわしいエディタです。

この記事では、VS Codeをベースに開発されたCursorの基本的な使い方から、最新の強力な機能、そしてVS Code + GitHub Copilotから移行する具体的なメリットまで、現場で即戦力となる実践的なノウハウを余すところなく解説します。AI時代の新しいコーディングスタイルを、Cursorと共に体験してみましょう。

なぜ今、Cursorなのか？ AI時代の開発環境の進化

ソフトウェア開発の歴史は、生産性向上のためのツールの進化の歴史でもあります。テキストエディタから始まり、シンタックスハイライト、コード補完、デバッガなどを統合したIDE（統合開発環境）が登場しました。そして、バージョン管理システムとしてGitがデファクトスタンダードとなり、私たちの開発スタイルは大きく変わりました。

そして2021年、GitHub Copilotが登場し、開発の世界に再び大きなパラダイムシフトが訪れます。大規模言語モデル（LLM）を活用し、コメントや文脈からコードを自動生成するCopilotは、多くの開発者に衝撃を与え、瞬く間に普及しました。

しかし、Copilotの登場は始まりに過ぎませんでした。Copilotは主に「補完」という形で開発者をサポートしますが、開発者が抱える課題はそれだけではありません。

• 大規模なリファクタリング: 複数ファイルにまたがる変数名や関数シグネチャの変更は、依然として骨の折れる作業です。
• 複雑なバグの調査: エラーメッセージやスタックトレースを読み解き、原因を特定するには深い知識と経験が必要です。
• コードベース全体の理解: 新しく参画したプロジェクトや、巨大なレガシーコードを理解するには膨大な時間がかかります。
• 設計から実装への落とし込み: 「ログイン機能を実装する」といった抽象的な要件から、具体的なファイル構成やコードを書き起こすのは創造的な思考を要します。

これらの課題は、単純なコード補完だけでは解決が難しい領域です。ここに、AIネイティブエディタという新しいコンセプトが登場する必然性がありました。

Cursorは、この「Copilotの次」を求める開発者のニーズに応えるために生まれました。エディタのUI/UXの深いレベルでAIを統合し、チャットインターフェースを通じて、より高レベルで双方向的なやり取りを可能にしたのです。VS Codeの強力なエコシステム（拡張機能、設定、キーバインド）をそのまま継承しているため、既存の環境からほぼストレスなく移行できる点も、多くの開発者に受け入れられている大きな理由です。

今、Cursorを学ぶことは、AIを最大限に活用した新しい開発ワークフローを身につけ、来るべきAI時代の開発競争で一歩先を行くための、最も効果的な投資と言えるでしょう。

Cursorの核心機能：具体的な使い方とコード例

Cursorの真価は、その多彩なAI機能にあります。ここでは、基本的な機能から最新の強力な機能まで、具体的なコード例を交えながら徹底的に解説します。

1. すべての基本「AIチャット (Cmd+K)」

Cursorの最も基本的な機能が、選択したコードに対してAIと対話できるチャット機能です。使い方は簡単。コードを選択し、Cmd+K (Windows/Linuxでは Ctrl+K) を押すだけです。

ケース1: コードの生成と編集

例えば、TypeScriptでユーザー情報を取得する非同期関数を書きたいとします。まずは空のファイルで Cmd+K を押し、次のように指示します。

プロンプト:

TypeScriptで、ユーザーIDを引数に取り、`https://api.example.com/users/{id}` からユーザー情報を取得する非同期関数 `fetchUser` を作成してください。fetch APIを使い、取得したデータはUser型として返してください。User型も定義してください。エラーハンドリングもお願いします。

すると、Cursorは以下のようなコードを生成し、ワンクリックでファイルに挿入してくれます。

生成されたコード:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

interface User {
  id: number;
  name: string;
  email: string;
  username: string;
}

async function fetchUser(userId: number): Promise<User> {
  try {
    const response = await fetch(`https://api.example.com/users/${userId}`);

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    const user: User = await response.json();
    return user;
  } catch (error) {
    console.error('Failed to fetch user:', error);
    throw error; // or handle it gracefully
  }
}

ケース2: リファクタリング

次に、既存のコードをリファクタリングしてみましょう。以下のような、少し冗長なコードがあるとします。

Before:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

function getUserProfile(user) {
  if (user) {
    if (user.profile) {
      if (user.profile.name) {
        return user.profile.name;
      } else {
        return 'No name';
      }
    } else {
      return 'No profile';
    }
  } else {
    return 'No user';
  }
}

この関数を選択して Cmd+K を押し、プロンプトを入力します。

プロンプト:

このコードを、Optional Chaining (?.) と Nullish Coalescing (??) を使ってリファクタリングしてください。

After (生成されたコード):

1
2
3

function getUserProfile(user) {
  return user?.profile?.name ?? 'No name';
}

※プロンプト次第では 'No user' や 'No profile' のケースも考慮した、より丁寧なコードを提案させることも可能です。

このように、対話形式で瞬時にコードの改善が可能です。

2. コードベース全体を理解する「@を使ったチャット」

Cursorの真骨頂とも言えるのが、コードベース全体をコンテキストとしてAIと対話できる機能です。チャットパネル（Cmd+L または Ctrl+L で開く）で @ をタイプすると、ファイル名やシンボル（関数名、クラス名など）を補完してくれます。

これにより、AIはあなたが指定したファイルや関数の内容を正確に理解した上で回答を生成します。

シナリオ: あなたはECサイトのプロジェクトに新しく参加しました。決済処理の流れを理解したいと考えています。

プロンプト:

@src/services/paymentService.ts と @src/controllers/orderController.ts の内容を参考にして、ユーザーが商品をカートに入れてから決済が完了するまでの大まかな処理フローを教えてください。特に、`processPayment` 関数がどのように呼び出されているかに注目して説明してください。

AIは指定された2つのファイルを読み込み、以下のように回答してくれます。

AIの回答（例）:

承知しました。`paymentService.ts` と `orderController.ts` を分析した結果、決済フローは以下のようになっていると推測されます。

1.  **注文作成 (`orderController.ts`):**
    *   ユーザーがチェックアウトボタンを押すと、フロントエンドから `/api/orders` のようなエンドポイントにリクエストが送られます。
    *   `orderController.ts` 内の `createOrder` ハンドラがリクエストを受け取ります。
    *   このハンドラは、カート情報から注文オブジェクトを作成し、データベースに保存します。

2.  **決済処理の呼び出し (`orderController.ts` -> `paymentService.ts`):**
    *   `createOrder` ハンドラの最後で、`paymentService.ts` に定義されている `processPayment` 関数を呼び出します。
    *   この時、引数として注文IDと合計金額を渡しています。

3.  **決済実行 (`paymentService.ts`):**
    *   `processPayment` 関数は、外部の決済ゲートウェイ（例: Stripe）のAPIを呼び出します。
    *   決済が成功すると、決済IDを返し、注文ステータスを「支払い済み」に更新します。
    *   失敗した場合は、エラーをスローし、`orderController` 側でトランザクションがロールバックされます。

このように、`@`機能を使うことで、複数のファイルにまたがる複雑なロジックも、人に質問するような感覚で素早く理解できます。

### 3. AIによる自動デバッグ「エラーメッセージを貼り付け」

開発中に遭遇する厄介なエラーメッセージ。もう一人で悩む必要はありません。ターミナルに出力されたエラーメッセージやスタックトレースをコピーし、チャットパネルに貼り付けて質問するだけで、AIが原因と解決策を提案してくれます。

**シナリオ:** Node.jsアプリケーションを実行したら、以下のようなエラーが出ました。

Error: Cannot find module ’express' Require stack:

• /Users/user/my-project/app.js at Function.Module._resolveFilename (node:internal/modules/cjs/loader:933:15) at Function.Module._load (node:internal/modules/cjs/loader:778:27) at Module.require (node:internal/modules/cjs/loader:1005:19) at require (node:internal/modules/cjs/helpers:102:18) at Object. (/Users/user/my-project/app.js:1:17) …

**プロンプト:**

このエラーの原因と解決方法を教えてください。 @package.json

`@package.json` を含めることで、プロジェクトの依存関係もコンテキストに加えます。

**AIの回答（例）:**

このエラー Error: Cannot find module 'express' は、Node.jsが express モジュールを見つけられないことを示しています。原因は主に2つ考えられます。

1. express がインストールされていない: package.json を確認しましたが、dependencies または devDependencies に express が記載されていません。

2. node_modules が存在しない、または破損している: package.json に記載があっても、npm install を実行していない可能性があります。

解決策: 以下のコマンドをターミナルで実行してください。

1

npm install express

これにより express パッケージがインストールされ、package.json にも依存関係が追加されます。その後、再度アプリケーションを実行してみてください。

このように、非常に具体的で実行可能な解決策を提示してくれます。

### 4. 複数ファイルを一括生成・編集「Code Generation (Cmd+Shift+L)」

これはCursorの最新機能の中でも特に強力なものです。単一のプロンプトで、複数の新しいファイルを作成したり、既存のファイルを横断的に編集したりできます。

**シナリオ:** React + Expressで簡単なTodoアプリに、「Todoの編集機能」を追加したい。

`Cmd+Shift+L` を押して、Code Generationモードに入り、以下のプロンプトを入力します。

**プロンプト:**

ReactのTodoアプリに編集機能を追加します。以下の変更を加えてください。

1. @src/components/TodoItem.jsx に、編集ボタンと編集フォームを追加します。編集ボタンを押すと、テキストがinputに変わり、Enterキーで更新を確定できるようにしてください。更新処理は handleUpdateTodo という名前で親コンポーネントからpropsで受け取ります。

2. @src/App.jsx に、handleUpdateTodo 関数を実装してください。この関数はidと新しいテキストを受け取り、todosステートを更新します。

3. @server/index.js (Expressサーバー) に、Todoを更新するための PUT /api/todos/:id エンドポイントを追加してください。

このプロンプトを実行すると、Cursorは変更が必要な3つのファイルを特定し、それぞれの変更差分（diff）を並べて表示します。

```diff
--- a/src/components/TodoItem.jsx
+++ b/src/components/TodoItem.jsx
// ... (編集モードの状態管理と、編集用inputを追加するコード)

--- a/src/App.jsx
+++ b/src/App.jsx
// ... (handleUpdateTodo関数の実装を追加するコード)

--- a/server/index.js
+++ b/server/index.js
// ... (app.put('/api/todos/:id', ...) の実装を追加するコード)

内容を確認し、「Apply」ボタンを押すだけで、3つのファイルすべてに一括で変更が適用されます。この機能は、新しい機能の追加や大規模なAPIの変更など、複数のファイルに影響が及ぶタスクの生産性を劇的に向上させます。

メリットとデメリット：VS Code + Copilotとの比較

Cursorの導入を検討する上で、既存の環境（特にVS Code + GitHub Copilot）との比較は欠かせません。

Cursorのメリット

1. コンテキスト認識能力の高さ: @機能により、AIに「どの情報を見てほしいか」を明示的に伝えられる点が最大の強みです。これにより、AIの回答精度が劇的に向上し、大規模プロジェクトでも的確なサポートを受けられます。

2. タスク実行能力の高さ: 単なるコード生成に留まらず、「リファクタリング」「デバッグ」「機能追加」といった、より高レベルなタスクを依頼できます。特にCmd+Shift+Lによる複数ファイル操作は、Copilotにはない強力な機能です。

3. シームレスなVS Code体験: 使い慣れたキーバインド、テーマ、そして何百もの拡張機能がそのまま動作します。学習コストをほとんどかけずに、AIの恩恵だけを追加できるのは非常に大きな利点です。

Cursorのデメリットと注意点

1. 有料プランの必要性: 無料版でも基本的な機能は使えますが、GPT-4oのような最新かつ高速なモデルを快適に使うには、Proプラン（月額$20）への加入が推奨されます。これはGitHub Copilot（月額$10）よりも高価です。

2. ネットワーク依存: 全てのAI機能はクラウド上のモデルを利用するため、オフライン環境では使用できません。

3. セキュリティとプライバシー: 企業によっては、ソースコードを外部のAIサービスに送信することを禁止している場合があります。Cursorはプライバシーポリシーを公開しており、プライベートなコードはモデルのトレーニングには使用しないと明言していますが、導入前には必ず所属組織のセキュリティポリシーを確認する必要があります。（設定で、ローカルファイルからの情報送信を一部制限するオプションもあります）

結論として、GitHub Copilotは優れた「オートコンプリート」 であり、Cursorはより能動的な「AIアシスタント」 と言えるでしょう。単純なコード補完で満足しているならCopilotで十分かもしれませんが、AIと対話し、より複雑なタスクを任せたいのであれば、Cursorへの移行は生産性を飛躍させる価値が十分にあります。

現場で使える実践的なTips

Cursorを最大限に活用するためには、いくつかのコツがあります。ここでは、明日からすぐに使える実践的なTipsを紹介します。

1. 効果的なプロンプトの技術

AIの性能はプロンプトの質に大きく左右されます。以下の点を意識するだけで、生成されるコードの質が格段に上がります。

• 役割を与える (Act as…): 「あなたは経験豊富なReactエンジニアです」「あなたはセキュリティ専門家です」のように、AIに役割を与えることで、その分野に特化した回答が得られやすくなります。
• コンテキストを豊富に与える: @で関連ファイルを指定するだけでなく、前提となる技術スタック、コーディング規約、達成したい目標などを具体的に記述します。
• 出力形式を指定する: 「Markdown形式で表にして」「JSDocコメントを付けて」「テストコードはJestを使って」のように、希望するアウトプットの形式を明確に指示します。
• ステップ・バイ・ステップで考えさせる: 複雑なタスクを依頼する際は、「まず、必要なコンポーネントをリストアップしてください。次に、それぞれのpropsを設計してください。最後に、コードを生成してください」のように、思考のプロセスを段階的に指示すると、より精度の高い結果が得られます。

2. レガシーコードのリファクタリングに活用する

ドキュメントが少なく、複雑に絡み合ったレガシーコードの改善は、Cursorの得意分野です。

• コードの要約: 巨大な関数を選択し、「この関数の役割を箇条書きで説明して」と依頼するだけで、処理内容を素早く把握できます。
• 責務の分離: 「この関数は責務が多すぎます。関心の分離の原則に基づいて、複数の関数に分割してください」と依頼すれば、リファクタリングの第一歩を自動化できます。
• テストコードの生成: 既存のコードに対して「この関数のためのユニットテストをJestで書いてください。正常系と異常系の両方をカバーしてください」と依頼することで、安全にリファクタリングを進めるためのテストハーネスを効率的に作成できます。

3. 新しい言語・フレームワークの学習ツールとして使う

新しい技術を学ぶ際、公式ドキュメントとサンプルコードを行き来するのは大変です。Cursorを使えば、エディタ内で対話しながら学習を進められます。

• サンプルコードの解説: Webからコピーしてきたコードを選択し、「このコードが何をしているのか、一行ずつ詳しく解説してください」と質問します。
• 文法の比較: 「Pythonのリスト内包表記に似たことを、JavaScriptの配列メソッドで行うにはどうすればいいですか？」といった、言語間の比較質問も有効です。
• 「お作法」を学ぶ: 「SvelteKitの流儀に従って、APIエンドポイントを作成するコードを書いてください」のように、フレームワーク特有のベストプラクティスに沿ったコードを生成させることができます。

4. コードレビューの補助として使う

人間の目だけでは見逃しがちな問題を、AIに指摘させることも可能です。プルリクエストの対象コードをチャットに貼り付け、以下のようなプロンプトを試してみましょう。

• 「このコードの潜在的なバグやエッジケースを指摘してください。」
• 「パフォーマンス上のボトルネックになりそうな箇所はありますか？」
• 「より可読性の高いコードにするための改善案を提案してください。」

AIの指摘が常に正しいとは限りませんが、レビューの新たな視点を提供し、議論のきっかけを生むことで、コードの品質向上に貢献します。

まとめ

本記事では、AIネイティブエディタCursorの強力な機能と、それがもたらす新しいコーディングスタイルについて、具体的な例を交えながら深掘りしてきました。

Cursorは、もはや単なる「便利なツール」の域を超え、開発者の思考プロセスそのものを拡張する存在になりつつあります。

• 対話によるコーディング (Cmd+K): アイデアを自然言語で伝え、瞬時にコードに変換する。
• プロジェクト全体の把握 (@チャット): 巨大なコードベースを前にしても、AIをガイドとして迷うことなく進む。
• 複雑なタスクの自動化 (Cmd+Shift+L): 複数ファイルにまたがる変更も、AIに任せて一瞬で完了させる。

VS Codeの資産を完全に引き継ぎながら、これほどまでにディープなAI統合を実現したCursorは、AI時代の開発環境の一つの完成形と言えるかもしれません。もちろん、AIは万能ではなく、最終的な判断は常に開発者自身に委ねられています。しかし、面倒で時間のかかる作業をAIに任せることで、私たちはより創造的で、本質的な問題解決に集中できるようになるはずです。

もしあなたがまだCursorを試していないのであれば、ぜひこの機会にインストールし、その実力を体感してみてください。あなたのコーディングライフが、今日から劇的に変わるかもしれません。AIと共にコードを書く未来は、もうすぐそこまで来ています。

Claude Codeに「このファイルのバグを直して」と言うと、勝手にファイルを読み、修正し、保存してくれます。 また、「天気を教えて」と言えば、外部APIを叩いて答えてくれます。

まるで魔法のようですが、裏側では非常に論理的なプロセスが動いています。

本記事では、エンジニア向けに**「Claude CodeでSKILLS（スキル）が発動する仕組み」**を徹底的に解剖します。

ここを理解すれば、あなたはClaude Codeを「ただ使う人」から「自在に操る人（ツール開発者）」になれます。

1. 全体像：発動までの4ステップ

Claude Codeがスキルを実行する時、内部では以下の4段階のプロセスが走っています。

1. ツール定義の読み込み (Tool Definition)
2. 意図の検出 (Intent Detection)
3. 引数の生成 (Argument Generation)
4. 実行と結果のフィードバック (Execution & Feedback)

それぞれ詳しく見ていきましょう。

Step 1. ツール定義の読み込み

Claude Codeが起動する時、設定ファイルや MCP (Model Context Protocol) サーバーから、「自分は何ができるか」というリストを読み込みます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "name": "read_file",
  "description": "指定されたパスのファイルを読み込む",
  "parameters": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "読み込むファイルの絶対パスまたは相対パス"
      }
    },
    "required": ["path"]
  }
}

Step 2. 意図の検出 (Intent Detection)

ユーザーが「src/main.py の中身が見たい」と発言したとします。

Claudeの脳内（推論プロセス）では、以下のような思考が行われます。

ユーザーはファイルの中身を知りたがっている。 私の持っている道具リストの中に、それを叶えるものはあるか？ …あった。read_file だ。 この道具を使おう。

これが Function Calling（関数呼び出し） のトリガーです。

Step 3. 引数の生成 (Argument Generation)

道具を使うと決めたら、次は「どう使うか」を決めます。

定義書の parameters に従って、必要な情報を会話履歴から抽出します。

• ユーザーの発言: “src/main.py の中身…”
• 引数 path: "src/main.py"

Claudeは以下のような特殊なトークン（またはJSON）を出力します。

<tool_use>
  <name>read_file</name>
  <parameters>
    {"path": "src/main.py"}
  </parameters>
</tool_use>

Step 4. 実行と結果のフィードバック

ここが重要です。Claude自身がファイルを読むわけではありません。

Claudeが出力した上記のJSONを、Claude Codeのランタイム（実行環境） が受け取ります。 そして、PythonやNode.jsで書かれた実際のプログラム（open() 関数など）が実行されます。

実行結果（ファイルの中身）は、再びテキストとしてClaudeに返されます。

<tool_result>
  import os
  print("Hello World")
</tool_result>

これを見て初めて、Claudeは「ファイルの中身はこうなっていました」とユーザーに回答できるのです。

2. MCP (Model Context Protocol) とは？

最近話題の MCP は、この「ツールの渡し方」を標準化した規格です。

これまで、Claudeに独自のツールを追加するには、複雑な設定が必要でした。 しかしMCPを使えば、「MCPサーバー」 を立ち上げるだけで、Claude Codeが勝手にツールを認識してくれます。

仕組み

1. MCPサーバー: ツール（関数）の実装を持つプロセス。
2. MCPクライアント: Claude Code本体。

クライアントとサーバーが通信し、「使えるツール一覧」と「実行リクエスト」をやり取りします。 これにより、ローカルのデータベース操作や、社内APIへのアクセスが安全かつ簡単に実装できるようになりました。

まとめ

Claude Codeの「SKILLS」は、魔法ではありません。 「定義を読む」→「選ぶ」→「JSONを作る」→「実行結果を読む」 という、非常に泥臭いテキスト処理のループです。

しかし、この仕組みを理解していれば、あなたはClaude Codeを 「ただの話し相手」から 「手足となって働く最強のパートナー」 に進化させることができます。

ぜひ、自分だけのカスタムスキルを作ってみてください。

はじめに

Anthropic社のClaude 3、特にコーディング能力に優れたclaude-3-opus-20240229モデルは、多くの開発者にとって強力な相棒となりつつあります。コード生成、リファクタリング、デバッグ支援など、その能力は多岐にわたります。

しかし、こんな風に感じたことはありませんか？

• 「Claudeに社内のデータベースへアクセスさせて、最新の売上データを分析させたい…」
• 「GitHubリポジトリの最新のIssueを要約させたり、新しいチケットをJIRAに起票させたりできたら最高なのに…」
• 「特定の計算や、自作のコマンドラインツールを実行するよう指示できれば、作業が劇的に効率化されるはずだ…」

標準のClaudeは、学習データに含まれる一般的な知識しか持っておらず、あなたの会社のプライベートな情報や、リアルタイムの外部情報にアクセスすることはできません。これまでは、開発者が手動でAPIを叩き、その結果をコピー＆ペーストしてClaudeに与える、という手間のかかる作業が必要でした。

もし、Claudeに**「あなた専用のスキル」**を自由に追加できたらどうでしょう？まるで優秀なアシスタントに新しい能力を教え込むように、独自のツールやAPIと連携させることができたら。

この記事では、Anthropicが提供する**「Tool Use（ツール使用）」機能を活用し、Claudeをあなただけの最強コーディング・アシスタントへと進化させる具体的な方法を、詳細なコード例とともに解説します。この記事で言うMCP（Multi-turn Conversational Platform）活用術**とは、まさにこのTool Use機能を駆使して、対話型AIの能力を最大限に引き出す実践的なテクニックを指します。

この記事を読み終える頃には、あなたはClaudeに独自の「スキル」を授け、開発ワークフローを根本から変革する力を手に入れているはずです。

なぜ今、「Tool Use」が重要なのか？

LLM（大規模言語モデル）は、単に質問に答えたり文章を生成したりするだけの存在から、外部の世界と対話し、能動的にタスクを実行する**「エージェント」**へと進化しつつあります。その中核をなす技術が、ChatGPTにおける「Function Calling」であり、Claudeにおける「Tool Use」です。

この技術がなぜゲームチェンジャーとなり得るのか、その背景にある課題と合わせて見ていきましょう。

従来のLLMが抱えていた課題

1. 知識の陳腐化と非公開情報へのアクセス不可: LLMの知識は、学習データがカットオフされた時点のものであり、リアルタイムの情報（今日の天気、最新の株価など）を知りません。また、社内DBや個人のファイルなど、インターネット上に公開されていない情報には当然アクセスできません。
2. 手動による連携の非効率性: 開発者が外部APIから取得したデータをLLMに渡す場合、手動でのコピー＆ペーストが必要でした。このプロセスは手間がかかるだけでなく、ヒューマンエラーの温床にもなります。
3. プロンプトの複雑化と再現性の低さ: 複雑なタスクを指示しようとすると、プロンプトが非常に長大かつ複雑になりがちです。「まずこのAPIを叩いてJSONを取得し、その中のitems配列をループして、各nameとpriceを抽出し、マークダウンのテーブル形式で出力して…」といった詳細な手順を毎回プロンプトに記述するのは現実的ではありません。

「Tool Use」がもたらす解決策

ClaudeのTool Use機能は、これらの課題をエレガントに解決します。その仕組みは、LLMと開発者が協調して動作するフレームワークです。

Tool Useの基本的なフロー

sequenceDiagram
    participant User as ユーザー
    participant App as 開発者のアプリケーション
    participant Claude as Claude
    participant Tool as 外部ツール/API

    User->>App: 「東京の天気は？」
    App->>Claude: ユーザーの質問と利用可能なツール定義を渡す
    Claude->>Claude: 質問を解釈し、「get_weather」ツールが使えると判断
    Claude->>App: 「get_weather(city='Tokyo')」を実行してほしい、とJSON形式で要求
    App->>Tool: 実際に天気APIを呼び出す
    Tool-->>App: 天気データ（JSON）を返す
    App->>Claude: ツール実行結果（天気データ）を渡す
    Claude->>Claude: 実行結果を解釈し、自然言語の回答を生成
    Claude->>App: 「東京の天気は晴れです。」
    App->>User: 最終的な回答を表示

このフローが示すように、Tool Useは以下の役割分担によって成り立っています。

• Claudeの役割: ユーザーの意図を汲み取り、どのツールを、どのような引数で使うべきかを判断し、JSON形式で開発者に伝達する。そして、ツールの実行結果を受け取り、それを基に最終的な回答を生成する。
• 開発者の役割: Claudeが利用可能な「スキル」（ツール）の仕様を定義し、Claudeからツール実行の要求を受け取ったら、実際にそのツール（関数やAPIコール）を実行し、結果をClaudeに返す。

これにより、LLMは思考や判断に集中し、実際の「行動」は開発者が用意した信頼性の高いコードが担う、という強力な分業体制が実現します。これは、LLMを単なる「知識ベース」から、具体的なタスクをこなす「実行エンジン」へと昇華させる、きわめて重要なパラダイムシフトなのです。

具体的な実装方法：Claudeに天気を尋ねるスキルを追加する

それでは、実際に手を動かして、Claudeに「天気を尋ねるスキル」を追加してみましょう。ここではPython用のAnthropic SDKを使用します。

Step 1: 準備

まず、必要なライブラリをインストールし、APIキーを設定します。

1

pip install anthropic

APIキーは環境変数に設定しておくのが一般的です。

1

export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"

Step 2: 「スキル」（ツール）の定義

最初に、Claudeに「こんなツールが使えますよ」と教えるための定義を作成します。今回は、特定の都市の天気を取得するget_weatherというツールを定義しましょう。

このツール定義は、Claudeがツールの機能、目的、そして必要な引数を理解するために非常に重要です。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

import anthropic
import json

# Anthropicクライアントの初期化
client = anthropic.Anthropic()

# --- ここからがツールの定義 ---
tools = [
    {
        "name": "get_weather",
        "description": "特定の都市の現在の天気を取得します。ユーザーが天気について尋ねた場合に使用します。",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "天気を知りたい都市名。例: '東京', 'サンフランシスコ'"
                }
            },
            "required": ["city"]
        }
    }
]
# --- ここまでがツールの定義 ---

# 開発者側で実際にツールを実行する関数を定義
# (この例では実際のAPIは叩かず、ダミーデータを返す)
def get_weather(city: str):
    """指定された都市の天気を取得する（ダミー関数）"""
    print(f"--- ツール実行: get_weather(city='{city}') ---")
    if "東京" in city:
        return json.dumps({"city": "東京", "temperature": 25, "weather": "晴れ"})
    elif "大阪" in city:
        return json.dumps({"city": "大阪", "temperature": 22, "weather": "くもり"})
    else:
        return json.dumps({"city": city, "temperature": "不明", "weather": "不明"})

ここで重要なのはtoolsリストの中身です。

• name: ツールの名前です。Claudeがどのツールを呼び出すか指定するのに使います。
• description: 最も重要な要素の一つです。 Claudeはこの説明を読んで、いつ、何のためにこのツールを使うべきかを判断します。具体的で分かりやすい説明を心がけましょう。
• input_schema: ツールが必要とする引数をJSON Schema形式で定義します。これにより、Claudeは正しい引数名とデータ型でツールを呼び出そうとします。

Step 3: Claudeにツール使用を促すリクエストを送信

次に、ユーザーからの質問と、先ほど定義したツールリストをClaudeに渡します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# ユーザーからの質問
user_message = "今日の東京の天気はどうですか？"

print(f"ユーザー: {user_message}")

# Claudeに最初のメッセージを送信
response = client.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    messages=[{"role": "user", "content": user_message}],
    tools=tools, # ここで定義したツールを渡す
)

print("\n--- Claudeからの初回応答 ---")
print(response)

このコードを実行すると、Claudeからの応答は通常のテキストではなく、ツールを使用するべきだという特別な形式で返ってきます。

Step 4: Claudeからの応答（ツール使用要求）を処理する

responseの中身を確認してみましょう。特にstop_reasonとcontentに注目です。

# responseの出力例
Message(
    id='...',
    content=[
        ToolUseBlock(
            id='toolu_01A09q90e9QyqG7LLVf9i4t4',  # ツール使用ごとのユニークID
            input={'city': '東京'},
            name='get_weather',
            type='tool_use'
        )
    ],
    model='claude-3-opus-20240229',
    role='assistant',
    stop_reason='tool_use', # 停止理由が 'tool_use' になっている！
    stop_sequence=None,
    type='message',
    usage=Usage(input_tokens=..., output_tokens=...)
)

stop_reasonが'tool_use'になっているのが分かります。これは、「私は会話を一旦停止します。なぜなら、あなたが定義したツールを使いたいからです」というClaudeからの合図です。

contentリストには、ToolUseBlockオブジェクトが含まれており、どのツール（name）を、どの引数（input）で呼び出してほしいかが具体的に示されています。

この情報を使って、実際にツールを実行します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 会話の履歴を保持するリスト
conversation_history = [{"role": "user", "content": user_message}]

# Claudeの応答を履歴に追加
assistant_response_content = response.content
conversation_history.append({"role": "assistant", "content": assistant_response_content})

# ツール使用要求があるかチェック
if response.stop_reason == "tool_use":
    tool_use = next((block for block in response.content if block.type == "tool_use"), None)
    if tool_use:
        tool_name = tool_use.name
        tool_input = tool_use.input
        tool_use_id = tool_use.id

        print(f"\n--- Claudeがツール '{tool_name}' の使用を要求 ---")
        print(f"引数: {tool_input}")

        # ツール名に応じて適切な関数を実行
        if tool_name == "get_weather":
            tool_result = get_weather(city=tool_input["city"])
        else:
            # 未知のツールが要求された場合のエラーハンドリング
            tool_result = json.dumps({"error": f"Unknown tool: {tool_name}"})

Step 5: ツール実行結果をClaudeに返す

ツールを実行したら、その結果をClaudeにフィードバックする必要があります。これにより、Claudeは次のステップに進むことができます。

結果を返す際は、「どのツール実行要求に対する結果なのか」を明確にするために、Step 4で取得したtool_use_idを使います。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

        print(f"ツール実行結果: {tool_result}")

        # ツール実行結果を会話履歴に追加
        conversation_history.append(
            {
                "role": "user",
                "content": [
                    {
                        "type": "tool_result",
                        "tool_use_id": tool_use_id,
                        "content": tool_result,
                    }
                ],
            }
        )

Step 6: Claudeからの最終的な回答を得る

最後に、ツール実行結果を含む更新された会話履歴を、再度Claudeに送信します。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

        print("\n--- ツール実行結果をClaudeに送信し、最終回答を要求 ---")

        # ツール実行結果を踏まえた最終的な応答をClaudeに生成させる
        final_response = client.messages.create(
            model="claude-3-opus-20240229",
            max_tokens=2048,
            messages=conversation_history, # 更新された会話履歴を渡す
            tools=tools,
        )

        print("\n--- Claudeからの最終回答 ---")
        final_answer = final_response.content[0].text
        print(final_answer)

# 実行結果の例:
#
# ユーザー: 今日の東京の天気はどうですか？
#
# --- Claudeからの初回応答 ---
# ... (ToolUseBlockを含むMessageオブジェクト) ...
#
# --- Claudeがツール 'get_weather' の使用を要求 ---
# 引数: {'city': '東京'}
# --- ツール実行: get_weather(city='東京') ---
# ツール実行結果: {"city": "東京", "temperature": 25, "weather": "晴れ"}
#
# --- ツール実行結果をClaudeに送信し、最終回答を要求 ---
#
# --- Claudeからの最終回答 ---
# 東京の今日の天気は晴れで、気温は25度です。

見事にClaudeが外部ツール（今回はダミー関数）と連携し、ユーザーの質問に答えることができました。これがTool Useの基本的な流れです。

メリットとデメリット

この強力なTool Use機能ですが、もちろん良い点ばかりではありません。導入を検討する上で、メリットとデメリットを正しく理解しておくことが重要です。

メリット

1. 無限の拡張性: Claudeの能力を、事実上無限に拡張できます。社内API、外部のSaaS、ローカルのスクリプト実行、データベース操作など、APIや関数として呼び出せるものなら何でも連携可能です。
2. タスクの自動化と生産性向上: JIRAチケットの作成、GitHubのIssue要約、デプロイメントのキックなど、これまで手作業で行っていた定型的なタスクを自然言語の指示で自動化でき、開発者の生産性を劇的に向上させます。
3. 対話の自然さ: ユーザーはツールの存在やAPIの仕様を意識する必要がありません。ただ自然言語で「〜して」と頼むだけで、裏側で適切なツールが呼び出されます。
4. 信頼性の向上: LLM単体では事実に基づかない回答（ハルシネーション）を生成することがありますが、Tool Useを使えば、信頼できる情報源（APIの実行結果など）に基づいた回答を生成させることができます。
5. プロンプトの抽象化: 複雑な手順を長々とプロンプトに書く代わりに、それらを一つのツールとしてカプセル化できます。プロンプトは簡潔になり、メンテナンス性も向上します。

デメリット

1. 実装コスト: ツール定義の作成、API連携ロジックの実装、エラーハンドリングなど、開発者側でのコーディングが必要です。手軽に試せるものではなく、システムへの組み込みには設計と実装のコストがかかります。
2. APIコストの増加: 一つの質問応答フローの中で、ClaudeのAPIを複数回（ツール使用判断で1回、最終回答生成で1回）呼び出すことになります。これにより、APIの利用料金が増加する可能性があります。
3. レイテンシの増加: ツール実行（特に外部APIの呼び出し）には時間がかかるため、応答全体のレイテンシは長くなる傾向にあります。ユーザー体験を損なわないよう、パフォーマンスへの配慮が必要です。
4. セキュリティリスク: データベースの更新やファイルの削除など、破壊的な操作を伴うツールを連携させる場合は、細心の注意が必要です。Claudeに意図しない操作を実行させないよう、厳格な権限管理、入力値のサニタイズ、実行前の人間による確認ステップなどを設けるべきです。

現場で使える実践的なTips

基本的な使い方をマスターしたところで、より実践的なシナリオでTool Useを使いこなすためのヒントをいくつか紹介します。

1. 良いツール設計の原則：descriptionが命

Claudeがツールを正しく使いこなせるかどうかは、ツールのdescription（説明文）の品質に大きく依存します。

悪い例 ❌: "description": "DBからデータを取得する" → これでは、いつ、何のデータを、どのように取得するのかが全く分かりません。

良い例 ✅: "description": "指定されたSQLクエリを読み取り専用の分析データベースで実行し、結果をJSON形式で返します。主に売上データやユーザー行動ログの集計・分析に使用します。データの更新や削除はできません。" → この説明により、Claudeは「売上分析の依頼が来たらこのツールを使おう」「SQLを生成して引数に渡せばいいんだな」「データを書き換えることはできないな」といったことを正確に理解できます。

引数の説明も同様に重要です。 ユーザーが曖昧な指示をした際に、Claudeがどの情報を追加でヒアリングすべきかの判断材料になります。

2. 堅牢なエラーハンドリング

ツールの実行は常に成功するとは限りません。APIがタイムアウトしたり、データベース接続に失敗したり、不正な引数が渡されたりすることもあります。

このような場合、エラー情報を適切にClaudeに返すことで、Claudeがユーザーに対して状況を説明したり、リトライを促したりできるようになります。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

def query_database(sql_query: str):
    try:
        # ... データベース接続とクエリ実行のロジック ...
        result = db.execute(sql_query)
        return json.dumps({"status": "success", "data": result})
    except Exception as e:
        # エラーが発生したら、エラー情報を返す
        print(f"--- ツール実行エラー: {e} ---")
        return json.dumps({
            "status": "error",
            "error_message": f"データベースクエリの実行に失敗しました: {str(e)}"
        })

# ...

# ツール実行結果をClaudeに返す部分
tool_result = query_database(sql_query=tool_input["sql_query"])
conversation_history.append({
    "role": "user",
    "content": [{
        "type": "tool_result",
        "tool_use_id": tool_use_id,
        "content": tool_result, # エラー情報が含まれたJSONをそのまま渡す
        "is_error": "error" in json.loads(tool_result) # (Optional) エラーであることを明示
    }]
})

こうすることで、Claudeは「データベースクエリの実行に失敗しました。SQLの構文が間違っている可能性があります。クエリを確認してください: SELECT * FRM sales」のように、具体的なフィードバックを返すことができます。

3. 複数のツールを組み合わせる（思考の連鎖）

より複雑なタスクでは、複数のツールを段階的に実行する必要があります。

例: 「先月の売上トップだった商品の担当営業に、Slackでお祝いメッセージを送って」

このタスクを達成するには、おそらく2つのツールが必要です。

1. get_top_sales_product(month: str): 指定した月の売上トップ商品と担当者を取得するツール。
2. send_slack_message(user_id: str, message: str): 指定したユーザーにSlackメッセージを送信するツール。

このようなシナリオでは、Claudeは自律的に思考の連鎖（Chain of Thought）を行い、ツールを順番に呼び出します。

1. ユーザーの指示を解釈し、まずget_top_sales_productを呼び出す必要があると判断する。
2. 開発者側でこのツールを実行し、結果（{"product": "商品A", "sales_person_id": "U12345"}）を返す。
3. Claudeは結果を受け取り、次にsend_slack_messageを、引数 user_id='U12345', message='...お祝いメッセージ...' で呼び出す必要があると判断する。
4. 開発者側でSlack送信ツールを実行し、成功した旨を返す。
5. Claudeはすべてのステップが完了したことを確認し、「先月の売上トップ商品Aの担当者である山田さんに、お祝いのSlackメッセージを送信しました。」と最終報告を行う。

このように、複数のツールを適切に設計・定義することで、Claudeをより高度な自律エージェントとして機能させることができます。

まとめ

本記事では、Claudeの「Tool Use」機能を用いて、Claudeに独自の「スキル」を追加し、あなた専用の最強アシスタントへと進化させる方法を解説しました。

Tool Useは、単なる機能追加ではありません。それは、LLMという強力な「脳」に、あなたの世界のツールやシステムという「手足」を与えることに他なりません。これまで分断されていたLLMの対話能力と、既存のソフトウェア資産を繋ぐ、きわめて重要な架け橋です。

今回紹介した基本的なフローと実践的なTipsを参考に、まずは身近なタスクを自動化する簡単なツールから試してみてください。天気予報の取得、簡単な計算、テキストファイルの読み書きなど、小さな成功体験を積み重ねることで、Tool Useの持つ無限の可能性を実感できるはずです。

LLMをワークフローに統合する動きは、今後ますます加速していくでしょう。Tool Useを使いこなし、Claudeを真の「相棒」として活用できるかどうかは、これからの開発者にとって大きなアドバンテージとなります。ぜひ、あなただけの「最強のClaude」を育て上げてみてください。