Claude Code ベストプラクティス — 成果を安定させる 7 つの鉄則と公式ガイドの設計思想

qiitapoi 氏のポストが、Qiita 記事「Claude Code ベストプラクティス – 成果を安定させる 7 つの鉄則」を紹介しています。この記事は、Claude Code の公式ベストプラクティスを実務者の視点で 7 つのルールに凝縮したもので、「具体的に頼む」「必ず検証する」という基本から、セッション管理やコスト意識まで、日々の運用に直結する指針をまとめています。

本記事では、この 7 つの鉄則を公式ドキュメントの設計思想と照らし合わせながら、なぜそのルールが効くのかを掘り下げます。

公式ベストプラクティスの根本原則: コンテキストウィンドウ

Claude Code 公式ベストプラクティスは、冒頭で明確に述べています。

ほとんどのベストプラクティスは 1 つの制約に基づいています。Claude のコンテキストウィンドウはすぐにいっぱいになり、満杯になるにつれてパフォーマンスが低下します。

Claude Code の 200K トークンのコンテキストウィンドウには、すべてのメッセージ、読み取ったファイル、コマンド出力が蓄積されます。コンテキストが埋まるにつれて、初期の指示を「忘れる」、ミスが増えるといった品質低下が起きます。7 つの鉄則のほぼすべてが、この制約への対処法として理解できます。

7 つの鉄則と公式ガイドの対応

nogataka 氏の Qiita 記事が提案する 7 つの鉄則を、公式ドキュメントの推奨事項と対応させて整理します。

鉄則内容公式ガイドの対応セクション
1. 具体的に頼む5W1H で指示を明確にするプロンプトで具体的なコンテキストを提供する
2. 必ず検証するdiff、テスト、コストの 3 点確認Claude に自分の作業を検証する方法を与える
3. CLAUDE.md でルール言語化プロジェクト固有の規約を明文化する効果的な CLAUDE.md を書く
4. セッション短く保つ1 タスク 1 セッションセッションを管理する
5. 計画→実行の 2 段階5 分ルールで判断最初に探索し、次に計画し、その後コーディングする
6. コスト意識/cost で定期確認コンテキストを積極的に管理する
7. 自動化への次ステップHooks, MCP, Agent Teams自動化とスケール

7 つの鉄則は、公式ガイドの膨大な内容を実務者が日常的に参照できる形に圧縮したものと位置づけられます。

鉄則 1: 具体的に頼む

曖昧な指示は、Claude の試行錯誤を増やし、トークンを浪費します。

5W1H チェックリスト

要素確認すること例
何を対象ファイル・関数・コンポーネントsrc/auth/login.ts の validateToken 関数
どこを変更箇所の特定エラーハンドリング部分
なぜ目的・背景セッションタイムアウト後のリフレッシュが失敗する
どこまで完了条件テストが通り、既存テストも壊れない
制約ライブラリ、規約、互換性外部ライブラリ追加不可

公式の推奨: Before / After パターン

公式ドキュメントは、具体的な Before / After の対比を示しています。

Before: 「ログインバグを修正する」

After:  「ユーザーはセッションタイムアウト後にログインが失敗すると
        報告しています。src/auth/ の認証フロー、特にトークン更新を
        確認します。問題を再現する失敗するテストを書き、その後修正する」

After の指示は、症状の説明、調査範囲の指定、検証方法の指定の 3 要素を含んでいます。この 3 要素を意識するだけで、指示の精度は大幅に向上します。

鉄則 2: 必ず検証する

公式ドキュメントは、検証を「あなたができる最もレバレッジの高いこと」と位置づけています。

3 つの検証ポイント

検証項目目的方法
diff 確認意図しない変更の検出git diff で変更箇所を確認
テスト実行既存機能の保証テストスイートの実行
コスト確認トークン消費の把握/cost コマンド

検証手段を Claude 自身に与える

公式が強調するのは、Claude 自身に検証手段を提供することです。テストを実行させる、スクリーンショットを撮って比較させる、期待される出力と照合させるなど、Claude が自分でフィードバックループを回せる環境を作ります。

「validateEmail 関数を書く。テストケースの例：
user@example.com は true、invalid は false、user@.com は false。
実装後にテストを実行する」

検証基準がないと、正しく見えるが実際には機能しないコードが生成されるリスクが高まります。

鉄則 3: CLAUDE.md でルール言語化

CLAUDE.md は、Claude がすべての会話の開始時に自動的に読み込む特別なファイルです。

含めるべき内容と除外すべき内容

含める除外する
Claude が推測できない Bash コマンドコードを読めば分かること
デフォルトと異なるコードスタイル標準的な言語規約
テスト指示・テストランナー詳細な API ドキュメント
リポジトリのエチケット頻繁に変わる情報
プロジェクト固有のアーキテクチャ決定長い説明やチュートリアル

「削除テスト」で肥大化を防ぐ

公式ドキュメントの重要なアドバイスです。

各行について「これを削除すると Claude が間違いを犯しますか？」と尋ねてください。そうでない場合は、削除します。

CLAUDE.md が長すぎると、Claude が重要なルールをノイズに埋もれて無視する原因になります。公式は「CLAUDE.md をコードのように扱う」ことを推奨しています。定期的にレビューし、不要な部分を削除し、Claude の動作が変わるかを観察するのが実践的なアプローチです。

ドメイン知識は Skills に分離する

CLAUDE.md はすべてのセッションで読み込まれるため、常に適用されるルールのみを含めるべきです。特定のドメインに関する知識やときどきしか使わないワークフローは、Skills として .claude/skills/ に分離します。Claude はオンデマンドで読み込むため、すべての会話のコンテキストを圧迫しません。

鉄則 4: セッション短く保つ

長時間セッションの問題は、コンテキストウィンドウの根本制約に直結します。

1 タスク 1 セッションの原則

公式ドキュメントが挙げる「一般的な失敗パターン」の筆頭が「キッチンシンクセッション」です。

1 つのタスクで開始し、関連のないことを Claude に尋ね、最初のタスクに戻ります。コンテキストは関連のない情報でいっぱいです。

修正は単純です。関連のないタスク間で /clear を実行してコンテキストをリセットします。

品質低下の兆候

以下の兆候が現れたら、セッションが長くなりすぎています。

  • 以前伝えた指示を忘れる
  • 命名規則がズレ始める
  • 依頼していないファイルを編集する
  • 同じ問題の修正を 2 回以上繰り返す

公式は「2 回の失敗した修正の後、/clear を実行し、学んだことを組み込んだより良い初期プロンプトを書く」ことを推奨しています。蓄積された修正を持つ長いセッションより、良いプロンプトを持つきれいなセッションの方が、ほぼ常に良い結果を生みます。

鉄則 5: 計画→実行の 2 段階

5 分ルール

Qiita 記事が提案する判断基準は明快です。

見積もりアクション
5 分未満直接実行
5 分以上計画から開始

公式ドキュメントも同様の判断基準を示しています。「差分を 1 文で説明できる場合は計画をスキップ」し、「アプローチについて不確実な場合、変更が複数ファイルにまたがる場合、コードに不慣れな場合」は計画を挟みます。

公式の 4 フェーズ

公式ドキュメントは、計画→実行をさらに細かく 4 フェーズに分解しています。

1. 探索（Plan Mode）: ファイルを読み、構造を理解する
2. 計画（Plan Mode）: 実装計画を作成する
3. 実装（Normal Mode）: コーディングとテスト
4. コミット: PR 作成

Plan Mode（Shift+Tab で切替）では Claude がファイルを読み取り質問に答えますが、変更は加えません。探索と実装を分離することで、「間違った問題を解決するコード」の生成を防ぎます。

鉄則 6: コスト意識

トークン消費の管理

/cost コマンドでセッション中のトークン消費を確認できます。コスト削減のポイントは、他の鉄則の実践そのものです。

削減策関連する鉄則
指示の具体化鉄則 1
.claudeignore で不要ファイル除外鉄則 3
セッション分割鉄則 4
サブエージェントで調査を分離鉄則 4, 5

避けるべきパターン

  • 大きなファイルの丸貼り
  • 範囲を指定しない広範な指示
  • 関連のないタスクの並行処理

公式ドキュメントは、サブエージェントを「コンテキストが基本的な制約であるため、利用可能な最も強力なツールの 1 つ」と位置づけています。調査をサブエージェントに委譲すると、メインのコンテキストを消費せずに探索できます。

鉄則 7: 自動化への次ステップ

基本の 6 つの鉄則を習得した後、Claude Code の拡張機能を活用して自動化の範囲を広げます。

4 つの発展方向

機能用途具体例
CLAUDE.md 拡張スコープ階層的な設定管理モノレポの親子ディレクトリごとに異なるルール
Hooks確実な自動実行ファイル編集後に必ず ESLint を実行
MCP サーバー外部サービス連携Notion、Figma、データベースとの統合
Agent Teams並列処理複数エージェントによる同時作業

CLAUDE.md の指示 vs Hooks

CLAUDE.md の指示は「勧告的」であり、Claude が従わない場合もあります。一方、Hooks は「決定的」であり、例外なく毎回実行されます。「必ず実行してほしい処理」は Hooks に移行することで、確実性が向上します。

実践のロードマップ

Qiita 記事が推奨する段階的な導入順序は、公式ドキュメントの構成とも整合しています。

Phase 1: 鉄則 1（具体的に頼む）+ 鉄則 2（必ず検証する）
   → 出力品質の安定化を実感する

Phase 2: 鉄則 3（CLAUDE.md）+ 鉄則 4（セッション管理）
   → プロジェクト固有のナレッジを蓄積する

Phase 3: 鉄則 5（計画→実行）+ 鉄則 6（コスト意識）
   → 効率的な開発フローを確立する

Phase 4: 鉄則 7（自動化）
   → Hooks, MCP, Agent Teams で規模を拡大する

まず鉄則 1 と 2 から始めるのが効果的です。指示の具体化と検証の習慣化だけで、出力の品質は大きく変わります。その安定を実感してから、残りの鉄則を段階的に導入します。

まとめ

  • 7 つの鉄則は公式ベストプラクティスの実務者向け圧縮版: 公式の膨大な推奨事項を日常的に参照できる形にまとめている
  • すべての根本はコンテキストウィンドウの制約: 200K トークンの枠を管理することが、Claude Code 運用の最重要課題
  • 「具体的に頼む」と「必ず検証する」が最優先: この 2 つだけで出力品質は大幅に安定する
  • CLAUDE.md は「削除テスト」で肥大化を防ぐ: 削除しても Claude の動作が変わらないルールは不要
  • セッションは短く、計画は必要な時だけ: 5 分ルールで判断し、関連のないタスク間で /clear を実行する
  • サブエージェントはコンテキスト管理の最強ツール: 調査を分離してメインのコンテキストを保護する
  • 自動化は段階的に導入する: まず基本の 6 鉄則を習得してから Hooks, MCP, Agent Teams に進む

参考