📘

Anthropicが公開しているClaude Codeのベストプラクティスを初心者向けに解説

に公開
AI
GitHub
個人開発
Claude
Claude Code
tech

こんにちは、とまだです。

「AIツールを使ってコーディングを効率化したい！」

そう思ってClaude Codeを始めてみたものの、思うような結果が出なくて悩んでいませんか？

今回は、Anthropic社が公開しているClaude Codeのベストプラクティスから抜粋し、初心者にもわかりやすく解説します！

これを読めば、Claude Codeをもっと効果的に使いこなせるようになるはずです。

ちなみに私は本業ではフリーランスエンジニア、ならびにAI駆動開発の導入支援を行っています。
また、Udemy で AI 駆動開発講座を複数開講しており、いくつかベストセラーもいただいています。

その経験を活かして、初心者の方でもわかりやすいよう、丁寧に解説しています！

忙しい人のために要約

  • CLAUDE.mdファイルで開発ルールを共有
  • 適切なツールの権限設定で安全性と効率性を両立
  • テスト駆動開発やビジュアルモックを活用した開発フローが効果的
  • 複数のClaude Codeを並行実行して生産性を向上
  • GitHub CLIを使ったバージョン管理やPRレビューの活用
  • コマンドのカスタマイズで開発効率を向上
  • セキュリティと安全性を意識した使い方が重要
  • ヘッドレスモードでの自動化も可能

なお、まだ Claude Code を使ったことがない方は、無料で公開しているこちらの本から学ぶことができます。

https://zenn.dev/tmasuyama1114/books/claude_code_basic

Claude Codeとは？

まず簡単にClaude Codeについて改めて説明しておきます。

Claude Codeは、Anthropic社が提供するAI駆動のコーディング支援ツールです。

コマンドラインから直接使えて、ファイルの作成・編集、テストの実行、GitやGitHubとの連携まで、幅広い開発作業をサポートしてくれます。

特徴的なのは、AIがコードを生成するだけでなく、実際にファイルを操作したり、コマンドを実行したりできることです。

ただし、この強力な機能を使いこなすには、いくつかのコツがあります。

それでは、具体的なベストプラクティスを見ていきましょう。

CLAUDE.mdでチーム開発を効率化

プロジェクトのルールを共有する仕組み

Claude Codeには、CLAUDE.mdという特別なファイルがあります。

このファイルをプロジェクトのルートディレクトリに置いておくと、Claude Codeが自動的に読み込んでくれます。

つまり、チーム全体で共有したい開発ルールやよく使うコマンドを記載しておけば、毎回説明する必要がなくなるのです。

CLAUDE.mdの活用例

たとえば、以下のような情報を記載しておくと便利です。

# プロジェクトのコマンド
- npm run build: プロジェクトをビルド
- npm run typecheck: 型チェックを実行

# コーディング規約
- ES modulesを使用（CommonJSは使わない）
- importはなるべく分割代入で記述

# 開発フロー
- 変更後は必ず型チェックを実行
- テストは個別に実行（全体実行は避ける）

このように書いておけば、Claude Codeは自動的にこれらのルールに従って開発を進めてくれます。

新しくチームに参加したメンバーも、このファイルを見れば開発の進め方がすぐにわかります。

CLAUDE.mdの配置場所

CLAUDE.mdファイルは、以下の場所に配置できます。

  • プロジェクトルート：最も一般的な配置場所
  • 親ディレクトリ：モノレポで複数のプロジェクトがある場合に便利
  • 子ディレクトリ：特定のフォルダで作業する際に自動読み込み
  • ホームフォルダ（~/.claude/CLAUDE.md）：全プロジェクトで共通の設定

サブエージェントで複雑な問題を解決

サブエージェントとは？

サブエージェントは、特定のタスクに特化した独立したAIエージェントです。

それぞれが専用のコンテキストウィンドウとツール権限を持ち、メインの会話とは別に作業を進められます。

.claude/agents/フォルダにMarkdown形式で定義し、/agentsコマンドで管理します。

ちょっと前の記事なのですが、こちらで詳しく解説しています。

https://qiita.com/tomada/items/a6fba5876dbc9304ca5a

探索フェーズでサブエージェントを活用する

複雑な問題に取り組む時、メインのClaude Codeにすべてを任せるとコンテキストがパンパンになってしまいます。

そんな時は、サブエージェントに詳細調査を任せる方法が効果的です。

たとえば、こんな指示を出します。

関連ファイルを読み込んで実装方針を立ててください。
技術的に不明な点があれば、サブエージェントを使って詳しく調査してください。

こうすると、メインのClaude Codeは全体の方針を考えながら、細かい技術調査はサブエージェントに任せてくれます。

サブエージェントは独立したコンテキストで動作するため、メインの会話を汚染せず、より深い調査ができて、実装の精度も上がります。

実装の検証に使う

テスト駆動開発でありがちなのが、「テストに通るだけの実装」になってしまうことです。

これを防ぐために、以下のような指示が有効です。

テストをすべて通す実装ができたら、
独立したサブエージェントで、実装が適切かどうか検証してください。
テストに過度に依存していないか確認してもらってください。

サブエージェントは、メインとは別の視点で実装を評価できるため、より客観的なコードレビューが可能になります。

サブエージェントの管理方法

サブエージェントを作成・編集するには、/agentsコマンドを使用します。

/agents

このコマンドで、以下のことができます：

  • 既存のサブエージェントの一覧表示
  • 新しいサブエージェントの作成
  • サブエージェントの編集・削除
  • 使用可能なツールの設定

プロジェクト固有のサブエージェントは.claude/agents/に、全プロジェクトで共通のサブエージェントは~/.claude/agents/に保存されます。

コンテキスト管理で長時間作業を効率化

コンテキストというのは、AIが持っている情報のことです。

人間と同じく、コンテキストが多すぎると情報を正確に思い出す能力が低下していきます。

/clearコマンドを戦略的に使う

長時間Claude Codeを使っていると、だんだん動作が重くなったり、的外れな提案が増えたりしませんか？

これは、コンテキストウィンドウが不要な情報でいっぱいになってしまうからです。

そこで、/clearコマンドを使うことで、コンテキストをリセットすることができます。

/clear

人間でいうと「リフレッシュして頭をリセットする」ようなものです。

違う機能の実装に移る時は、思い切って/clearしてしまいましょう。

ただし、/clear は全てのコンテキストをリセットするので、注意が必要です。

作業の続きをしたい場合は、/compactコマンドを使うことで、コンテキストを圧縮することができます。

/compact

ここでいう「圧縮」とは、ここまでの作業内容を要約して、コンテキストを節約するような意味を指します。

ただし、ここまでのコンテキストを引き継ぐことになりますので、全く別な作業に移る時は、/clearを使ってください。

ちなみに、大きく機能追加や設計変更をした場合は、/initコマンドを使うことで、CLAUDE.mdを更新することができます。

/init

/init は何回でも実行できますので、大きく機能追加や設計変更をした場合は、実行しておきましょう。

/clear を使っても /compact を使っても CLAUDE.md の内容は引き継がれますので、その点は安心です。

長時間セッションのコツ

チェックリストを作る

大量のタスク（たとえばlintエラーの修正）がある時は、Markdownファイルでチェックリストを作ると便利です。

1. すべてのlintエラーをchecklist.mdに書き出してください
2. 一つずつ修正して、完了したらチェックを入れてください
3. 10個修正したら進捗を報告してください

これなら、コンテキストが膨らんでも、どこまで進んだかが明確です。

重要な決定事項は外部ファイルに保存

実装方針や重要な決定は、別ファイルに残しておきます。

今回の実装方針をimplementation_notes.mdにまとめてから、
/clearして次のタスクに進んでください

後から「あの時どういう方針だったっけ？」となった時に助かります。

AIにとっても、人間にとっても重要なポイントです。

MCP（Model Context Protocol）でツールを拡張

MCPサーバーで外部ツールと連携する

Claude CodeはMCPクライアントとしても動作するので、外部ツールとの連携が可能です。

私も最初はよくわからなかったのですが、要するに「Claude Codeが使えるツールを増やせる仕組み」だと理解すれば大丈夫です。

たとえばWebアプリの開発であれば、Chrome DevTools MCPサーバーを使うと UI チェックやパフォーマンスチェックができたりと、開発効率が大幅に向上します。

https://qiita.com/tomada/items/8b22cac69b5247df1c20

なお、プロジェクトルートに.mcp.jsonファイルを作っておくと、チーム全員が同じツールを使えるようになります。

// 例：Sentry MCPサーバーを使う場合
{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "args": ["--sentry-auth-token", "your-auth-token"]
    },
  }
}

チーム開発では、この設定ファイルをGitに含めておけば、メンバー全員が同じ環境で作業できて便利ですね。

適切な権限設定で安全性を確保

なぜ権限設定が重要か

Claude Codeは強力なツールですが、ファイルの編集やコマンドの実行など、システムに影響を与える操作も可能です。

そのため、デフォルトでは多くの操作に対して許可を求めてきます。

しかし、毎回許可を求められるのは効率的ではありません。

安全性を保ちながら効率的に作業するため、適切な権限設定が重要になります。

権限設定の方法

権限の設定には、以下の4つの方法があります。

  1. セッション中に「Always allow」を選択
  2. /permissionsコマンドを使用
  3. 設定ファイルの直接編集
  4. --allowedToolsフラグを使用

よく使うツールは、事前に許可リストに追加しておくと便利です。

色々とやり方はありますが、settings.json で設定するのが整理しやすくておすすめです。

私が書いた無料本の中で詳しく解説していますので、ぜひご覧ください。

https://zenn.dev/tmasuyama1114/books/claude_code_basic/viewer/memory_and_settings_settings_json

GitHubと連携するなら、gh CLIをインストールしておくのもおすすめです。

効果的な開発フローの実践

探索・計画・実装・コミットのワークフロー

Claude Codeを使った開発では、以下のようなフローが効果的です。

  1. 探索：関連ファイルを読み込ませる
  2. 計画：実装方針を立てる
  3. 実装：コードを書く
  4. コミット：変更を保存

ポイントは、いきなりコードを書かせるのではなく、まず計画を立てさせることです。

ちなみに「think」という言葉を使うと、Claude Codeは時間をかけて考えてくれます。

関連ファイルを読み込んで、この機能の実装方針を提案してください think

ちなみに、もーーーっと考えさせたい場合は、「think hard」「think harder」「ultrathink」という言葉を使うことで、より深く考えてくれます。

These specific phrases are mapped directly to increasing levels of thinking budget in the system: "think" < "think hard" < "think harder" < "ultrathink." Each level allocates progressively more thinking budget for Claude to use.

もしくは tab キーを押しても think モードになります。

テスト駆動開発の活用

テストを先に書いてから実装する方法も、Claude Codeに限らずAI駆動開発では非常に効果的です。

  1. テストを書く：期待する動作を明確にする
  2. テストの失敗を確認：まだ実装がないことを確認
  3. テストをコミット：テストの内容を固定
  4. 実装を書く：テストが通るまで繰り返す
  5. 実装をコミット：完成したコードを保存

この方法だと、Claude Codeは明確な目標（テストを通すこと）に向かって作業できるため、より良い結果が得られやすくなります。

「先にゴールを設定して、それに向かって作業させる」というのは、AI駆動開発の基本です。

ビジュアルモックを使った開発

UIを作る場合は、デザインモックを用意してそれに合わせて実装させる方法も効果的です。

  1. デザインモックを提供：画像やスクリーンショットを渡す
  2. 実装を依頼：モックに基づいてコードを書かせる
  3. スクリーンショットで確認：実装結果を画像で確認
  4. 調整を繰り返す：モックに近づくまで修正

視覚的なフィードバックがあると、Claude Codeもより正確な実装ができます。

ビジュアルモックは、Claude Code のみならず、Cursor や Codex などでも使えます。

GitとGitHubの活用

バージョン管理の自動化

Claude Codeは、Gitコマンドを使ったバージョン管理も得意です。

コミットメッセージの作成、ブランチの管理、マージの実行など、多くの作業を任せられます。

変更内容を確認して、適切なコミットメッセージでコミットしてください

実務など、いきなりコミットさせるのが不安という方は「コミットメッセージを考えてください」と指示してみてください。

そのあとに「コミットしてください」と指示することで、安心して作業を進められます。

GitHub連携の活用

GitHub を使っている場合には、GitHub CLI を使っていれば、以下のような作業も可能です。

  • プルリクエストの作成
  • イシューへのコメント
  • コードレビューへの対応
  • ビルドエラーの修正

特に、コードレビューで指摘された内容を修正する作業は、Claude Codeが得意とする分野です。

私の場合、AI が PR につけたレビューコメントを取得して、修正を実行しています。

なお、GitHub CLI については以下の記事がわかりやすいです。

https://zenn.dev/caru/articles/aa088436f69277

GitHub CLI を使う場合には、CLAUDE.md にたとえば以下のように書いておくと便利です。

# GitHub CLI を使って PR を作成する
gh pr create

...(他にも色々書いておく)

「GitHub CLI を使えるんだ」と理解させる助けにもなります。

コマンドのカスタマイズ

スラッシュコマンドの作成

よく使う作業は、カスタムコマンドとして登録しておけます。

.claude/commandsフォルダにMarkdownファイルを作成すると、スラッシュコマンドとして使えるようになります。

たとえば、GitHubイシューにもとづいて修正を実行するコマンドを作る場合...

# .claude/commands/fix-github-issue.md

GitHubイシュー #$ARGUMENTS を確認して、以下を実行：
1. イシューの内容を読む
2. 関連ファイルを特定
3. 修正を実装
4. テストを実行
5. プルリクエストを作成

使用時は以下のように実行します。

/fix-github-issue 1234

マークダウンファイルの中では $ARGUMENTS を使うことで、コマンド実行時に値を渡せるようになります。

ここでは、イシュー番号を渡すことで、そのイシューに対して修正を実行します。

また、ホームディレクトリの ~/.claude/commands/ に置けば、すべてのプロジェクトで共通のコマンドとして使えます。

セキュリティと安全性の確保

危険な操作を避ける

Claude Codeは強力なツールゆえ、以下の点に注意が必要となります。

  • 本番環境では使わない：開発環境での使用に留める
  • 機密情報は扱わない：APIキーやパスワードは別管理
  • 重要なファイルのバックアップ：作業前に必ずバックアップ

コンテナ環境の活用

より安全に使いたい場合は、Dockerコンテナ内での実行がおすすめです。

docker run -it --rm -v $(pwd):/workspace ubuntu:latest
# コンテナ内でClaude Codeを実行

これにより、万が一の際もホストシステムへの影響を最小限に抑えられます。

複数のClaude Codeを並行活用

これは私はあまりやってないのですが、Anthropic が公開しているベストプラクティスにも書かれていますので、紹介しておきます。

ただし、ちょっと上級者向けのテクニックなので、初心者の方は無理にやらなくても大丈夫です。

並行作業で効率化

大きなプロジェクトでは、複数のClaude Codeを同時に走らせることで、開発効率を大幅に向上する手法があります。

たとえば、以下のような使い分けができます。

  • Claude A：新機能の実装
  • Claude B：テストの作成
  • Claude C：ドキュメントの更新
  • Claude D：バグ修正

Gitワークツリーの活用

Gitのワークツリー機能を使えば、同じリポジトリの異なるブランチで並行作業ができます。

git worktree add ../project-feature-a feature-a
cd ../project-feature-a && claude

これにより、複数の機能開発を同時に進められます。

ヘッドレスモードでの自動化

こちらもあまり私は活用しきれていないのですが、Anthropic が公開しているベストプラクティスにも書かれていますので、紹介しておきます。

CI/CDパイプラインへの統合

Claude Codeは、ヘッドレスモード（対話なし）でも動作します。

これを使えば、CI/CDパイプラインに組み込んで自動化できます。

claude -p "このプルリクエストのレビューコメントを分析して、改善案を提案" --output-format stream-json

自動イシュー分類

GitHubのイシューを自動で分類する例：

claude -p "新しいイシューを確認して、適切なラベルを付ける" --dangerously-skip-permissions

ただし、--dangerously-skip-permissionsフラグは慎重に使用してください。

まとめ

Claude Codeは、適切に使えば開発効率が何倍にもアップできるツールです。

今回紹介したベストプラクティスを実践することで、より安全で効率的な開発が可能になるはずです。

特に重要なポイントは以下の3つですので、ぜひ意識してください。

  1. CLAUDE.mdで開発ルールを明文化
  2. 段階的な開発フローの実践
  3. 適切な権限設定とセキュリティの確保

これらを意識しながら、少しずつClaude Codeの機能を試していくことをおすすめします。

最初は小さなタスクから始めて、徐々に複雑な作業を任せていけば、きっと手放せないツールになるはずです。

皆さんもClaude Codeを使って、より効率的な開発を実現してみてください！

その他のClaude Code関連記事

https://zenn.dev/tmasuyama1114/articles/global_rule_file

https://qiita.com/tomada/items/c369d5f28142a2599a36

また、Youtube でも AI 駆動開発の実践動画を公開しています！

https://www.youtube.com/@vibe-coding-studio

よければチャンネル登録していただき、AI駆動開発の実践的な情報をキャッチアップしていってください！

ちょっと宣伝：AI駆動開発を体系的に学びたい方へ

冒頭でも触れましたが Udemy では AI 駆動開発講座を複数開講しており、いくつかベストセラーもいただいています。

https://school.learning-next.app/coupons?topic=claude-code

最大で 90%OFF のクーポンも配布しておりますので、これから学ぶ方はぜひご利用ください。

Webアプリやスマホアプリ、Pythonなど、多くの分野で講座を開講しています！

Discussion