「AIに書かせたコードが動かない」から卒業するために

AIを使ったコーディングに挑戦したものの、「コードが動かない」「途中で指示がブレる」「結局自分で直す羽目になる」——そんな経験を繰り返していませんか？

ChatGPTやGitHub Copilotが広まったことで、AIコーディング自体は一般化しましたが、継続的に価値を生み出せるレベルで使いこなしている開発者はまだ少数派です。その差を生み出しているのは「ツールの違い」ではなく、AIとの協働の設計にあります。

Anthropicが提供するClaude Codeは、ターミナルから直接操作できるエージェント型のAI開発ツールです。従来のチャット型AIとは異なり、ファイルの読み書き・コマンド実行・Git操作まで自律的に行える点が大きな特徴です。本記事では、このClaude Codeを実務で最大限に活用するための戦略を、日本のエンジニア・個人開発者の視点から体系的に解説します。

Claude Codeが他のAIコーディングツールと根本的に違う理由

チャット型との本質的な差異

ChatGPTやClaudeのWeb版でコードを生成してもらう場合、開発者は「生成されたコードをコピーして貼り付ける」というブリッジ作業を常に担います。一方、Claude Codeはターミナル上で動作し、プロジェクト全体のコンテキストを保持しながら直接コードを編集・実行できます。

主な違いを整理すると：

観点チャット型AIClaude Code
コード反映手動コピペ直接ファイル編集
コンテキスト会話単位プロジェクト全体
コマンド実行不可可能（bash等）
マルチファイル対応限定的ネイティブ対応

GitHub Copilotとの使い分け

Copilotはインライン補完に強みがあり、コードを書きながらリアルタイムで候補を出してくれます。対してClaude Codeは「大きな機能を丸ごと実装する」「既存コードをリファクタリングする」といったタスク単位の作業に向いています。両者は競合ではなく補完関係にあり、使い分けることで開発速度が大幅に向上します。

実務効率を10倍にするMCPサーバー活用術

**MCP（Model Context Protocol）**は、Anthropicが提唱するオープン規格で、AIモデルと外部ツール・データソースを接続する仕組みです。Claude CodeはMCPに対応しており、適切なサーバーを設定することで開発体験が劇的に変わります。

特に効果的なMCP連携の例

  1. Filesystem MCP：ローカルファイルシステムへのアクセスを制御。読み書き範囲を明示的に設定でき、セキュリティと利便性を両立します。

  2. GitHub MCP：Issueの取得・PR作成・コメント追加などをClaude Code経由で実行できます。「このIssueの内容を読んで実装して」という指示が文字通り動きます。

  3. Postgres / SQLite MCP：データベースのスキーマをAIが直接参照しながらクエリを生成・実行します。ORMの設定ミスやNullポインタ系のバグが大幅に減ります。

  4. Brave Search MCP：Claude Codeにリアルタイムの検索能力を付与。ライブラリの最新バージョンやエラーの解決策を自分で調べながら実装を進めます。

MCP設定時の注意点

MCPはまだ発展途上の規格であり、サードパーティ製サーバーには品質のばらつきがあります。導入前に以下を確認してください：

  • リポジトリのメンテナンス頻度（直近3ヶ月以内の更新があるか）
  • 必要な権限スコープが最小限か（過剰な権限要求は危険信号）
  • 機密情報（APIキー、個人情報）が外部送信されないか

並列タスク設計：AIエージェントを「チーム」として動かす

通常、AIに指示を出す場合は「質問→回答→次の質問」という直列フローになりがちです。しかしClaude Codeを含むエージェント型AIは、設計次第で複数のタスクを並列処理させることが可能です。

並列開発の具体的な設計パターン

個人開発でも有効な並列タスクの切り方として、以下のパターンが実践的です：

フロントエンド ／ バックエンド 分離パターン

1
2
3
4
5
6
7

Session A（ターミナル1）:
「認証APIのエンドポイントを/api/auth以下に実装してください。
  仕様：JWT使用、リフレッシュトークン対応、エラーレスポンスはRFC7807形式」

Session B（ターミナル2）:
「ログイン・登録フォームのUIコンポーネントをReactで実装してください。
  状態管理はZustand、バリデーションはZodを使用してください」

この設計のポイントは、インターフェース（API仕様）を先に確定させてから並列化することです。仕様が曖昧なまま並列実装を走らせると、結合時に大量の差分修正が発生します。

タスク分解の黄金ルール

  • 依存関係のないタスクを特定する（データフロー図を先に描く）
  • 各タスクに明確な「完了条件」を定義する
  • セッションをまたぐ共有情報（型定義、定数など）はファイルとして先に作成する

長期プロジェクトで破綻しないためのプロンプト設計

Claude Codeの最大の落とし穴は、プロジェクトが大きくなるにつれてコンテキストが失われ、一貫性が崩れることです。数千行規模のコードベースになると、AIが過去の設計方針を「忘れる」現象が顕著になります。

CLAUDE.mdによるコンテキスト永続化

プロジェクトルートにCLAUDE.mdというファイルを作成し、以下の情報を記載することで、セッションをまたいでもAIが一貫した理解を保持できます：

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

# プロジェクト概要
このプロジェクトは〇〇を目的としたWebアプリです。

# 技術スタック
- フロントエンド: Next.js 14 (App Router)
- バックエンド: Hono + Cloudflare Workers
- DB: Turso (libSQL)
- 認証: Better Auth

# コーディング規約
- コンポーネントはServer Componentsを基本とする
- 副作用のあるコンポーネントのみ'use client'を付与
- エラーハンドリングはResult型で統一

# 禁止事項
- anyの使用禁止
- console.logの本番コードへの混入禁止

指示の粒度を揃える

大きすぎる指示（「ECサイトを作って」）は失敗します。適切な粒度は「1〜2時間の作業に相当するタスク」です。機能単位ではなく変更単位で考えることが重要で、これはGitのコミット単位とほぼ一致します。

編集部の視点：日本の開発現場でClaude Codeを使う際の現実的な注意点

コスト管理は事前に設計する

Claude CodeはAnthropicのMax Plan（月額$100〜）での利用を推奨されています。大規模なコンテキストを扱うとトークン消費が急増するため、個人開発者が無計画に使い始めると想定外の課金が発生します。以下の対策を推奨します：

  • .claudeignoreでnode_modulesや.gitディレクトリを除外
  • セッション開始時にコンテキストをリセットする習慣をつける
  • コスト確認コマンド（/cost）を定期的に実行する

セキュリティ：AIに渡すべきでない情報

Claude Codeは強力ですが、以下の情報はプロジェクトに含めないよう徹底してください：

  • 本番環境の.envファイル
  • 顧客の個人情報・機密データを含むログ
  • 社内の認証情報・証明書類

.gitignoreと同様に.claudeignoreを設定し、センシティブなファイルへのアクセスを物理的にブロックする設計を推奨します。

日本語コメント・ドキュメントへの対応

朗報として、Claude（Sonnet / Opus系）は日本語コードコメントやREADMEの理解精度が非常に高いです。既存プロジェクトに日本語コメントが混在していても、理解精度が大きく落ちることは少ないですが、プロンプト自体は英語で書くと精度が上がる傾向があります。重要な指示は英語、補足説明は日本語、という使い分けも有効です。

まとめ：Claude Codeは「使う」のではなく「設計する」ツール

Claude Codeを使いこなせる開発者とそうでない開発者の差は、タイピング速度でも知識量でもありません。AIとの協働をどう設計するかという構造設計力にあります。

本記事のポイントを振り返ります：

  1. チャット型との違いを理解する：コンテキスト保持と直接実行がClaude Codeの核心
  2. MCPで外部ツールと繋ぐ：GitHubやDBとの連携でAIの行動範囲を拡張
  3. 並列タスク設計：インターフェース先行で複数セッションを活用
  4. CLAUDE.mdでコンテキストを永続化：長期プロジェクトでの一貫性を保つ
  5. コストとセキュリティを事前設計：日本の実務環境に合わせたリスク管理

まずは小規模な個人プロジェクトでCLAUDE.mdの作成とMCPの1つの連携から試してみてください。最初の一歩が、AIとの本質的な協働への入口になります。

YCC Blogでは、Claude・ChatGPT・Geminiなどの最新AI活用事例を定期的に発信しています。気になる方はぜひブックマーク＆SNSフォローをお願いします！