Anthropicが提案するClaude Codeのベストプラクティス

なんとなくClaude Codeを使っていませんか？

私自身、まさにそうでした。
AIの力は強力なので、それでもある一定のプロダクトや機能は作れていました。
しかし、

• 修正してほしくないところが修正されてしまう
• UIが崩れてしまう
• 思った通りの動作にならない

など問題が生じてきていて、そろそろ「なんとなく」コーディングをするのではなく
AIコーディングの基礎から学び直したい、と思ったわけです。

そしたら見つけました。
「Anthropic公式が提案するベストプラクティス」

これは…信頼できる！！
Anthropic社が言うには、単なるコード生成ではなくAIと一緒に考え、設計し、改善していく "Agentic Coding" をしましょうとのこと。

この記事では、そのAgentic Codingの基本的なベストプラクティスを、公式記事に基づいて解説していきます。

英語が読める方はぜひ公式記事をご参照ください。

まず始めに：プロジェクトをAIに理解してもらう

Agentic codingの第一歩は、AIにあなたのプロジェクトを理解してもらうことです。これがないと、どんなに優秀なAIでも的外れな提案をしてしまいます。

CLAUDE.mdファイルの役割

多くの方が知っていると思いますが、改めて簡単に説明すると、CLAUDE.mdは「AIへの説明書」です。新しいチームメンバーに渡すオンボ資料のように、AIがあなたのプロジェクトで効率的に働けるよう必要な情報をまとめたファイルです。

なぜCLAUDE.mdが必要なのか？

• AIは毎回ゼロからプロジェクトを理解する必要がある
• 開発ルール、コーディング規約、テスト手順などを毎回説明するのは非効率
• プロジェクトの「文脈」を共有することで、より適切な提案が可能に

シンプルなCLAUDE.mdから始める

CLAUDE.mdの作成方法は、プロジェクトの状況によって2つのアプローチがあります：

既存プロジェクトの場合：/initコマンドを活用

手順：

1. プロジェクトのルートディレクトリでClaude Codeを起動
2. /initコマンドを実行
3. Claudeが自動でプロジェクトを分析し、CLAUDE.mdを生成

新規プロジェクトの場合：対話的に作成

アプローチ：
Claudeと対話しながら、プロジェクトの詳細を詰めて一緒にCLAUDE.mdを作成します

実際の会話例：

開発者：「新しいWebアプリを作りたいんですが、CLAUDE.mdを一緒に作ってもらえますか？」

Claude：「承知しました。まず、どのようなアプリを作る予定ですか？」

開発者：「React + TypeScript でTodoアプリを作りたいです」

Claude：「良いですね。技術スタックについて確認させてください：
- スタイリングはどうしますか？（CSS Modules、Tailwind、styled-components等）
- 状態管理は必要ですか？
- バックエンドとの連携は予定していますか？」

開発者：「Tailwind CSSでスタイリングして、バックエンドはREST APIで連携予定です」

Claude：「承知しました。では、これらの情報を元にCLAUDE.mdを作成しますね」

生成されるCLAUDE.mdの例：

# プロジェクト概要
React + TypeScript + Tailwind CSSで作るTodoアプリ

# 開発環境
- Node.js 18+
- npm run dev でローカルサーバー起動
- npm run build でビルド
- npm test でテスト実行

# コーディング規約
- 関数コンポーネントを使用
- TypeScriptの型定義を必須
- Tailwind CSSでスタイリング
- ファイル名はkebab-case

# プロジェクト構造
- src/components/ : 再利用可能なコンポーネント
- src/pages/ : ページコンポーネント
- src/hooks/ : カスタムフック
- src/utils/ : ユーティリティ関数

段階的に充実させる

最初は上記のような基本的な内容から始めて、開発を進めながら以下を追加していきます：

レベル2：開発フローを追加

• Git の使い方（ブランチ戦略など）
• PR作成時の注意点
• コードレビューのポイント

レベル3：プロジェクト固有の情報

• よく使う外部ライブラリの使い方
• API仕様やデータ構造
• 過去の設計判断とその理由

重要なのは「完璧を求めない」こと

CLAUDE.mdは一度書いたら終わりではありません。開発を進めながら「これをAIに説明するの面倒だな」と思ったことを追加していけば、自然と充実していきます。

実践：3つの基本ワークフロー

Anthropic社が推奨する3つの基本ワークフローを、具体例とともに紹介します。どれも「AIと一緒に考える」ことを重視した手法です。

1. 「見る→考える→作る」アプローチ（Explore, Plan, Code）

従来の問題: いきなりコードを書き始めて、後で大幅修正が必要になる

Agentic codingのアプローチ：

1. Explore（探索）：既存のコードを理解する
2. Plan（計画）：AIと一緒に実装計画を立てる
3. Code（実装）：段階的にコードを書く

実際の例：

開発者：「既存のユーザー認証システムに2FA機能を追加したい」

1. Explore段階：
開発者：「まず現在の認証システムがどうなっているか調べてください」
AI：「認証関連のファイルを調査しました。JWT トークンベースで...」

2. Plan段階：
開発者：「2FA機能を追加するための詳細な計画を立てましょう」
AI：「以下の手順で進めることを提案します：
- TOTPライブラリの導入
- QRコード生成機能の実装
- 認証フローの修正...」

3. Code段階：
開発者：「まずはTOTPライブラリの導入から始めましょう」
AI：「了解しました。段階的に実装していきます」

このアプローチの効果：

• 設計ミスが減る
• 実装の方向性が明確になる
• 後戻りが少なくなる

2. テストから始める開発手法（Test-Driven Development）

従来の問題：実装後にテストを書くと、テストが形骸化しやすい

Agentic codingのアプローチ：

1. テストを先に書く：期待する入力・出力を定義
2. テストの失敗を確認：実装前にテストが失敗することを確認
3. 実装する：テストが通るまで開発
4. 反復する：すべてのテストが通るまで改善

実際の例：

開発者：「パスワード強度チェック機能を作りたい」

1. 要件明確化：
AI：「どのような条件でパスワードを強度判定しますか？」
開発者：「8文字以上、大文字小文字数字記号を含む」

2. テスト作成：
AI：「まずテストケースを作成しましょう」
-------
describe('password strength checker', () => {
  it('should return weak for short passwords', () => {
    expect(checkPasswordStrength('abc')).toBe('weak');
  });
  
  it('should return strong for complex passwords', () => {
    expect(checkPasswordStrength('MyP@ssw0rd')).toBe('strong');
  });
});
-------

3. 実装：
AI：「テストが通るように実装します」

4. 検証：
開発者：「別のClaude インスタンスでこのコードをレビューしてください」

このアプローチの効果：

• 要件が明確になる
• バグの発見が早い
• リファクタリングが安全になる

3. 視覚的フィードバックによる改善サイクル（Visual Iteration）

従来の問題：UI開発で完成イメージと実際の出力にギャップがある

Agentic codingのアプローチ：

1. 視覚的な目標を設定：デザインモックや参考画像を共有
2. 実装してスクリーンショットを撮る
3. 比較・改善：2〜3回の反復で品質を向上

実際の例：

開発者：「このデザインモックの通りにダッシュボードを作ってください」
[デザイン画像を共有]

AI：「実装しました。スクリーンショットを撮って確認してください」

1回目のフィードバック：
開発者：「色味が少し違いますね」[スクリーンショット共有]
AI：「カラーパレットを調整します」

2回目のフィードバック：
開発者：「レイアウトがほぼ完成しました。レスポンシブ対応をお願いします」
AI：「モバイル向けのレイアウトを調整します」

3回目で完成：
開発者：「完璧です！」

このアプローチの効果：

• デザインの再現度が高い
• 修正回数が最小限になる
• 視覚的な確認で品質が向上

3つのワークフローを組み合わせる

実際の開発では、これらのワークフローを組み合わせて使用することで、より効率的な開発が可能になります。プロジェクトの性質に応じて、最適な手法を選択しましょう。

効果を最大化する実践のコツ

3つの基本ワークフローを理解したら、次は実際の開発で効果を最大化するための実践的なコツを身につけましょう。

1. 具体的な指示の出し方

ダメな例：

開発者：「ログイン機能を作って」

良い例：

開発者：「ユーザー認証システムを作りたいです。以下の要件で：
- メールアドレス・パスワードでログイン
- JWT トークンを使用
- ログイン失敗時は3回までリトライ可能
- 失敗回数上限でアカウントロック
- 実装言語：TypeScript + Express
まず要件の確認から始めましょうか？」

具体的な指示のポイント：

• 要件を明確に：何を作りたいか詳細に
• 技術要件も指定：使用ライブラリや言語
• 制約条件も伝える：セキュリティ要件など
• 段階的な進行を提案：「まず〜から」

2. 早期軌道修正の重要性

問題: AIが間違った方向に進んでいても、遠慮して最後まで待ってしまう

解決策：「コース修正」を恐れない

実際の例：

AI：「ログイン機能を実装しました。セッション管理にはCookieを使用して...」

開発者：「すみません、少し軌道修正をお願いします。
認証方式はJWTトークンベースでお願いします。
Cookieベースの実装は今回は使わない方針です」

AI：「承知しました。JWTベースの認証に変更します」

軌道修正のタイミング：

• 想定と違う技術選択をしている時
• 設計方針がずれている時
• 要件の解釈が間違っている時

**重要：**修正は早ければ早いほど効果的です

3. AIとのコミュニケーション術

3-1. 「なぜ」を共有する

ダメな例：

開発者：「この方法じゃなくて、こっちの方法で」

良い例：

開発者：「提案いただいた方法も良いのですが、
今回は保守性を重視したいので、
より単純な実装にしたいと思います」

3-2. 中間チェックポイントを設ける

効果的な進行例：

開発者：「では、まず基本的なログイン機能を実装して、
動作確認をしてから次のステップに進みましょう」

AI：「承知しました。基本機能の実装が完了しました」

開発者：「テストしてみます...動作確認できました！
次はエラーハンドリングを追加しましょう」

3-3. /clear コマンドを活用する

**問題：**会話が長くなると、AIが初期の方針を忘れがち

**解決策：**Claude Code の /clear コマンドで文脈をリセット

使用タイミング：

• 大きな機能の区切りで
• 方針転換をする時
• 会話が散漫になった時

4. チェックリストを活用する

複雑なタスクでは、チェックリストをAIと共有することで抜け漏れを防げます。

例：

開発者：「API開発のチェックリストを確認しながら進めましょう：
□ 基本的なCRUD機能
□ バリデーション
□ エラーハンドリング
□ 認証・認可
□ テストケース
□ API ドキュメント
まずは基本的なCRUD機能から始めます」

5. 「明確なゴール」を設定する

ダメな例：

開発者：「いい感じのダッシュボードを作って」

良い例：

開発者：「ダッシュボードを作りたいです。完成の定義は：
- ユーザー数、売上、アクティブ率の3つの指標を表示
- グラフは Chart.js を使用
- レスポンシブ対応
- 本日中にMVPを完成させる
この定義で問題ないでしょうか？」

実践のまとめ

これらのコツを使うことで、AIとの開発効率は格段に向上します。最初は意識的に実践し、徐々に自然にできるようになることを目指しましょう。

重要なのは「AIはパートナー」という意識です。
命令するのではなく、一緒に問題を解決していく姿勢が、最高の結果を生み出します。

最後に：「なんとなく」から「戦略的」へ

Claude CodeのようなAIツールは、使い方次第で結果が大きく変わります。

戦略的に、意図的に使って最強の開発パートナーにしていきましょう。

---

参考文献：Claude Code Best Practices - Anthropic Engineering

この記事は2025年7月8日時点の情報に基づいています。最新の機能や変更点については公式ドキュメントをご確認ください。