Claude Code ベストプラクティス(英語圏では best practices)を、Boris Cherny氏のCLAUDE.md運用・並列ワークツリー・--bareまで、リポジトリ shanraisshan/claude-code-best-practice を軸に整理します。Claude Code全般は Claude Code|2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き をご覧ください。

REPO GROWTHリポジトリの伸び

4か月でスターが約1.8倍、Tips集から広がった

2026年4月(記事初出時)スター

36012

2026-08-01 実測スター

63824
出典: 本文の実測表(shanraisshan/claude-code-best-practice)
30秒でわかる
・CLAUDE.mdは「消してもミスしないなら消す」で200行以下に保つ
・3〜5個のgitワークツリーを並列に走らせる
・CI向けは claude -p --bare で起動を速くする
・公式ドキュメントが概念中心なのに対し、実際に動く .claude/ の実装例を手元に置ける

Claude Code ベストプラクティスとは?shanraisshan/claude-code-best-practice の全貌

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 vs Cursor徹底比較2026年版が導入に向く。


Boris Cherny流 CLAUDE.md の書き方(claude.md ベストプラクティス)

最初の一手:/init コマンドを実行する
プロジェクトルートで /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.MD RULES書く・書かない

CLAUDE.md は「消すとミスが出るか」で残す

  1. 1.Claudeが推測できないものを書く

    ビルド・テストのコマンド、ブランチ命名、環境変数

  2. 2.コードから読めることは書かない

    標準的な言語慣習、ファイルごとの説明

  3. 3.200行を超えたら @import で分ける

    子ディレクトリのCLAUDE.mdは該当ファイルを扱うときだけ読まれる

出典: 本文(公式ガイドの推奨)

「このルールを削除しても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を置くことで、そのディレクトリのファイルを扱う時だけ読み込まれる。

Boris流 CLAUDE.md 更新ルール
訂正を加えるたびに、最後に「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パターン

複数セッションで品質を上げるパターンが公式ドキュメントで紹介されている:

SessionB(Reviewer)SessionA(Writer)SessionB(Reviewer)SessionA(Writer)SessionBは実装に関わっていないためバイアスのないレビューが可能APIレート制限の実装@src/middleware/rateLimiter.tsを渡すエッジケース・競合状-態・既存パターンとの-整合性をレビューレビュー結果をフィードバック問題点を修正

レビュアーセッションが「書いた当人ではない」ことが重要だ。同じコンテキストで書いた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

スキル・サブエージェント・フック・MCP:Claude Codeを拡張する

リポジトリが最も詳しく解説しているのが、この3つのプリミティブだ。Claude Codeの内部アーキテクチャでも解説したように、Claude Codeは拡張可能な設計になっている。

Command → Agent → Skill アーキテクチャ

ユーザー
/weather-orchestrator

Command
.claude/commands/weather-orchestrator.md
エントリポイント:C/F確認・エージェント・スキル呼び出し

Agent
.claude/agents/weather-agent.md
気温取得(weather-fetcherスキル事前ロード済み)

Skill(Agent専用)
.claude/skills/weather-fetcher/SKILL.md
Open-Meteo API呼び出し手順

Skill(直接呼び出し)
.claude/skills/weather-svg-creator/SKILL.md
SVG天気カード作成・ファイル書き込み

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 を使えば重要なタスクに高性能モデルを割り当てられる。

よく使うサブエージェント frontmatter フィールド
isolation: "worktree" — 一時的なgitワークツリーで独立実行
background: true — 常にバックグラウンドタスクとして実行
memory: "project" — プロジェクトスコープの永続メモリ
effort: "max" — 最高の推論品質(コスト増加に注意。API料金シミュレーターで事前にコストを確認しよう)

フック・MCPで自動化を次のレベルへ

フックシステム:決定論的に動作を保証する

CLAUDE.mdのルールは「アドバイス」だが、フックは「保証」だ。フックはClaudeのワークフローの特定ポイントでスクリプトを自動実行する。

ADVICE VS GUARANTEE助言と保証

CLAUDE.md は助言、フックは保証

CLAUDE.md

ルールとして読ませる

  • 守られるかはClaude次第
  • コマンドや慣習の共有に向く

フック

決まったタイミングでスクリプト実行

  • PreToolUse で危険コマンドを止められる
  • PostToolUse で編集後にESLintを回せる
出典: 本文のフック解説

リポジトリの .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直伝 Claude Code Tips 25選と –bare

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 で起動を高速化する(隠し機能) 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

【2026-08-01 実測】リポジトリはTips集からワークフロー集へ広がった

本記事は .claude/ ディレクトリの実装例とBoris直伝の25 Tipsを軸にしている。2026年8月1日にリポジトリを測り直すと、規模も構成も当時から変わっていた。

項目 記事初出時(2026年4月) 2026-08-01 実測
スター 36,012 63,824
総ファイル数 — 603
最終push — 2026-07-31
ライセンス MIT MIT(変更なし)

注目したいのはStar数よりトップレベルのディレクトリ構成だ。Tree APIで列挙すると、記事が扱った .claude/ 以外に次のような区画が並んでいる。

ディレクトリ 内容
.claude 本記事が解説しているスキル・エージェント・フックの実装例
.codex Codex CLI向けの設定。Claude Code専用リポジトリではなくなっている
agent-teams エージェントチーム編成のプロンプトと出力例(.claude を内包)
orchestration-workflow オーケストレーションの解説(Markdown+GIF+SVGの図解つき)
development-workflows 開発ワークフロー集
changelog 追加履歴。agent-collections / best-practice / cross-model-workflows / development-workflows / skill-collections の5区分
tips / tutorial / implementation / presentation / videos / reports Tips本体、チュートリアル、実装例、資料、動画、レポート

changelog/cross-model-workflows と .codex の存在が、このリポジトリの性格の変化を端的に示している。「Claude CodeのTips集」から、複数のコーディングエージェントをまたぐワークフロー集へ広がった、と読むのが実態に近い。

いま読むならどこから
本記事の25 Tipsを読み終えたあとの次の一歩として、changelog/ の5区分を見るのが効率的だ。どのカテゴリに何が追加されてきたかが分かるため、記事が書かれた時点以降の差分だけを追える。orchestration-workflow/ はMarkdownに加えてGIFとSVGの図解が同梱されており、複数エージェントの流れを目で追いたい場合はここが早い。

Claude Codeベストプラクティス:まとめ

最も重要な3つを覚えておくとしたら:

  1. CLAUDE.mdに投資する — 訂正のたびに更新し、200行以下に保ち、定期的にプルーニングする
  2. 並列ワークツリーを使う — 3〜5セッションを同時実行することで生産性が最大になる
  3. コンテキストを管理する — /clear・/compact・サブエージェントでメインコンテキストをクリーンに保つ

shanraisshan/claude-code-best-practiceは単なるTips集ではなく、.claude/ディレクトリに実際に動くスキル・エージェント・フックの実装例が含まれた生きたリファレンス実装だ。GitHubスターを付けて手元に置き、自分のプロジェクトのCLAUDE.md改善のたびに参照する習慣をつけると効果が大きい。

Claude Code Auto Modeの設定方法と組み合わせることで、よりスムーズな自律実行環境を構築できる。

関連記事: Claude Code完全ガイド2026:インストールから本番運用まで

参照ソース