Claude Code ベストプラクティス集リポジトリの紹介と実践ガイド

Claude Code を使った開発が増えてきて、設定やワークフローの知見も徐々に溜まってきた。そんな中、GitHub で claude-code-best-practice というリポジトリを見つけた。2025年10月に作成されてからスター数が1,500を超えており、中身を読んでみたらかなり実用的だったのでまとめておく。

リポジトリの概要

アプリケーションのコードベースではなく、Claude Code の設定パターン集・テンプレート集。以下のようなトピックが網羅されている。

CLAUDE.md の書き方と運用ノウハウ
Command / Agent / Skills の3層アーキテクチャ
Hooks による通知システム
settings.json の全オプションリファレンス
モノレポでの CLAUDE.md / Skills の読み込み挙動
RPI（Research → Plan → Implement）ワークフロー

著者の経験則から学べること

README の「MY EXPERIENCE」セクションに、実際に使い込んで得られた知見がまとめられている。開発で使う人にとっては一番参考になる部分だと思う。

CLAUDE.md は150行以下に抑える

長すぎると Claude が守ってくれない指示が増える。著者は「still not 100% guaranteed」と注記しているが、短いほうが遵守率が上がるのは間違いない。

一方で /memory、/rules、constitution.md については「does not guarantee anything」とバッサリ。CLAUDE.md に直接書くのが最も確実という立場。

コンテキスト管理を意識する

コンテキスト使用量の 50% に達したら手動で /compact を実行する
サブタスクは コンテキストの50%以内で完了できるサイズ に分割する
ステータスラインでコンテキスト使用量を常に監視する

コンテキストが溢れると Claude の品質がガクッと落ちるので、能動的に管理するという発想。これは大きめの実装タスクで特に効く。

小さいタスクにワークフローは不要

vanilla cc is better than any workflows with smaller tasks

これは結構大事な話で、ワークフローを構築すること自体が目的化しがち。単純なバグ修正や1ファイルの変更なら、素の Claude Code にそのまま頼むほうが速い。

その他の実践的なTips

常にプランモードから始める — いきなりコードを書かせない
タスク完了のたびにコミット — 大きな変更を一度にコミットしない
defaultMode: "bypassPermissions" を settings.json に設定する — dangerously--skip-permissions フラグより安全に権限チェックをスキップできる
Wispr Flow（音声プロンプト）で10倍の生産性向上を謳っている

Command → Agent → Skills の3層アーキテクチャ

このリポジトリの中核となるアーキテクチャパターン。天気情報の取得を題材にした実装例が含まれている。

各層の役割

層	配置場所	役割
Command	`.claude/commands/*.md`	エントリーポイント。ユーザーが `/command-name` で起動する
Agent	`.claude/agents/*.md`	ワークフローの実行主体。Skills をプリロードして使う
Skills	`.claude/skills/*/SKILL.md`	ドメイン知識・手順書。Agent のコンテキストに注入される

実装例: 天気ワークフロー

ユーザーが /weather-orchestrator コマンドを実行
コマンドが weather エージェントを起動
エージェントは起動時に weather-fetcher と weather-transformer のスキルがプリロードされている
エージェントがスキルの手順に従って順番に処理を実行

# .claude/agents/weather.md のフロントマター
---
name: weather
description: Use this agent PROACTIVELY when you need to fetch and transform weather data
tools: WebFetch, Read, Write
model: haiku
color: green
skills:
  - weather-fetcher
  - weather-transformer
---

ポイントは Progressive Disclosure（段階的開示）の考え方。スキルの内容はエージェント起動時にプリロードされるが、エージェント自体はコマンドから呼ばれるまで起動しない。必要な情報が必要なタイミングでだけコンテキストに入る設計。

汎用エージェントではなく機能特化エージェントを作る

著者は「general qa, backend engineer のような汎用エージェントではなく、feature specific subagents を作れ」と言っている。汎用エージェントはコンテキストが肥大化しやすく、専門的な指示が薄まるため。

Hooks による音声通知

Claude Code の各イベント（ツール使用前後、セッション開始・終了、コンパクト前など）でシェルスクリプトを実行する仕組み。このリポジトリでは ElevenLabs TTS で生成した音声ファイルを使った通知システムを構築している。

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

git commit 時には専用の音声が鳴るなど、イベントごとに異なるフィードバックを返す設計。設定は hooks-config.json（チーム共有）と hooks-config.local.json（個人用、gitignore）の2層構造。

長いタスクを実行中にブラウザで別のことをしていても、音で完了を知れるのは地味に便利。

settings.json リファレンス

reports/claude-settings.md に settings.json の全オプションが網羅されている。ドキュメントとして非常に充実しており、公式ドキュメントを補完する資料として使える。

特に有用なのはパーミッション構文のリファレンス。

{
  "permissions": {
    "allow": [
      "Edit(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)"
    ]
  }
}

Bash(npm run *) のようにワイルドカードでコマンドパターンを指定できる。.env や secrets/ 配下の読み取りを deny に入れておけば、うっかり機密情報を読まれることを防げる。

モノレポでの CLAUDE.md と Skills の挙動

大規模プロジェクトで使う人向けの調査レポートも含まれている。

CLAUDE.md の読み込み

上方向（Ancestor Loading）: 起動ディレクトリから上に向かって、見つかったすべての CLAUDE.md を起動時に読み込む
下方向（Descendant Loading）: サブディレクトリの CLAUDE.md は、そのディレクトリのファイルにアクセスしたときに遅延読み込みされる

つまり、ルートの CLAUDE.md は常に読まれるが、packages/frontend/CLAUDE.md は frontend のファイルを触るまで読まれない。

Skills の読み込み

CLAUDE.md とは異なり、Skills は上方向の探索をしない。

プロジェクトルートの .claude/skills/ は常に読まれる
サブディレクトリの .claude/skills/ は、そのディレクトリのファイルにアクセスすると自動検出される
スキルの説明文（description）は常にコンテキストに入るが、本文は呼び出されたときに初めて読み込まれる

RPI ワークフロー

大きな機能開発向けの体系的なワークフロー。Research → Plan → Implement の3フェーズで進める。

Research フェーズ

/rpi:research コマンドで実行。requirement-parser、product-manager、senior-software-engineer などのエージェントが実現可能性を分析し、GO/NO-GO の判定を出す。

Plan フェーズ

/rpi:plan コマンドで実行。PM要件（pm.md）、UXデザイン（ux.md）、技術設計（eng.md）、実装ロードマップ（PLAN.md）を自動生成する。

Implement フェーズ

/rpi:implement コマンドで実行。PLAN.md に基づいてフェーズごとに実装し、code-reviewer エージェントがレビューする。

正直、個人開発やブログ運営には重すぎるワークフローだが、チーム開発や大きなプロダクト機能の開発には参考になる。特に「Research で NO-GO が出たらそこで止める」という設計は、無駄な実装を防ぐ仕組みとして優秀。

実際に取り入れるなら

全部を導入する必要はなく、プロジェクトの規模に合わせて取捨選択するのが良い。

個人開発・小規模プロジェクト:

CLAUDE.md を150行以内に抑える意識
コンテキスト50%での手動 compact
settings.json のパーミッション設定
小さいタスクはワークフローなしで直接実行

中〜大規模プロジェクト:

Command → Agent → Skills の3層構造
機能特化エージェントの設計
Hooks による通知
モノレポでの CLAUDE.md / Skills の配置設計

チーム開発:

RPI ワークフロー
settings.json と hooks-config.json のチーム共有
settings.local.json と hooks-config.local.json による個人設定の分離

リポジトリ自体がリファレンス実装として使えるように設計されているので、必要な部分だけ自分のプロジェクトにコピーして使うのが実用的だと思う。