導入
Claude Code を触り始めたとき、「AI がコードを自動生成してくれるなら、開発が楽になるはず」と思いました。しかし、実際に使い始めると、プロンプトの書き方やエラーの対処法、生成されたコードの検証方法など、わからないことがたくさんありました。特に、初心者の頃は「どうやって AI と会話すれば自分の意図を正確に伝えられるのか？」と悩んだものです。この記事では、僕が現場で Claude Code を活用する中で得た失敗談や気づき、そして今では当たり前としているベストプラクティスを 5 つ紹介します。これから Claude Code をチームで使ってみようと考えている方や、 currently 使い始めているけれどもっと効率的に使いたいと考えている方にとって、「こんな風にすれば良かった」というヒントが得られるはずです。ぜひ、読み進めてみてください。
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
最新ツール・トレンド情報をずんだもん×めたんが解説するYouTubeチャンネルを運営しています！
いいね、チャンネル登録してもらえると嬉しいです🙇♂️
ハジメル.dev: https://hajimeru-dev.vercel.app/
「ひとりで続けるのは難しい」「何から学べばいいか分からない」という方向けに、
プログラミングのマンツーマンレッスンサービス「ハジメル.dev」も運営しています。
未経験OK・オンライン完結・月額制/違約金なしなので、気軽に無料相談してみてください🙇♂️
海外テックニュースを追いたいけど、英語や情報量の多さで大変…という方向けに、
Hacker News の話題を日本語でサクッと追える「HackerNews 日本語まとめ & AI要約」
を個人開発しました！
技術トレンド収集に使ってもらえると嬉しいです🔥🙇♂️
→ HackerNews 日本語まとめ & AI要約: https://hn-matome-2ht.pages.dev/
「ニャンパイアサバイバー」というヴァンパイアサバイバーリスペクトのゲームを作成しました！
もしよろしければ遊んで頂けると嬉しいです😭
習い事教室の先生向けに、SNS 投稿・生徒募集・保護者通知の文章を AI で生成する Web サービス「おしらせAI」を個人開発しました。Next.js + Supabase + LLM で構成しており、無料で月 10 回まで試用できます。よければ触ってみてください。
→ おしらせAI: https://oshirase-ai.vercel.app/
言いたいことがうまく伝わらない…という方向けに、会話の言い方を添削する「伝え方ラボ」を開発中です。
場面を選んで自分の言葉で返すと、何が伝わっていないかの指摘と、そのまま使える言い換えが返ってきます。
ChatGPT に相談すると褒めから入って直すべきところが残りがちなので、指摘側に振り切りました。
現在は公開時にお知らせするメール登録のみ受付中です🙇♂️
→ 伝え方ラボ: https://tsutaekata-lab.pages.dev/
✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨✨
環境構築のポイント
Claude Code をインストールした直後、僕はまず公式のドキュメントに従ってセットアップを行いました。しかし、その時点では「必要なもの」を全て理解していませんでした。例えば、Node.js の特定のバージョンや、Git の設定、さらには API キーの管理方法などです。後で気づいたのですが、これらの設定を事前にしっかりと行っておくことで、コード生成の前に多くの時間を節約できます。僕は今では、Claude Code をインストールする前に必ず .env.example を作成し、必要な環境変数をリストアップするようにしています。また、Node のバージョン管理には nvm を使い、プロジェクトごとに isolate された環境を構築しています。これにより、チームメンバーが同じ設定で作業できるようになり、生成されたコードの整合性も保たれます。具体的な手順としては、以下の通りです。
# Node のバージョン確認
node -v
# nvm がインストールされていない場合はインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20.15.0
nvm use 20.15.0
# Git の設定（なければ）
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
# プロジェクトの初期化と .env.example の作成
npm init -y
touch .env.example
echo "CLAUDE_API_KEY=your_key_here" > .env.example
この準備をしておくと、後々のトラブルを未然に防ぐことができます。環境が整っていれば、AI に集中してプロンプトを書くことにエネルギーを費やすことができ、開発全体の効率が向上します。
プロンプト設計の極意
Claude Code を使い始めた頃、最も苦労したのが「どうやってプロンプトを書けば意図したコードが生成されるのか」という点でした。最初は「Add a button that shows a modal」とだけ書いていたのですが、生成されたコードはボタンを表示するだけのもので、モーダルの動作は全く含まれていませんでした。原因は、プロンプトが曖昧だったことと、AI に具体的な実装の詳細を伝えられていなかったことにあります。今では、いくつかのルールを意識してプロンプトを書くようにしています。
- 目的と詳細な要件を最初に記述する – 「モーダルを開くボタンが必要」ではなく、「ユーザーがボタンをクリックすると、モーダルを開いて…」と書きます。
- エッジケースやエラーハンドリングを盛り込む – 「エラーメッセージを表示する」や「API が失敗した場合はフォールバックを表示する」など。
- コードのスタイルや命名規則を指定する – 「React の関数コンポーネントを使用し、Tailwind CSS を適用する」、「変数名は camelCase、関数名は snake_case で定義する」など。
- 期待する UI の構造を図示する – テキストだけだと伝わりにくいので、簡単な ASCII アートやマークダウン表を使うこともあります。
具体的な例を挙げると、以下のようなプロンプトが今では僕の効果的なツールです。
React の関数コンポーネントを作成し、モーダルを開くボタンを含めてください。
- モーダルは、`<Dialog>` コンポーネント（Headless UI）を使用して実装します。
- ボタンのテキストは「開く」とします。
- モーダル内には、`<h2>` 見出しと「閉じる」ボタン付きの段落が含まれます。
- モーダルは、backdrop クリックで閉じることができます。
- スタイルには Tailwind CSS を使用し、アクセシビリティ（role、aria‑label など）にも配慮してください。
このプロンプトの後に「コードのみを返してください。説明は不要です」と付け加えると、Claude Code はほぼ完璧なコードブロックを返してくれるようになりました。コード生成後には、フォーマットチェック（Prettier）や lint（ESLint）を自動的に実行し、問題があれば修正依頼を AI に投げます。このループを回すことで、コードの品質が安定し、修正作業に費やす時間を大幅に削減できました。
テストとデバッグの習慣
Claude Code で生成されたコードをそのままコミットしていた初期の頃、僕は多くのバグに悩まされました。例えば、「開発環境では正常に動作するが、本番環境で undefined エラーが発生する」といった問題です。後で気づいたのですが、AI にコード生成を任せるだけでは、隠れた前提条件や環境固有の処理を見逃してしまうのです。今では、Claude Code にコードを生成させた後、必ず以下の 3 つのステップを踏むようにしています。
-
単体テストの作成 – Jest や Vitest を使って、主要な関数やコンポーネントの動作をテストします。テストコードは生成したコードと同じファイルに追加し、
// test:というコメントで区切ることで、AI が後で理解できるようにしています。 -
ローカルでの動作確認 –
npm testを実行し、テストが通ることを確認します。もし失敗したら、失敗理由を AI にフィードバックします。「X 条件に対して Y テストが失敗しています。X を満たすように修正してください」と具体的に伝えます。 - 統合テストの実行 – Cypress や Playwright を使って、UI のエンドツーエンドテストを実行します。これにより、AI が生成したコンポーネントが全体のフローと整合しているかどうかを確認できます。
具体的な例として、以下のような Jest テストを生成した React コンポーネントに追加しています。
import { render, screen, fireEvent } from '@testing-library/react';
import ModalButton from './ModalButton';
test('モーダルを開くボタンがクリックされるとモーダルが表示される', () => {
render(<ModalButton />);
const button = screen.getByRole('button', { name: '開く' });
expect(screen.getByRole('dialog')).not.toBeInTheDocument();
fireEvent.click(button);
expect(screen.getByRole('dialog')).toBeInTheDocument();
});
この習慣を身につけてから、バグの修正に費やす時間が 80% 以上削減されました。また、チーム内でも「このコードはテストがしっかりしているから安心して使える」という評価を得られるようになり、Claude Code を活用した開発がよりスムーズになりました。
チームでの共有と継続的改善
一人で開発を進めていた頃は、Claude Code で生成したコードを GitHub にプッシュし、レビューを受けることがほとんどありませんでした。しかし、チームで開発するようになってから、いくつかの課題に直面しました。例えば、チームメンバーが異なるプロンプトの書き方をしていて、生成されたコードのスタイルがバラバラになったり、API キーが共有リポジトリに誤ってコミットされたりするといった問題です。これらの問題を解決するために、僕たちはいくつかのルールをチームで決めました。
-
Claude Code の設定をリポジトリにコミットしない –
.envファイルは.gitignoreに追加し、.env.exampleを使って必要な変数を管理します。 - 生成したコードは必ず PR に含める – レビュワーがコードの意図やテストの有無を確認できるようにします。
-
プロンプトテンプレートをドキュメント化する – 効果的なプロンプトの例を
docs/prompt-templates.mdにまとめ、全員が参照できるようにします。 - 月次で振り返りを行う – 何がうまくいっていて、何がうまくいかなかったかをチームで話し合い、プロンプトの改善やワークフローの見直しを行います。
具体的な例として、僕たちのチームでは docs/prompt-templates.md に以下のようなテンプレートを保存しています。
## テンプレート: React コンポーネント生成
### 入力
- コンポーネントの名前
- 必要な UI 要素
- スタイル要件（Tailwind、CSS モジュールなど）
- テストの要件（オプション）
### 出力
- 関数コンポーネントコード
- 単体テストコード
- 簡単な使用例（オプション）
このドキュメントのおかげで、新しくメンバーが加わっても一貫した品質のコードを生成できるようになり、Claude Code を活用した開発がチーム全体で安定しました。また、継続的な改善を心がけることで、Claude Code の能力が向上するにつれて、プロンプトの精度やテストの網羅率も自然と高まっていきます。
まとめ
Claude Code を現場で活用する上で最も重要なことは、「AI にコードを生成させること」そのものではなく、「生成されたコードをいかに品質高く、チームで活用できるか」という点だと僕は考えています。環境構築の徹底、プロンプトの工夫、テストとデバッグの習慣化、そしてチームでの共有と継続的改善。この 5 つのベストプラクティスを実践することで、開発スピードを上げつつも code quality を維持することが可能になります。あなたもぜひ、この記事を参考にしながら、Claude Code をより効果的に活用してみてください。コード作成がもっと楽しくなるはずです。