■ 1. リポジトリの概要
shanraisshan/claude-code-best-practiceはGitHub Trending 1位を獲得し、5万スター近くまで伸びているClaude Codeのベストプラクティス集- 設定ファイルのテンプレート集ではなく、「Claude Codeをうまく使うための知識」をリンク付きで整理したリファレンス
- 構成:
- 概念リファレンス（CONCEPTS）: Subagents / Commands / Skills / Hooks / MCP / Memoryなど各機能を一覧化
- Tips & Tricks（82個）: Prompting / Planning / Context / CLAUDE.md / Agents / Hooksなど14カテゴリ、各Tipに出典リンク付き
- 開発ワークフロー比較: Superpowers、Spec Kit、BMAD-METHODなど10以上の手法を比較表で掲載
- 作者のShayan Rais氏はAnthropicの社員ではなくコミュニティの個人
- 価値の源泉は、Boris Cherny（生みの親）、Thariq（エンジニア）、Cat Wu（プロダクト責任者）ら、Anthropic側の発信を一次情報として集約している点にある
■ 2. 大前提: 作り手の設定は「驚くほどバニラ」
- Boris Cherny自身が自分の設定を "surprisingly vanilla"（驚くほど素のまま）と表現
- Claude Codeはそのままでも十分機能するため、過度なカスタマイズは不要
- チームは「使う・カスタマイズする・ハックする」を自由に選べるよう意図的に設計しており、メンバー全員が異なる使い方をしている
- 「すごい設定を大量に積む」のではなく、必要最小限に保ち効果が確実なものだけを入れるのが作り手の思想
■ 3. 軸1: CLAUDE.md はシンプルに保つ
- なぜ短くするか:
- CLAUDE.md は毎セッション先頭に丸ごと読み込まれる常駐メモリ
- 公式ドキュメントは1ファイルあたり200行以下を目標に挙げており、長いファイルはコンテキストを消費し指示の遵守率を下げる
- HumanLayerのDex氏は60行という実例を示しつつ「指示を100%守らせる保証はない」と注記
- r/ClaudeCodeでは「CLAUDE.mdに書いた指示が80%無視される」という報告もある
- 短く保つための具体策:
.claude/rules/への切り出しと遅延ロード:
paths:フロントマターを付けると、Claudeが該当globにマッチするファイルを読んだときにのみロード- ドメイン固有のルールをここに逃がすのが定石
paths:を持たないルールファイルはCLAUDE.mdと同様に毎セッション無条件で読み込まれる- 守られにくいルールは
<important if="...">タグで囲む- モノレポでは各パッケージにCLAUDE.mdを階層配置し、ルートに全部書かない
- 「最低ライン」テスト: どの開発者でもClaude起動直後に「テストを実行して」と言えば一発で通る状態を目標とし、通らないならセットアップ・ビルド・テストの基本コマンドが欠けているサイン
- 「設定で決まること」をCLAUDE.mdに書かない:
- 決定論的に設定できることをお願いベースの自然言語でCLAUDE.mdに書かない
- 例: 「コミットにCo-Authored-Byを付けるな」と書くより
settings.jsonのattribution.commit: ""で機械的に止める方が確実- CLAUDE.mdは「コンテキスト（お願い）」であって強制ではなく、確実に効かせたい挙動は設定やフックで担保する
■ 4. 軸2: ハーネスエンジニアリング
- ハーネスとは:
- Claude本体ではなく、その周りを取り囲む足場・治具のこと
- フック、権限設定、検証スクリプト、スラッシュコマンド、サブエージェントの総称
- Borisの主張: 「モデルを賢くしようとするな、モデルが失敗しにくい仕組みを作れ」
- Claudeに「検証手段」を与える（Boris曰く最重要のTip）:
- Claudeが自分の作業をその場で検証できる手段を渡すことで最終成果物の質が2〜3倍になる
- テスト、型チェック、E2E、ブラウザ操作など「正解かどうか自分で確認できる経路」を与えると、Claudeは失敗を自分で見つけて直すようになる
/goスキルの例: (1) bash・ブラウザ・computer useでend-to-endにテスト → (2) /simplifyで整理 → (3) PRを作成- フックで「最後の10%」を機械的に埋める:
- BorisのPostToolUseフックの例: Write/Edit後に
bun run format || trueを自動実行- 「Claudeにフォーマットを守らせる」ではなく「フックで機械的に整える」という発想
- 確率的な自然言語指示ではなく決定論的な後処理に落とす
- 実用的なフックTip:
- Stopフックでターン終了時に「続けろ・検証しろ」とClaude を促す
- 権限リクエストをOpusに回して攻撃を自動スキャン・安全なものは自動承認させる
- PreToolUseフックでスキルの使用回数を計測し、効いていないスキルを特定する
- 権限は「pre-allow」を使い
--dangerously-skip-permissionsは使わない:
- 安全だと分かっているコマンドだけを
/permissionsで事前許可し.claude/settings.jsonにチェックイン- Autoモード（モデルベースの分類器が各コマンドの安全性を判定して自動承認）が全許可フラグの正しい代替
■ 5. 最小構成の例
- CLAUDE.md（短く・基本コマンド中心）:
- プロジェクト概要を1〜2行
- セットアップ・ビルド・テストの基本コマンドを列挙
- 守られにくいものだけ
<important>タグで囲む.claude/settings.json（決定論的に効かせるもの）:
- フォーマット用のPostToolUseフック
- 安全なコマンドの事前許可
- attributionなど機械的に決まる設定
.claude/rules/*.md（paths:で遅延ロード）:
- ドメイン固有の細かいルール
- 役割分担の要点: 「お願い」はCLAUDE.mdに最小限、「強制」はsettings.jsonに
■ 6. Boris Cherny氏のCLAUDE.md（参考）
- ワークフローオーケストレーション:
- 非自明なタスク（3ステップ以上や設計判断を含む）は必ずPlanモードで開始
- サブエージェントを積極的に活用してメインのコンテキストウィンドウを清潔に保つ
- ユーザーから修正を受けたら
tasks/lessons.mdにパターンを記録し、同じ失敗を繰り返さないルールを書く- 完了マークを付ける前に必ず動作を証明する
- 非自明な変更では「より優れた方法はないか」と自問し、場当たり的な修正を避ける
- バグレポートを受けたら自律的に修正する（ユーザーの手引きを不要にする）
- タスク管理:
- 計画をチェックリスト形式で
tasks/todo.mdに書き、実装前に確認する- 各ステップでハイレベルなサマリーを提示し、修正後は
tasks/lessons.mdを更新する- コア原則:
- シンプルさ最優先: 変更は可能な限り小さくし、影響するコードを最小限にする
- 手を抜かない: 根本原因を探り、一時的な修正を避け、シニアエンジニアの水準で対応する
- 影響範囲の最小化: 必要な箇所だけを変更し、バグの混入を防ぐ
■ 7. 開発ワークフロー比較の要点
- 10以上の手法（Superpowers、Spec Kit、BMAD-METHODなど）はすべて同じ骨格に収束する
- Research → Plan → Execute → Review → Ship
- Borisのセッション運用:
- ほとんどのセッションをPlanモードで開始（Shift+Tab 2回）
- コーディングはOpus + thinkingで実施（大きく遅いが、ステアリングが減る分結局速い）
- 1日に何度もやる「インナーループ」はスラッシュコマンド化してgitにチェックイン
- 1日1回以上やることはスキルかコマンドにする
- 「賢いプロンプトを毎回打つ」より「繰り返す作業を仕組みにする」という点でハーネスの思想と一貫する
■ 8. まとめ
claude-code-best-practiceは設定を丸ごとコピーするためのリポジトリではなく、Anthropicの作り手たちの一次情報を集約したリファレンス- 核心は以下の2点:
- CLAUDE.md はシンプルに: 長く書くより基本コマンドを揃え、ドメインルールは
rules/に逃がし、強制したいことは設定で機械的に効かせる- ハーネスを組む: Claudeを賢くしようとするより、Claudeが自分で検証・修正できる足場（検証手段・フック・権限設計）を整える
- Boris Chernyが "surprisingly vanilla" と言うのは、「設定を盛る」のではなく「失敗しにくい仕組みを作る」という引き算の設計思想の表れ
- リポジトリを見るなら、まずTips & Tricksの「CLAUDE.md」と「Hooks」カテゴリから確認するのが効率的