shanraisshan/claude-code-best-practice とは？GitHubトレンド1位の全貌
2025年10月31日に公開されたGitHubリポジトリ shanraisshan/claude-code-best-practice が、2026年4月時点でスター36,012・フォーク3,393を記録し、GitHubトレンドの1日最多獲得リポジトリに輝いた。
このリポジトリが特別な理由は、Claude Code開発者のBoris Cherny氏自身が貢献・紹介していることだ。タイトルの「practice made claude perfect」が示す通り、「振る舞いコーディング（vibe coding）からエージェントエンジニアリングへ」の実践的な移行を支援するコンテンツが集約されている。
リポジトリの構成は以下の通りだ：
| ディレクトリ | 内容 |
|---|---|
tips/ |
Boris Cherny他からのTipsまとめ（10Tips/15Tips等） |
best-practice/ |
Claude Commands・Skills・Subagents等の詳細リファレンス |
tutorial/ |
ハンズオンチュートリアル |
implementation/ |
実装例集 |
orchestration-workflow/ |
ワークフロー図（天気システム等） |
agent-teams/ |
マルチエージェントチームの例 |
.claude/ |
スキル・エージェント・フック・コマンドの実装例 |
対象読者は「Claude Codeをすでに使っているが、まだポテンシャルを引き出しきれていないエンジニア」だ。これからClaude Codeを始める人にはClaude Code vs Cursor徹底比較2026年版が導入として最適だが、本記事はClaude Codeを使い倒したいエンジニア向けの実践ガイドを提供する。
最重要：CLAUDE.md の作り方と7つのベストプラクティス
プロジェクトルートで
/init を実行すると、Claude Codeがビルドシステム・テストフレームワーク・コードパターンを解析してCLAUDE.md の下書きを自動生成する。これを土台に育てていく。
CLAUDE.md はすべてのセッションでClaudeが最初に読む「恒久的なコンテキスト」だ。リポジトリの CLAUDE.md を見ると、以下のような実践的パターンが確認できる：
# CLAUDE.md 基本構成例
## リポジトリ概要
このリポジトリは天気システムのデモ実装...
## アーキテクチャ
Command → Agent → Skill の3層構成
- /weather-orchestrator コマンド（.claude/commands/weather-orchestrator.md）
- weather-agent（.claude/agents/weather-agent.md）
- weather-fetcher スキル（.claude/skills/weather-fetcher/SKILL.md）
## ワークフロールール
- サブエージェントはbashからではなくAgentツール経由で起動する
- 設定階層は managed > CLI args > local > team > global の順
何を書き、何を書かないか
「このルールを削除してもClaudeが間違いを犯すか？」 と問い、NOなら削除する。これが最も重要なCLAUDE.md管理の原則だ。
| ✅ 書くべき内容 | ❌ 書かなくていい内容 |
|---|---|
| Bashコマンド（Claudeが推測できないもの） | コードから読み取れる内容 |
| デフォルトと異なるコードスタイルルール | 標準的な言語慣習 |
| テスト方法・使用テストランナー | 詳細なAPIドキュメント（リンクでOK） |
| ブランチ命名・PR慣習 | 頻繁に変わる情報 |
| プロジェクト固有のアーキテクチャ判断 | 自明な慣習（「きれいなコードを書く」等） |
| 環境固有の注意点（必要な環境変数等） | ファイルごとの説明 |
@importで複数ファイルに分割する
# CLAUDE.md でのimport例
See @README.md for project overview and @package.json for available npm commands.
# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md
CLAUDE.mdが200行を超えそうなら、@インポートで分割する。サブディレクトリに子CLAUDE.mdを置くことで、そのディレクトリのファイルを扱う時だけ読み込まれる。
設定ファイルの6層ヒエラルキー
設定の優先順位（高→低）:
1. managed-settings.json（組織強制・MDM/plist/Registry）
2. CLIコマンドライン引数
3. .claude/settings.local.json（個人プロジェクト設定・git除外）
4. .claude/settings.json（チーム共有設定）
5. ~/.claude/settings.json（個人グローバルデフォルト）
6. hooks-config.local.json > hooks-config.json（フック設定）
訂正を加えるたびに、最後に「CLAUDE.mdを更新してこの間違いを繰り返さないように」と伝える。Claudeは自分自身のルールを書くのが得意で、これを続けると間違い率が目に見えて下がる。
並列実行・Gitワークツリー：最大の生産性向上テクニック
「3〜5個のgitワークツリーを同時に走らせることが、最大の生産性向上施策だ」 — Boris Cherny（Claude Code作者）
これはチーム内で最も評価されるTipだとBorisは述べている。なぜ並列実行がそこまで重要なのか？
Claude Codeのボトルネックはコンテキストウィンドウの消費だ。1つのセッションでコードを書きながら調査・デバッグ・テストをやり続けると、コンテキストが汚染されてパフォーマンスが下がる。独立したワークツリーで別々のタスクを走らせることで、コンテキストを常にクリーンに保てる。
# git worktreeの基本操作
git worktree add ../my-project-feature-a feature-a
git worktree add ../my-project-bugfix bugfix/login-issue
# Claude Codeでワークツリーセッションを開始
claude -w # 新しいワークツリーでセッション開始
# よく使うシェルエイリアスの例（Boris流）
alias 2a='cd ~/worktrees/feature-a && claude'
alias 2b='cd ~/worktrees/feature-b && claude'
alias 2c='cd ~/worktrees/bugfix && claude'
Writer/Reviewerパターン
複数セッションで品質を上げるパターンが公式ドキュメントで紹介されている：
バイアスのないレビューが可能
レビュアーセッションが「書いた当人ではない」ことが重要だ。同じコンテキストで書いたClaudeはそのコードに対してバイアスを持つが、フレッシュなセッションはバイアスなしにレビューできる。
/batch：大規模変更の並列実行
# /batch コマンドの使い方
1. /batch を実行
2. Claudeがインタビュー形式でタスクを聞き出す
3. 必要な数だけワークツリーエージェントを起動
4. 各エージェントが独立して作業
5. 結果を統合
# 用途例
- Pythonファイル2,000本をReact→Vueに移行
- 全エンドポイントのOpenAPI仕様を自動生成
- コードベース全体の型注釈を追加
また、claude -p と for ループを組み合わせることでスクリプト化もできる：
# ファイルリストをループして並列マイグレーション
for file in $(cat files.txt); do
claude -p "Migrate $file from React class to functional component" \
--allowedTools "Edit,Bash(git commit *)" \
--bare &
done
wait
スキル・コマンド・サブエージェント：Claude Codeを拡張する3つの武器
リポジトリが最も詳しく解説しているのが、この3つのプリミティブだ。Claude Codeの内部アーキテクチャでも解説したように、Claude Codeは拡張可能な設計になっている。
Command → Agent → Skill アーキテクチャ
/weather-orchestrator"] --> C["Command
.claude/commands/weather-orchestrator.md
エントリポイント：C/F確認・エージェント・スキル呼び出し"] C --> A["Agent
.claude/agents/weather-agent.md
気温取得（weather-fetcherスキル事前ロード済み）"] A --> S1["Skill（Agent専用）
.claude/skills/weather-fetcher/SKILL.md
Open-Meteo API呼び出し手順"] C --> S2["Skill（直接呼び出し）
.claude/skills/weather-svg-creator/SKILL.md
SVG天気カード作成・ファイル書き込み"] style U fill:#FF6B35,color:#fff style C fill:#7C3AED,color:#fff style A fill:#2563EB,color:#fff style S1 fill:#059669,color:#fff style S2 fill:#059669,color:#fff
2種類のスキル呼び出しパターンがある：
- Agentスキル：
skills: [weather-fetcher]フィールドでエージェントに事前ロード - 直接スキル：Skill ツールで明示的に呼び出す
スキルの定義（SKILL.md）
# .claude/skills/fix-issue/SKILL.md
---
name: fix-issue
description: Fix a GitHub issue end-to-end
disable-model-invocation: true # 副作用ありのためユーザーが明示的に起動
argument-hint: "[issue-number]"
allowed-tools: Bash(gh issue view *), Read, Edit, Bash(git *)
---
以下の手順でGitHub Issueを修正する: $ARGUMENTS
1. `gh issue view <number>` でIssue詳細を取得
2. 問題の原因を特定してコードを検索
3. 修正を実装してテストを書く
4. lintとtype checkを実行
5. コミットしてPRを作成
/fix-issue 1234 で実行。disable-model-invocation: true にすることで、副作用のあるワークフローを誤って起動することを防げる。
サブエージェントの定義
# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Reviews code for security vulnerabilities. PROACTIVELY invoked when editing auth or payment code.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: acceptEdits
maxTurns: 20
---
あなたはシニアセキュリティエンジニア。以下を重点的にレビューする：
- インジェクション脆弱性（SQL、XSS、コマンドインジェクション）
- 認証・認可の欠陥
- コード内のシークレット・クレデンシャル
- 安全でないデータ処理
具体的な行番号と修正案を提示する。
description: "PROACTIVELY..." とすることで、Claudeが関連タスクを検出すると自動的に起動する。model: opus を使えば重要なタスクに高性能モデルを割り当てられる。
isolation: "worktree" — 一時的なgitワークツリーで独立実行background: true — 常にバックグラウンドタスクとして実行memory: "project" — プロジェクトスコープの永続メモリeffort: "max" — 最高の推論品質（コスト増加に注意）
フック・MCPで自動化を次のレベルへ
フックシステム：決定論的に動作を保証する
CLAUDE.mdのルールは「アドバイス」だが、フックは「保証」だ。フックはClaudeのワークフローの特定ポイントでスクリプトを自動実行する。
リポジトリの .claude/hooks/scripts/hooks.py は以下のイベントを処理する：
// .claude/settings.json のフック設定例
{
"hooks": {
"PreToolUse": [{
"matcher": "Bash",
"hooks": [{ "type": "command", "command": "python3 .claude/hooks/scripts/hooks.py pre_tool_use" }]
}],
"PostToolUse": [{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "npx eslint $CLAUDE_TOOL_OUTPUT_FILE --fix" }]
}],
"PermissionRequest": [{
"hooks": [{ "type": "command", "command": "python3 .claude/hooks/scripts/hooks.py permission_request" }]
}],
"Stop": [{
"hooks": [{ "type": "command", "command": "python3 .claude/hooks/scripts/hooks.py on_stop" }]
}]
}
}
使用可能なフックイベント：
| イベント | タイミング | 活用例 |
|---|---|---|
PreToolUse |
ツール実行前 | Bashコマンドのログ取得、危険コマンドのブロック |
PostToolUse |
ツール実行後 | ファイル編集後にESLint自動実行 |
PermissionRequest |
権限確認時 | WhatsApp/Slackに転送して外出先から承認 |
Stop |
Claudeが停止時 | 継続をプッシュ（Claudeが止まらないようにする） |
SessionStart |
セッション開始時 | コンテキストの動的ロード |
UserPromptSubmit |
プロンプト送信時 | ログ取得、コンテキスト注入 |
PermissionRequestフックでパーミッションをWhatsApp等に転送する際は、そのメッセージがプロンプトインジェクション攻撃のベクターになり得ることを理解した上で使用すること。外部からの「全アクションを承認して」といった指示は拒否する。
MCPサーバーとの連携
# MCPサーバーの追加
claude mcp add slack # Slack MCP
claude mcp add github # GitHub MCP
claude mcp add notion # Notion MCP
# よく使われる組み合わせ
claude mcp add bigquery # BigQueryでSQL不要の分析
claude mcp add figma # デザインから実装
Borisのチームの活用例：
- Slack MCP — バグスレッドをそのまま貼り付けて「fix」と言うだけ
- GitHub MCP — Issue/PR管理、コメント、レビューを自然言語で操作
- BigQuery MCP — 「先週のエラー率が上がった原因を調べて」とだけ指示
Boris Cherny直伝：Tips 25選（2026年版完全整理）
Boris CherneyはClaude Codeの作者であり、2026年に入って複数のTipsスレッドをXで公開している。以下にすべてのTipsを整理した。
📋 CLAUDE.md・コンテキスト管理（5Tips）
1. CLAUDE.mdを訂正のたびに更新する 訂正の後に「Update your CLAUDE.md so you don’t make that mistake again」と伝える。繰り返すことで間違い率が目に見えて下がる。
2. /clearを積極的に使う
無関係なタスク間は必ず /clear する。長いセッションに無関係な情報が蓄積すると品質が下がる。
3. /compact で部分的に圧縮する
/compact Focus on the API changes のように指示付きでコンパクション。重要なコンテキストだけを残せる。
4. セッションに名前をつける
/rename oauth-migration でセッションを命名。claude --resume で過去のセッション一覧から選択できる。
5. 複雑なタスクの前に詳細仕様を書く
「Let Claude interview you first」— AskUserQuestion ツールでインタビュー後に仕様をSPEC.mdに書き出させ、新しいセッションで実装する。
⚡ 並列実行・パフォーマンス（5Tips）
6. 3〜5個のワークツリーを同時実行（最重要） シェルエイリアスで一発切り替え。分析専用ワークツリーをBigQueryログ用に常時確保するのも有効。
7. /batch で数百エージェントを展開
大規模マイグレーションに /batch を使う。インタビュー後に自動で並列展開。
8. –bare で起動を10倍速にする（隠し機能）
claude -p "..." --bare でCI/CD用の高速起動。現在はオプトインだが将来はデフォルト予定。
9. /loop でスケジュール自動化
/loop 5m /babysit でコードレビュー対応・自動リベースを5分ごとに実行。
/loop 30m /slack-feedback でSlackフィードバックPRを自動作成。
10. –add-dir で複数リポジトリを横断する
claude --add-dir ../other-repo または /add-dir コマンドで別リポジトリへのアクセスと権限を付与。
🛠️ プロンプト・デバッグ（5Tips）
11. Claudeにレビュアーになってもらう 「PRを作る前に、この変更について徹底的に批判してください」で手戻りを事前に防ぐ。
12. 「エレガントな解法を実装し直して」 微妙な修正の後に「今わかっていることすべてを踏まえ、これを捨てて洗練された解法を実装して」と言う。
13. 「これが機能することを証明して」 main と feature ブランチの動作差分をdiffさせてClaudeに証明させる。
14. Plan Modeで「こじれたら戻る」 何かがおかしくなったら計画モードに切り替えて再計画する。押し続けない。
15. 失敗パターンを認識する
2回同じ訂正をしたら /clear して、学んだことを盛り込んだより具体的なプロンプトで再スタート。
📱 UI・環境（5Tips）
16. モバイルアプリを使う（隠し機能） iOSアプリの「Code」タブからPRレビュー・変更承認・コード作成が可能。
17. /teleport でデバイス間を移動（隠し機能）
claude --teleport でクラウドセッションをローカルターミナルに引き込む。/remote-control で逆方向も可能。
18. /btw でサイドクエリ（隠し機能） エージェントが動いている間にサイドクエリを送れる。回答はオーバーレイに表示され、会話履歴に入らない。コンテキスト節約に効果的。
19. /voice で音声入力（隠し機能） Borisは主にVoiceでコーディングしている。タイピングより3倍速く、プロンプトが詳細になる。
20. /branch でセッションをフォーク（隠し機能）
/branch または claude --resume <id> --fork-session で現在のセッションを分岐させて実験できる。
🤖 エージェント・自動化（5Tips）
21. 「use subagents」を付けるだけ リクエストに「use subagents」を追加するだけで並列サブエージェントが起動し、メインコンテキストをクリーンに保つ。
22. CIテストを自律修正させる 「Go fix the failing CI tests」とだけ言う。どう修正するかを指示しない。
23. docker logsをClaudeに解析させる 分散システムのトラブルシューティングでdockerログを直接渡すと驚くほど的確に診断する。
24. BigQuery/DBをCLI経由で分析する BigQuery skillをコードベースにコミットして全員が使える状態にする。Borisは半年以上SQLを1行も書いていない。
25. Chromeエクステンションでフロントエンド検証（最重要 for フロント） Claudeにブラウザを与えることがフロントエンドの最重要ポイント。コードを書いて→ブラウザで確認して→改善を繰り返す。Claude in Chromeエクステンション推奨。
公式ドキュメント・他のTips集との比較
このリポジトリと他のリソースを比較すると、それぞれの特性が見えてくる：
| リソース | 対象 | 更新頻度 | 深さ | 実装例 |
|---|---|---|---|---|
| shanraisshan/claude-code-best-practice | 実践的な上級者向け | 高（頻繁にPR） | 非常に深い | 豊富（.claudeディレクトリ含む） |
| 公式ドキュメント（code.claude.com） | 全レベル | 中（機能追加時） | 中 | コンセプト例多め |
| awattar/claude-code-best-practices | 基本〜中級 | 低 | 浅め | 少ない |
| Anthropic公式ブログ | 一般読者 | 低 | 概要のみ | なし |
初めてClaude Codeを使うなら公式ドキュメントから。日常的に使い倒したいならshanraisshan/claude-code-best-practiceを手元に置いておく。新機能・隠し機能の最速キャッチアップにはBoris Chernyのフォローが効果的。
実践セットアップ：リポジトリの活用方法
# リポジトリをクローンして手元で参照
git clone https://github.com/shanraisshan/claude-code-best-practice
cd claude-code-best-practice
# 構造を把握する（READMEから始める）
cat README.md | head -100
# .claudeディレクトリの内容（実装例として参照）
ls .claude/
# agents/ commands/ hooks/ rules/ settings.json skills/
# スキル・エージェントをコピーして自分のプロジェクトに適用
cp -r .claude/skills/weather-fetcher ~/my-project/.claude/skills/my-skill
CLAUDE.mdもそのまま参考になる。特に以下のセクションは自分のプロジェクトに移植価値が高い：
- Critical Patterns — サブエージェントからサブエージェントを呼ぶ方法（Agentツール経由）
- Workflow Best Practices —
/compactのタイミング、コンテキスト管理 - Debugging Tips —
/doctor、バックグラウンドタスク、ブラウザMCP
エージェントエンジニアリングへの体系的なロードマップはAgentic AIエンジニアロードマップ2026も参照してほしい。
Claude Codeベストプラクティス：まとめ
最も重要な3つを覚えておくとしたら：
- CLAUDE.mdに投資する — 訂正のたびに更新し、200行以下に保ち、定期的にプルーニングする
- 並列ワークツリーを使う — 3〜5セッションを同時実行することで生産性が最大になる
- コンテキストを管理する —
/clear・/compact・サブエージェントでメインコンテキストをクリーンに保つ
shanraisshan/claude-code-best-practiceは単なるTips集ではなく、.claude/ディレクトリに実際に動くスキル・エージェント・フックの実装例が含まれた生きたリファレンス実装だ。GitHubスターを付けて手元に置き、自分のプロジェクトのCLAUDE.md改善のたびに参照する習慣をつけると効果が大きい。
Claude Code Auto Modeの設定方法と組み合わせることで、よりスムーズな自律実行環境を構築できる。
