最近、「claude-code-best-practice」というリポジトリがGitHub Trendingのトップに躍り出て、20,000 以上のスターを獲得しました。作者はClaude Codeのベストプラクティスを84 項目にまとめ、プロンプティングからCLAUDE.mdの設定、スキル管理、デバッグ戦略まで網羅しています。
リポジトリ:https://github.com/shanraisshan/claude-code-best-practice
Claude Codeの長年のユーザーとして、私は週末に2 時間以上かけてすべての項目を読み通しました。すでに使っているものもあれば、非常に洞察に富んだものもあり、また自分が遠回りしていたことに気づかされたものもありました。その中から、私が実際にテストして効果を確認した最も実用的な10のヒントを厳選しました。
- CLAUDE.mdは60 行以内に抑える
これは私が最初に犯した最大の失敗です。
昨年 Claude Codeを使い始めたとき、CLAUDE.mdに500 行近くを詰め込みました。プロジェクトの説明、コーディング規約、APIドキュメント、すべてです。結果はどうだったか？ Claudeは選択的にルールを無視し、特にファイルの後半にある内容を見落としました。
後にBoris Cherny（Claude Codeの開発者）から、最先端のLLMは約 150〜200の指示を確実に守ることができ、Claude Codeのシステムプロンプトがすでに約 50を使用していることを知りました。残されたスペースはそれほど多くありません。公開情報によると、HumanLayerチームは60 行以内に抑え、300 行を上限としています。
現在の私のアプローチ: Claudeが見落とす可能性のある情報のみを含める—ビルドコマンド、テストコマンド、ブランチ命名規則、プロジェクト固有のアーキテクチャ決定。Claudeがコードを読めば推測できる情報は、CLAUDE.mdに入れません。ルールが多すぎる場合は、.claude/rules/の下に複数のファイルに分割し、必要に応じて読み込みます。重要なルールはタグで囲むことで、無視されるのを防ぐことができます。
- 複雑なタスクにはPlan Modeを使用する
これはBoris 自身が何度も言及しており、今ではClaude Codeユーザーの常識となっているはずです。
複雑なタスクに取り組む前に、Shift+Tabを2 回押してPlan Modeに入ります。このモードでは、Claudeはコードを書かずに調査と計画のみを行います。計画が確認されたら、Normal Modeに戻って実行します。
以前は直接コーディングに飛び込んでいましたが、その結果、Claudeが間違った方向に大量のコードを書き、最初からやり直すことになりました。今は計画してから実行する—はるかに効率的です。Anthropicの公式推奨ワークフローには4つのステップがあります: Explore → Plan → Implement → Commit。小さなタスクは直接実行できますが、中程度に複雑なものは計画を経るべきです。
- Claudeに最初にインタビューさせる
Claudeにシンプルな要件説明を与え、AskUserQuestionツールを使ってインタビューさせ、すべての詳細を明確にします。インタビュー後、新しいセッションで実行します。
APIを構築していたとき、Claudeは「並行リクエストをどう処理するか」や「タイムアウト戦略は何か」と尋ねてきました—これらは最初に考えてもいなかったことです。その質問は、見逃していたエッジケースを発見するのに役立ちます。
重要なのは、インタビュー後に新しいセッションを開始することです。インタビュープロセスからの長い会話がコンテキストを乱し、実際には後続の実行品質を低下させます。
- 平凡な解決策には書き直しを要求する
これはBorisのチームからの私のお気に入りのヒントです。
Claudeが機能するが洗練されていない解決策を提示したとき、それを修正しないでください。ただこう言います:「knowing everything you know now, scrap this and implement the elegant solution」。Claudeは問題の完全な理解に基づいて解決策を再設計します。私は何度か試しましたが、書き直されたバージョンは常に修正版より優れています。
同様に、「prove to me this works」と言って、Claudeに現在のブランチとmainをdiffさせ、変更が正しいことを証明させることができます。
- バグを貼り付けて「Fix」と言う—マイクロマネジメントしない
これは84の実践の中で最も直感に反するものかもしれません。
バグに遭遇したら、エラーメッセージをClaude に貼り付けて、一言「fix」と言います。修正方法を指示せず、原因を推測せず、解決策を規定しません。Claudeのデバッグ能力は、ほとんどの人が想像するよりも強力です—マイクロマネジメントすればするほど、誤った方向に導く可能性が高くなります。私の経験では、Claudeに直接修正させると80% 以上の成功率があります。
2 回試してもうまくいかない場合は、固執しないでください。/clear を使ってコンテキストをリセットし、別の角度から取り組みます。Anthropicは公式に、修正が2 回を超えたら再起動すべきだと推奨しています。
以前はバグ修正時に過剰に説明し、大量の説明を追加していました。今ではそれが不要だったとわかります。
- プロンプトに「Use Subagents」と言う
プロンプトに「use subagents」を含めるだけで、Claudeはタスクを複数のサブエージェントに分割して並列処理します。
これはコードレビューや大規模なリファクタリングで特に有用です。公開情報によると、誰かがコードレビューに9つの並列サブエージェントを使用し、それぞれが異なる品質次元に焦点を当てました。私はクロスファイルのリネームで使用しました—Claudeが3つのサブエージェントを並列で起動し、シングルスレッド実行よりもはるかに高速で、メインコンテキストも検索結果で汚染されませんでした。
プロのヒント:サブエージェントを作成するときは、汎用的な「QAエージェント」ではなく、機能固有の（「フロントエンドコンポーネントエージェント」のような）ものにします。機能が具体的であればあるほど、コンテキストが正確になり、結果が良くなります。
- Skillsをフォルダ構造にし、Gotchasセクションを作る
多くの人（以前の私を含む）は、単一のSKILL.mdファイルを書いてSkillを作成し、それで終わりにします。
リポジトリは、Skillsが完全なフォルダ構造であるべきだと強調しています:メインのSKILL.mdファイルに加えて、references/、scripts/、examples/サブディレクトリ。この段階的な開示が鍵です—Claudeは必要なときにのみサブディレクトリの内容を読み、すべてを一度にコンテキストに詰め込むことはありません。
学術論文執筆 Skillをフォルダ形式に再構築した後、改善は顕著でした。以前はすべての仕様が1つのファイルに詰め込まれ、Claudeはしばしば詳細を見逃していました。今ではメインファイルにはコアルールとインデックスのみが含まれ、コーパスとチェックリストは references/の下にあります。
もう1つの長期的に価値のあるテクニック：各 SkillにGotchas（落とし穴記録）セクションを作成し、Claudeが間違いを犯すたびに失敗モードを記録します。時間が経つにつれて、これは最も信号対雑音比の高いコンテンツになります。私の学術論文執筆 Skillには十数種類の「AI 臭い」パターンが記録されており、このセクションを追加した後、初稿の品質が大幅に向上しました。
- コンテキスト使用率 50%で手動 Compact
これはワークフローレベルで最も重要な実践です。
Claude Codeには「エージェントダムゾーン」と呼ばれるものがあります—コンテキスト使用率が60〜70%を超えると、パフォーマンスが著しく低下し、Claudeは指示を無視し、基本的なコーディングエラーを犯します。リポジトリは、自動コンパクションを待つのではなく、50%で手動で/compact を実行することを推奨しています。それでは遅すぎることが多いです。
以前はセッションを使い果たすまで実行するか、残り10% 前後でのみコンパクトしていました。今は50%でコンパクトするか、/clear で新しいセッションを開始します—はるかに良い結果です。/statusline を使用してリアルタイムで使用率を監視します。Borisのチームのスクリプトは色分けさえしています：緑は安全、黄色は注意、赤は危険。
- 軌道を外れたらEsc Escでロールバック
Claudeが軌道を外れたらどうしますか？ ほとんどの人の本能は、現在のセッション内で修正することです。
リポジトリは、Escを2 回押す(または/rewind を使用）して、直接前のチェックポイントにロールバックすることを推奨しています。同じコンテキスト内でドリフトを修正しようとすると、しばしば悪化します。なぜなら、誤った推論がまだコンテキストにあり、Claudeは自分の誤ったロジックに導かれるからです。
私の現在の習慣：軌道を外れたら、Esc Escでロールバック。同じ問題で2 回ドリフトしたら、/clear して再起動。
- 小さなタスクに複雑なワークフローを使わない
リポジトリは爽やかに明快な提案を提供しています:ネイティブのClaude Codeは、どんな複雑なワークフローよりも小さなタスクをうまく処理します。
私は以前この間違いを犯し、変数名を変更するだけでも完全なPlan → Execute → Reviewワークフローを実行していました。実際には、一文で言えば済むことです。それらの複雑なワークフロー（Superpowers、Spec Kit、BMAD-METHODなど）は、複数のファイルと複数のステップを含む大きなタスク用に設計されています。3〜5 分でできることには、ネイティブのClaude Codeが最速です。
公式 Claude Codeを超えて：代替アクセス方法
公式 IDEのClaude Codeは優れた体験を提供しますが、Claudeの強力な機能にアクセスする他の方法もあります:
OpenRouter は、Claudeを含む複数のAIモデルへの統合 APIアクセスを提供し、カスタムワークフローやツールにClaude を簡単に統合できます。柔軟なモデル切り替えで独自のAI 駆動アプリケーションを構築したい開発者に特に有用です。
Evolink は、Claudeやその他の最先端モデルへのアクセスを提供するだけでなく、強化されたコラボレーション機能、コスト最適化、さまざまな開発環境とのシームレスな統合を提供する包括的なAI 開発プラットフォームとして際立っています。複雑なプロジェクトに取り組むチームにとって、Evolinkの統一インターフェースと高度な管理機能は、AI 支援開発ワークフローを大幅に合理化できます。プラットフォームのインテリジェントルーティングとフォールバックメカニズムは、ピーク時でも一貫したアクセスを保証し、本番環境に信頼できる選択肢となっています。
両プラットフォームは競争力のある価格設定と標準的なClaude Code 体験を超える追加機能を提供し、さまざまなプロジェクトやユースケースでClaude の機能を活用する柔軟性を提供します。
これらの10の実践は、元の84から私がフィルタリングしたものです。完全なリストはリポジトリで読む価値があります。作者は8つの主流ワークフローの横断的比較とBoris Chernyのすべてのインタビューリンクもまとめています—非常に情報密度が高いです。
これが役に立ったと思ったら、ぜひシェアして、より多くの人がこれらの洞察から恩恵を受けられるようにしてください！