メインコンテンツまでスキップ

Claude Code ベストプラクティス集 shanraisshan/claude-code-best-practice の歩き方

· 約59分
rasshii
Software Engineer

Claude Code を業務に取り入れ始めると、公式ドキュメントを読んでも「次に何を導入すべきか」「自分のレベルに合うのはどれか」が見えにくくなる段階があります。Anthropic 自身が出している機能だけでも 30 種類を超え、コミュニティが公開しているワークフローも 12 件以上、Boris Cherny や Thariq といった Claude Code 開発陣の Tips も 80 件以上が散らばっている状態です。

その整理に役立つのが、2026 年 3 月の GitHub Trending #1 を獲得した shanraisshan/claude-code-best-practice です。Shayan Raisshan 氏 (Claude Pakistan community 主宰、Claude Community Ambassador) が MIT ライセンスで公開・継続更新しているリポジトリです。執筆時点 (2026 年 5 月 25 日) で 445 ファイル、585 行の README を持つキュレーション集です。

本記事はこのリポジトリを 自分のレベルと用途に合った要素だけ拾い出せる ように整理した見取り図です。長めの 1 本ですが通読は前提にしておらず、目次から拾い読みできる構成にしてあります。気になった箇所はそのまま GitHub 上のファイルへ飛べるよう、本文中の重要リンクはリポジトリ内の具体ファイルへの直リンクで張っています。

加えて、各章末には :::info 筆者の実装例 ブロックを設けて、筆者自身の ~/.claude/ (agents 7 件 / skills 38 件 / rules 31 件 / hooks 3 script / teams 1 件 / ADR 16 件) でどう実践しているかを併載しました。「他人の整理 (キュレーション)」と「自分の harness (実装)」の橋渡しとして使えるようにしてあります。実装例が不要な方は :::info ブロックを読み飛ばし、:::note 採用判断 ブロックだけを拾って章をまたいでも、本筋は崩れない構成にしています。

本記事の読み方

このリポジトリは作者自身が「コードリポではなくリファレンス・コース」と位置づけています (README の How to Use セクション)。本記事もそれに倣い、まず全体像を提示してから、章末ごとに 採用判断 ミニまとめを置いて「自分は何を試すか」を整理する形で進めます。最後の第 9 章にレベル別ロードマップをまとめてあるので、急ぐ方はそちらから読んでも構いません。

第 1 章: リポジトリの正体13 ディレクトリの役割​

最初に全体像を把握します。リポジトリ直下には 13 の主要ディレクトリと 2 つの基幹ファイルがあります。

shanraisshan/claude-code-best-practice/
├── README.md                    ハブ。585 行に全分類表が集約
├── CLAUDE.md                    このリポ自身の Claude Code 設定 (自己言及)
├── best-practice/    (8 件)     概念ごとの仕様カタログ
├── implementation/   (6 件)     実際に動く実装例
├── orchestration-workflow/      ショーケース (Command → Agent → Skill)
├── agent-teams/                 Agent Teams 実装例
├── development-workflows/       cross-model + RPI ワークフロー
├── reports/         (12 件)     深掘り解析レポート
├── tips/            (10 件)     Boris / Thariq 等の発言集
├── videos/           (8 件)     ポッドキャスト / 動画解説
├── tutorial/                    day0 / day1 セットアップ手順
├── changelog/                   更新追跡
├── presentation/                GDG Kolachi 等の登壇資料
└── .claude/                     このリポ自身が使う agents/commands/skills/hooks

このリポジトリの特徴は 4 つの情報軸が役割分担している 点にあります。

軸配置用途読者にとっての価値
Conceptsbest-practice/各機能の仕様カタログ「この機能は何か」を 5 分で把握
Workflowsdevelopment-workflows/, orchestration-workflow/, ECC/Superpowers 等の外部リポへのリンク機能を組み合わせた方法論他人がどう組み合わせているかを学ぶ
Tipstips/ + README の 83 件開発者発言の集約自分が次に試すべきことを発見
Reportsreports/ (12 件)比較分析・深掘り論考「なぜそうするか」の理屈を理解

どこから読み始めるかは、自分の Claude Code 経験レベルで決まります。インストールが終わったばかりなら tutorial/ から始めて Tips の入門カテゴリへ。基本機能は動かしたことがあるなら best-practice/ の 8 ファイルを順に読みつつ Workflows を 1 つ試す。すでに自前で .claude/ を育てている人は Reports と Workflows の比較で次の改善ヒントを探す、という具合です。

採用判断

ディレクトリ図を「目次」としてブックマーク。1 セッションで全部読もうとせず、章別に拾い読みする方が頭に残ります。第 9 章のロードマップを先に眺めてから戻るのも1つの読み方。

第 2 章: 30+ の Claude Code 概念カタログ​

リポジトリの中心になるのが、README 冒頭の 🧠 CONCEPTS 表と 🔥 Hot 表です。Anthropic が Claude Code に追加した機能を網羅し、各機能について「公式ドキュメント」「リポ内の best-practice 解説」「実装例」「コミュニティの実装例」へのリンクを付けています。

ここでは機能を 役割で再グルーピング して紹介します。各機能に 採用 difficulty ラベル を付けてあります: ★ は設定 1 ファイル / 学習 30 分以内で導入可能、★★ は数ファイル + 1-2 時間の学習が必要、★★★ は複数機能の組み合わせ / 半日以上の理解が必要です。

2.1 中核プリミティブ (4)​

Claude Code を「ただのチャットボット以上」にする 4 つの基本機能です。

Subagents ★★：best-practice/claude-subagents.md には 16 個の frontmatter (= ファイル冒頭に書く YAML メタデータ) フィールドが表形式で解説されています。フィールドは name / description / tools / model / permissionMode / skills / mcpServers / hooks / memory / effort / isolation / initialPrompt / color などです。Anthropic 公式ビルトインも 5 種類用意されていて、general-purpose (汎用), Explore (haiku でコードベース探索), Plan (read-only な実装計画), statusline-setup, claude-code-guide という構成です。実装例は implementation/claude-subagents-implementation.md にまとまっています。

設計の中核にあるのは Generator-Evaluator 分離 という原則です。これは「作る側 (Generator)」と「評価する側 (Evaluator)」を別 subagent に分けて、self-evaluation bias (= 自分が作ったものを自分で評価すると品質を過大評価しやすい認知バイアス) を回避する考え方です。Boris Cherny も繰り返し言及しています。

Commands ★：slash コマンドの作り方は best-practice/claude-commands.md に解説があります。.claude/commands/<name>.md に Markdown を置くだけで /<name> として呼び出せるようになる、もっとも導入コストが低い拡張ポイントです。Boris Cherny の Tip でも「1 日 1 回以上やる作業は command か skill にする」と繰り返し強調されています。

Skills ★★：best-practice/claude-skills.md では 15 個の frontmatter フィールドに加え、9 個の公式 bundled skill が表になっています。まず simplify (重複削除リファクタ), batch (一括コマンド), debug (失敗調査), loop (定期実行), claude-api (Anthropic SDK 補助) の 5 つです。残る 4 つは fewer-permission-prompts (allowlist 自動生成), run (実アプリ起動), verify (動作検証), run-skill-generator (起動レシピ作成) です。v2.1.145 で /run, /verify, /run-skill-generator の 3 つが追加された点が特に新しいです。

Skill 設計の重要概念に Progressive disclosure (段階的開示) があります。1 つの SKILL.md ファイルに全情報を詰め込むのではなく、フォルダ内に references/ scripts/ examples/ を配置し、必要になった時だけ Claude が読み込む構造にします。こうすることで context window (一度に処理できるトークン枠) を圧迫しないという設計指針です。

Hooks ★★★：PreToolUse / PostToolUse / Stop / SessionStart などライフサイクルイベントで shell コマンドを実行できる機構。リポ内では別リポ shanraisshan/claude-code-hooks として独立しており、サウンド通知 / 自動フォーマット / 危険コマンドのブロック等の実装例が揃っています。Boris の発言「PostToolUse hook で auto-format を入れると Claude が生成するコードの最後 10% を仕上げてくれて CI failure を防げる」が代表的な活用例です。

Hook の役割を整理する枠組みとして Computational Sensor / Inferential Guide の二分法 があります。Computational Sensor は「コードで自動検出する deterministic (決定的) な仕組み」です (lint / CI / hook の suppression 検出など)。Inferential Guide は「LLM 自身に判断させる確率的な仕組み」です (CLAUDE.md / rules / skills の指示文)。Hook は前者を担当し、rules や CLAUDE.md だけでは LLM が確率的に違反してしまう規範を deterministic に強制する役割を持ちます。

ここまでで Subagent / Command / Skill / Hook の 4 つを見てきましたが、初学者が最も混乱しやすい Subagent vs Skill vs Command の境界 を 1 つの表に集約しておきます (Hook はライフサイクル機構のため別軸として整理)。

機能役割起動方法
Commandエントリポイント / ワークフロー指揮/<name> をユーザーが打鍵
Agent (Subagent)ドメイン作業の主役 (別 context window で動く)Command または上位 agent から呼出
Skill成果物生成 / 参照知識の単位trigger 発話で自動起動、または Skill tool から呼出
筆者の実装例 (~/.claude/)

筆者は ~/.claude/agents/ に 7 件の subagent を配置し、Generator-Evaluator 分離 を意図的に組んでいます。内訳は architect / code-reviewer / debugger / implementer / refactorer / test-strategist / infra-reviewer の 7 つです。

  • Generator (作る側): implementer (実装専任) / refactorer (リファクタ専任) / debugger (バグ調査 + 修正)
  • Evaluator (評価する側): architect (設計レビュー) / code-reviewer (コードレビュー) / test-strategist (テスト戦略) / infra-reviewer (TF/IaC レビュー)

Evaluator 側の 4 件は disallowedTools: Write, Edit で read-only を強制 しており、評価担当が誤って実装に手を出すことを構造的に防いでいます。命名も general qa のような汎用名ではなく、Boris 推奨の feature 特化 (具体的な役割名) に統一しています。

具体的には、subagent 定義ファイルの frontmatter は以下のような YAML 形式で書きます (筆者の code-reviewer.md 抜粋)。

---
name: code-reviewer
description: ペアプログラミング用コードレビュアー。コード変更後のレビューとガイダンスを提供
model: opus
effort: max
tools: Read, Grep, Glob, Bash, WebSearch, mcp__context7__query-docs
disallowedTools: Write, Edit
isolation: worktree
---

# Instruction 本文...

tools で許可ツール、disallowedTools で禁止ツールを明示することで、評価専任エージェントが誤って実装に手を出すリスクを deterministic に排除できます。

Commands は 0 件で運用 しており、用途は全て skill に統合しています。理由は、skill は frontmatter に書いた trigger 発話 (例: 「レビュー」「バグ」) で自動起動できるため、/command-name を毎回打つ手間が省けるからです。Boris の「1 日 1 回以上やる作業は command か skill にせよ」は、筆者環境では「全部 skill にせよ」に翻訳されています。

Skills は 38 フォルダ (propose / debug / review / explain / compare / learn / next / checkpoint / spec-driven-development / verify ほか) を運用。代表的な trigger 発話の対応は以下のとおりです。

Skilltrigger 発話役割
/propose"提案して", "設計案"敵対的自己批判付きで実装方針を提案 (最大 2 反復)
/debug"バグ", "動かない"Investigate → Fix → Verify を最大 3 反復で自律解決
/review"レビュー", "チェック"7 観点 (正確性 / 可読性 / パフォーマンス / セキュリティ / 保守性 / 規約 / デグレ) でコードレビュー
/explain"説明して", "なぜ"コード・概念を段階的に説明
/checkpoint"checkpoint", "区切って"現セッション整理 + 次セッション用 prompt 生成

Progressive disclosure 構造 (references/ scripts/ examples/ を持つフォルダ型) は 2 件のみ (skill-creator / react-view-transitions)。他の 36 件は SKILL.md 単体 + metadata で済ませており、必要に応じて段階導入する方針です。

Hooks は実体スクリプト 3 件 を運用しています。

  • ~/.claude/hooks/check-protected-files.sh (PreToolUse)：Write/Edit 実行前に .env 等の保護ファイルへの書き込みを block
  • ~/.claude/hooks/check-suppression.sh (PostToolUse)：Write/Edit の出力に suppression が新規追加されていないか deterministic に検証。対象は // eslint-disable-next-line や // @ts-ignore 等
  • ~/.claude/hooks/check-plain-question.sh (Stop)：応答終了時にテキスト出力を grep し、「〜ましょうか」「〜ですか」等の平文質問パターンを検出。exit 2 で Claude に自己修正を促す (AskUserQuestion ツール使用を強制する Sensor)

Boris の「PostToolUse hook で auto-format」を、筆者は 「format」ではなく「suppression 検出」 に転用しているのが意図的な差分です。format は CI で十分カバーできますが、suppression は LLM が確率的に挿入する anti-pattern で、CI 通過後に永続化されると harness が空洞化するため、PostToolUse hook で実行直後に即時 block します。

2.2 統合機構 (5)​

外部世界やプロジェクト設定とつなぐためのレイヤです。

機能難易度リポ内リファレンス
MCP Servers★★best-practice/claude-mcp.md：context7 / aws-knowledge / playwright 等を Claude Code から呼べるプロトコル
Plugins★★公式 docs：配布可能パッケージ。marketplace を立てる方法もリンクあり
Settings★best-practice/claude-settings.md：.claude/settings.json の全フィールド網羅、permission / model / output style 等
Status Line★shanraisshan/claude-code-status-line：context 使用量 / cost の可視化
Memory★★best-practice/claude-memory.md + 深掘り reports/claude-agent-memory.md：CLAUDE.md / .claude/rules / auto-memory の階層

ここで MCP (Model Context Protocol) について少し補足しておきます。これは Anthropic が策定した「外部のツールやデータソースを Claude に呼び出させるための標準プロトコル」です。対応する MCP server を導入すれば、Claude が外部機能を tool として呼べるようになります。例えばライブラリドキュメント取得 (context7) / AWS 公式 docs 取得 (aws-knowledge) / ブラウザ自動化 (playwright / chrome-devtools) / コードベース symbol 検索 (serena) などです。WebSearch だけでは取りこぼす一次情報を確実に取得できるため、技術的判断の精度が上がります。

2.3 セッション制御 (3)​

長時間セッションや複雑タスクで Claude Code が「賢く動き続ける」ための機構です。

  • Checkpointing ★：ファイル編集を自動追跡し、/rewind で過去状態に戻れる。失敗した試行で context を汚すより rewind した方が良い、という Thariq の Tip と組み合わせると価値が出ます。
  • CLI Startup Flags ★：best-practice/claude-cli-startup-flags.md に主要フラグの一覧。--permission-mode, --agent, --bg, --worktree 等。
  • Auto Mode / Plan Mode ★★：Shift+Tab で Ask → Plan → Auto のモードを循環。Auto Mode はモデルベース classifier (= 小型モデルでコマンドの安全性を自動分類する分類器) が各コマンドの安全性を判定して自動承認する仕組みで、Boris は「dangerously-skip-permissions の代わりにこれを使え」と推奨しています。

2.4 🔥 Hot 機能群 (新機能、優先度高)​

2026 年に入って急速に追加された機能群です。一部は beta 表記がついていて仕様変更の可能性がありますが、業務での活用余地が大きいものを中心に紹介します。

機能難易度用途
Ultrareview ★★beta/ultrareview で multi-agent な PR レビュー。GitHub PR# を指定して走らせると複数視点でレビューが並列実行される
Ultraplan ★★beta/ultraplan で大規模な計画立案。Plan mode の上位版
Auto Mode ★beta上記 §2.3 参照。classifier が安全なコマンドを自動承認
Power-ups ★—/powerup (best-practice/claude-power-ups.md)
Fast Mode ★beta/fast で出力高速化 (モデルはダウングレードしない、Opus 4.6/4.7 で利用可)
Chrome ★★beta--chrome で Claude 専用 Chrome 拡張連携。Payload admin 等のログイン状態を共有して操作
Code Review ★betaGitHub App として managed 提供。Boris は「Greptile / CodeRabbit / Cursor BugBot を置き換える」と言及
GitHub Actions ★★—.github/workflows/ で claude を呼び出し。GitLab CI/CD も対応
Remote Control ★★—/remote-control / /rc で headless (= GUI なしで実行する) 操作
Agent Teams ★★★betaenv var で起動、複数 agent を並列実行 (implementation/claude-agent-teams-implementation.md)
Scheduled Tasks ★★—/loop (local 最大 7 日) と /schedule (cloud cron) (implementation/claude-scheduled-tasks-implementation.md)
Routines ★★betacloud で動く scheduled agent。マシンがオフでも実行される
Goal ★★—/goal <condition> で「条件達成までターン自動反復」 (implementation/claude-goal-implementation.md)
Voice Dictation ★beta/voice で音声プロンプト
Computer Use ★★★betacomputer-use MCP server。デスクトップ操作の自動化
Git Worktrees ★★—--worktree / -w で並列開発。Boris は 5 通りの使い方を 紹介
Simplify & Batch ★—/simplify / /batch の bundled skill
Ralph Wiggum Loop ★★★—プラグイン。長時間自律ループ。実装は 別リポ で公開

なお、表中の Git Worktrees は git 標準機能で「同じリポジトリを別ディレクトリにチェックアウトして並列作業できる仕組み」のことです (git worktree add ../feature-x feature-x のように使います)。Claude Code の --worktree フラグや subagent の isolation: worktree 設定は、この機能を使って main workspace から作業を隔離します。

筆者の実装例 (~/.claude/)

筆者は --worktree フラグそのものは多用していませんが、subagent (debugger / refactorer / code-reviewer) を isolation: worktree で起動するパターン1 を採用しています。長時間 / 破壊的になりやすいレビューやリファクタを main workspace から隔離し、失敗時の巻き戻しを安全にしています。

Auto Mode は permission prompt 削減効果を活用しています。Plan mode 承認後の自動実装で classifier が block するケースには、AskUserQuestion ツールで筆者に明示認可を求める動線を組んでいます (Phase 13 W1-1 ratchet)。この動線は ~/.claude/rules/ask-user-question.md の規範によるものです。Auto Mode の便利さと破壊的操作の認可ギャップを harness で吸収する設計です。

採用判断

迷ったらまず ★ から導入します。Plan Mode、Commands、Settings あたりは初日から効きます。★★ の Subagents / Skills / Hooks は次の週末で 1 つ作ってみると進歩が大きい領域。★★★ (Agent Teams / Computer Use / Hooks 自作 / Ralph Wiggum) は基本機能を組み合わせて手応えを得てから挑む順番が安全です。

第 3 章: Orchestration Workflow ショーケース​

このリポの中央に置かれているのが Command → Agent → Skill という 3 層オーケストレーションです。作者はこれを /weather-orchestrator という気象データ取得ワークフローで実演しています (orchestration-workflow.md)。

この showcase が伝える設計の要点は 2 つあります。

1 つ目は 2 つの Skill パターン の使い分けです。weather-fetcher は weather-agent の frontmatter に skills: フィールドで指定され、agent が起動した瞬間に context へ全文 inject されます (Agent Skills パターン)。一方 weather-svg-creator は preload されておらず、command が Skill tool を呼び出した時点で初めて発火します (Skill パターン)。前者は agent に「ドメイン知識を骨格として持たせる」用途、後者は「成果物を作る」用途、と覚えれば整理がつきます。

2 つ目は 役割分担の徹底 です。Command がワークフローを指揮し、Agent がデータ取得などのドメイン作業を担い、Skill が成果物を出力する。3 層がそれぞれ単一責任で並んでいるため、後から「fetcher を OpenWeather に差し替える」「SVG ではなく PNG を出す」といった変更が局所化されます。実装ファイルは .claude/commands/weather-orchestrator.md と .claude/agents/weather-agent.md で直接参照できます。skill 側は .claude/skills/weather-fetcher/SKILL.md と .claude/skills/weather-svg-creator/SKILL.md です。

リポを clone して /weather-orchestrator を実行すれば、上記の流れがそのまま手元で再現できます。3 層構造を学ぶ題材としては、このリポで一番手を動かしやすい素材です。

筆者の実装例 (~/.claude/)

筆者は weather example と同じ「3 層オーケストレーション」の発想で、~/.claude/teams/multi-perspective-review/ という team 構成を組んでいます。違いは weather example が「Command → Agent → Skill」の 異種役割の直列実行 であるのに対し、こちらは 同種 Evaluator agent の並列実行 という点です。

  • Team 構成: code-reviewer + architect + test-strategist の 3 つの Evaluator subagent を並列起動
  • trigger 発話: 「複数視点でレビュー」「総合レビュー」「3 視点」(10 ファイル以上の変更時に推奨)
  • 統合: 各 agent が独立に出した judgment を main agent が統合し、重複指摘を整理した上で筆者に提示

設計目的は「単一 Evaluator では観点漏れが発生する大規模変更を、独立した 3 視点で冗長検証する」ことです。weather example の「定型タスクを直列で組み立てる」用途とは対照的に、こちらは「重要判断を並列で冗長化する」用途で、3 層構造の応用範囲の広さを示す事例として参考にできます。

なお Agent Teams 機能が無効な環境でも、Task tool での fallback 経路 (main agent が 3 subagent を逐次呼ぶ) を team.md に記載しており、機能変動に対する耐性も組み込んでいます。

採用判断

このパターンを理解するには、weather example をそのまま clone して動かすのが手っ取り早いです。自分の業務でも「定型レポート生成」「データ取得 + 可視化」のような 3 ステップで終わる作業を 1 つだけ、この 3 層構造で書き直してみると pattern が身につきます。

第 4 章: 12 の開発ワークフローを比較する​

README の ⚙️ DEVELOPMENT WORKFLOWS セクションは、コミュニティで公開されている主要ワークフロー 12 件を star 数順に並べて比較しています。各ワークフローは「複数の slash command やスキルを連鎖させて開発を進める方法論」で、それぞれ思想と粒度が異なります。

ワークフロー★流れの特徴構成数 (A / C / S)向き
Superpowers200kbrainstorming → worktrees → writing-plans → subagent-driven → TDD → code-review → verification → finishing0 / 0 / 14TDD + 並列開発を重視する人
Everything Claude Code (ECC)188k/ecc:plan → /tdd → /code-review → /security-scan → /e2e → merge48 / 143 / 230商用プロダクトでフルセット導入
Spec Kit104k/speckit.constitution → .specify → .clarify → .plan → .tasks → .implement0 / 9 / 0仕様駆動の最小構成を体験
gstack100k/office-hours → 3 種類の /plan-*-review → /design-shotgun → /review → /ship → /retro0 / 0 / 48CEO/Eng/Design の多角レビューを回したい
Matt Pocock Skills97k/grill-with-docs → /to-prd → /to-issues → /triage → TDD → /diagnose → /improve-codebase-architecture0 / 0 / 28要件詰めから PRD 化までを丁寧に
Get Shit Done63k/gsd-new-project → discuss → plan → execute → verify → ship → complete-milestone33 / 67 / 0個人開発で速度を求める
OpenSpec50k/opsx:propose → :apply → :archive の 3 段0 / 11 / 03 段だけのミニマル仕様駆動
BMAD-METHOD48kproduct-brief → PRD → architecture → epics-and-stories → sprint-planning → story-by-story 実装0 / 0 / 42PdM/PM と協働するチーム
oh-my-claudecode34k/deep-interview → /team → 5 段 team フロー → /ralph → merge19 / 0 / 39Team モードと Ralph ループを使いたい
agent-skills27k/spec → /plan → /build → /test → /review → /ship3 / 7 / 21王道 6 段、迷ったらここから
Compound Engineering17k/ce-ideate → brainstorm → plan → work → code-review → debug → optimize → compound49 / 4 / 38アイデア発散段階から伴走させたい
HumanLayer11k/create_plan → /validate_plan → /implement_plan → /iterate_plan → /local_review → /commit6 / 27 / 0Plan 検証と iteration を厳密に分けたい

A = Agent / C = Command / S = Skill の数。表中の略語は以下のとおりです。TDD = Test-Driven Development (テスト駆動開発、テストを先に書いてから実装する手法)。PRD = Product Requirement Document (製品要件定義書)。RPI = Research-Plan-Implement (調査 → 計画 → 実装の 3 段階パターン)。

12 件の流れを並べて眺めると、構成要素の粒度や名前は違っても どれもほぼ同じパターンに収束している ことが分かります: Research → Plan → Execute → Review → Ship。これは作者本人が README で強調しているポイントで、ベテランほどこの 5 段に自然と寄っていく、という観察的事実とも一致します。

ワークフローを選ぶ際の見方をいくつか挙げます。Spec Kit は 6 個の slash command だけで完結する最小構成で、まず「仕様駆動の流れ」を体験するのに適します。Everything Claude Code (ECC) は 48 agents + 143 commands + 230 skills という超大規模で、商用プロダクトでフルセット導入したい人向け。BMAD-METHOD は PRD → architecture → sprint planning という「マネジメントの言葉」で構成されているので、PdM や PM と協働するチームに馴染みやすい。Matt Pocock Skills は /grill-with-docs で要件を詰めてから PRD 化する流れが特徴的で、Matt 氏自身の YouTube 解説と組み合わせれば理解が早いです (リポ内 videos/claude-matt-pocock-24-apr-26.md)。

リポ独自の方法論として、development-workflows/ ディレクトリには Cross-Model Workflow (cross-model-workflow.md) と RPI Workflow (rpi-workflow.md) が独自に整備されています。RPI は Plan agent と 8 種類の専門 agent を組み合わせた research-plan-implement パターンの実装です。専門 agent は constitutional-validator / requirement-parser / ux-designer / senior-software-engineer 等です。リポ内 .claude/agents/ に実体ファイルがあるため、そのまま参照できます。

筆者の実装例 (~/.claude/)

筆者は表中の 12 ワークフローのどれも 丸ごとは採用していません。代わりに、Plan-and-Solve (ACL 2023) / Plan-and-Act (ICML 2025) の論文エビデンスを根拠に、plan-then-execute Workflow Gate という規範を採用しています。これは ~/.claude/rules/plan-then-execute.md に harness 規範化したものです。「3 ファイル以上 / 不慣れ領域 / アーキテクチャ判断 / 不可逆変更を伴うタスクは、実装着手前に必ず Plan フェーズを分離する」というシンプルな gate です。

SPECIFY → PLAN → TASKS → IMPLEMENT の 4-phase 構造そのものは、表中 12 件には含まれていない addyosmani/agent-skills (MIT) の spec-driven-development skill で運用しています。この skill は ~/.claude/skills/spec-driven-development/ に取り込み済みです。Skill が trigger 発話 (「仕様駆動」「spec から進めて」) で自動起動するため、Spec Kit のように /specify.constitution から手動で打鍵する必要がありません。

ワークフローを「外部からまるごと導入する」のではなく 「個別 skill 単位で取り込んで自前 rule と組み合わせる」 のが筆者方針で、これは表中のどのワークフローとも違う独自スタイルです。BMAD-METHOD の PRD → architecture の流れや Get Shit Done の discuss → plan → execute 等は、参考にした部分があれば個別の skill description にコメントを残す運用にしています。

採用判断

1 つだけ採用するなら Spec Kit (シンプル、6 コマンドだけ) か ECC (網羅型、商用想定) を推奨。チームに導入するなら BMAD-METHOD、個人で速度を求めるなら Get Shit Done あたりも候補。複数試してみて、しっくり来るものを 1 つだけ残す方が定着します。

第 5 章: Skill / Agent コレクションライブラリを借りる​

ワークフローではなく、個別の SKILL.md / agent.md を「ライブラリ」として配布しているリポも多数あります。README の 🧰 SKILL COLLECTIONS と 🤖 AGENT COLLECTIONS セクションがこれを整理しています。

Skill コレクション (8 件、star 数順):

リポ★Skill 数
anthropics/skills138k17
mattpocock/skills97k24
wshobson/agents36k155
impeccable27k1 (デザイン 7 ドメイン参照)
addyosmani/agent-skills27k21
scientific-agent-skills25k138
awesome-agent-skills22k1,100+ (キュレーション一覧)
claude-skills15k246 (9 ドメイン横断)

Agent コレクション (2 件):

リポ★Agent 数
msitarzewski/agency-agents105k144
VoltAgent/awesome-claude-code-subagents20k151

選び方のポイントは 2 つあります。1 つは ドメイン特化か汎用か。デザイン業務なら impeccable、研究用途なら scientific-agent-skills が個別ドメインに最適化された SKILL.md を提供します。汎用なら Anthropic 公式の anthropics/skills と Matt Pocock 氏の mattpocock/skills を入れておけば日常作業はカバーできます。

もう 1 つは メンテナンス頻度。Claude Code 自体が頻繁にアップデートされるので、半年以上更新が止まっているリポは frontmatter フィールドが古い可能性があります。README の表は star 数だけでなく更新時期も把握できるよう作られているので、コレクションを選ぶ際は元リポの commit 履歴も合わせて確認すると安全です。

筆者の実装例 (~/.claude/)

筆者は外部コレクションを 丸ごとは採用せず、自前で 38 skills + 7 agents + 1 team を運用しています。理由は以下の 2 点です。

  • trigger 発話のカスタマイズが必要: 各 skill の自動起動条件 (「レビューして」「バグ」等の日本語発話) を自分のタイピング習慣に合わせて細かく設定したいため、外部 skill を入れると description 全件を再編集することになりがち
  • Generator-Evaluator 分離の意図的設計: 第 2.1 章で述べたとおり、agent 群は「作る側 3 / 評価する側 4」で role-based 分離を意図的に組んでいる。外部 agent コレクションは「全部 generalist」「全部 specialist」のどちらかに寄っているケースが多く、設計思想ごと取り込めない

ただし「自前 vs 外部」は二項対立ではなく 個別 skill 単位で取捨選択 しています。例えば前章で触れた spec-driven-development skill は addyosmani/agent-skills (MIT) から取り込んだもので、自前 rule (~/.claude/rules/plan-then-execute.md) と組み合わせて使っています。コレクション全体を導入するのではなく「気に入った skill だけ 1 つずつ取り込み、自前環境と整合させる」運用が現実的です。

採用判断

ドメイン特化が要るなら専用 collection (impeccable / scientific-agent-skills 等) を、そうでなければ anthropics/skills + mattpocock/skills の 2 つだけ で十分実用的。awesome-agent-skills は 1,100+ のキュレーション一覧なので「他に何があるか」を探す入口として使います。

第 6 章: Cross-Model WorkflowsClaude Code に他モデルを混ぜる​

README の 🔀 CROSS-MODEL WORKFLOWS セクションでは、Claude Code を Codex / Gemini / GPT / Kimi / DeepSeek / local モデル等と組み合わせる方法が 3 つの方式 に分類されています。

方式概念代表リポ
Plugin他モデルの CLI を Claude Code 内から呼び出す (/codex:review 等)openai/codex-plugin-cc (18k★)
MCPClaude Code が他モデルを「tool」として呼ぶBeehiveInnovations/pal-mcp-server (12k★、Gemini / OpenAI / Azure / Grok / Ollama / OpenRouter 50+ モデル対応)
RouterClaude Code の API endpoint を別 provider に振り替えmusistudio/claude-code-router (34k★)、router-for-me/CLIProxyAPI (32k★)

リポ独自の方法論 development-workflows/cross-model-workflow/cross-model-workflow.md は、Plan を Claude Code で、QA-Review を Codex で行う「手動 2-terminal フロー」を推奨しています。これは Plugin / MCP / Router いずれにも依存せず、すぐ試せる構成です。

筆者の実装例 (~/.claude/)

筆者は cross-model を 意図的に採用していません。Anthropic 内のモデル群 (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) を subagent の model: フィールドと Fast Mode (/fast) で使い分けます。さらに adaptive thinking (effort level low/medium/high/xhigh/max) も併用すれば、必要な推論深さとコストのバランスは取れているという判断です。

cross-provider router (musistudio/claude-code-router 等) を導入すると、料金体系の二重管理 / Anthropic 公式機能との互換性のリグレッション追跡 / 用途別の品質差検証 / API key 管理の複雑化など、運用負荷が大きく上がります。これに見合うリターン (例: DeepSeek でコスト 1/10 化など) が筆者業務では明確でないため、現時点では Anthropic 単独運用を続けています。

将来採用するとしたら、第一候補は router 方式 (claude-code-router 経由で OpenRouter にバックアップを通す) です。Plugin 方式 (openai/codex-plugin-cc で Codex を /codex:review として呼ぶ) は cross-model QA レビューが必要な場面が増えれば検討、という温度感です。

なお Anthropic 内ルーティングについては、effortLevel: xhigh を default にしています。architect / debugger / propose 等 28 件の subagent / skill では frontmatter で effort: max を上書き指定する、という細かい使い分けを harness で組んでいます。詳細は第 7 章の Workflows Advanced カテゴリで触れます。

採用判断

主要モデルを Claude Code 内に統合したいなら Plugin (openai/codex-plugin-cc) です。コスト最適化したいなら Router (musistudio/claude-code-router で OpenRouter / DeepSeek / Ollama に振り分け)。Claude を主役のまま他モデルに QA レビューさせたいなら MCP (pal-mcp-server) という棲み分けで考えると選びやすいです。

第 7 章: 83 個の Tips を 15 カテゴリで概観する​

README の 💡 TIPS AND TRICKS (83) セクションは、開発陣やコミュニティから集められた Tips を 15 カテゴリ に分けて表化したものです。出典は Boris Cherny (Claude Code 開発者) / Thariq (Anthropic) / Cat Wu / Dex Horthy / Lydia Hallie / コミュニティ等です。各 Tip には元ツイートや元動画への直リンクが付いていて、文脈ごと辿れるようになっています。

カテゴリと件数、そして象徴的な Tip を 1-2 個ずつ取り上げます。

カテゴリ件数象徴的な Tip
Prompting3"grill me on these changes — PR を作る前に Claude にテストさせろ" (Boris)
Planning/Specs7"always start with plan mode" (Boris), "AskUserQuestion で Claude にインタビューさせて仕様を引き出す" (Thariq)
Context5"context rot は ~300-400k tokens 周辺で発生" / "dumb zone は ~40% context — 新人は 40%、ベテランは 30% 以下を死守" (Thariq / Dex)
Session Management6"new task = new session" / "/compact vs /clear はトレードオフ" (Thariq)
CLAUDE.md + rules8"CLAUDE.md は 200 行以下、humanlayer は 60 行" / "paths: frontmatter で lazy-load"
Agents4"feature 特化型 subagent を作れ、general qa とか general backend とかは作るな" (Boris)
Commands3"1 日 1 回以上やる作業は skill か command にせよ" (Boris)
Skills9"skills are folders, not files — references/, scripts/, examples/ で progressive disclosure" / "Gotchas section は最重要、Claude の失敗ポイントを蓄積せよ" (Thariq)
Hooks5"PostToolUse hook で auto-format — Claude が生成するコードの最後 10% を仕上げて CI failure を防ぐ" (Boris)
Workflows5"thinking mode true + Output Style Explanatory で意思決定が見える" (Boris)
Workflows Advanced9"/sandbox で permission prompt -84%" / "Opus 4.7 の effort level を low / medium / high / xhigh / max で動的調整" (Boris)
Git / PR5"PR の p50 は 118 行 — 141 PR / 45K 行/日 のうち中央値" / "always squash merge" (Boris)
Debugging6"screenshot を Claude に渡せ" / "agentic search (glob + grep) beats RAG — Claude Code は vector DB を試して破棄した" (Boris)
Utilities5"iTerm / Ghostty / tmux > IDE" (Boris)
Daily2"Claude Code を毎日アップデート" / "朝、CHANGELOG を読む"

各カテゴリの右側には Boris / Thariq の元投稿リンクが付いていて、原文の文脈を確認できます。特に tips/claude-boris-6-tips-16-apr-26.md (Opus 4.7 関連の最新 6 Tips) には、2026 年時点の Claude Code 運用に直結する内容がまとまっています。tips/claude-thariq-tips-16-apr-26.md (Session Management と 1M context の使いこなし) も同様です。

Tips の中には 🚫👶 (do-not-babysit) というマークが付いているものがあります。これは「Claude に細かく口出しせず任せろ」系の Tip を区別するためのアイコンです。grill me、fix だけ言う、use subagents to throw more compute at it、Code Review の自動化、@claude でレビュー lint rule を自動生成、等が代表例です。「Claude を信頼して手放す」段階に進む人向けの位置づけです。

CLI binary から抽出された hidden Tips は reports/claude-spinner-verbs-and-tips.md にまとめられています。こちらでは、公式 README には載っていないものの CLI 内部で使われているスピナー verb (Pondering, Cogitating, Synthesizing 等) と関連 Tips も拾えます。

筆者の実装例 (~/.claude/)

主要 5 カテゴリの Tips に対する筆者の実装を対比表にまとめます。

カテゴリshanraisshan の象徴的 Tip筆者の実装 (~/.claude/)
CLAUDE.md + rules"CLAUDE.md は 200 行以下"436 行 (推奨の 2 倍超だが意図的)。詳細は path-scoped rule 20 件 + references/ 30 件に分散。常時 load は 10 件 / 722 行に抑制
Skills"Gotchas section は最重要"doubt-driven-development / mcp-builder / grill-me 等の SKILL.md に "When to Use" / "Loading Constraints" セクションを実装
Hooks"PostToolUse hook で auto-format"format ではなく suppression 検出 (check-suppression.sh) + 平文質問検出 (check-plain-question.sh) に転用
Agents"feature 特化型 subagent を作れ"architect / code-reviewer / debugger 等 7 件すべて特化命名、generalist 系ゼロ
Workflows Advanced"effort level を低 / 中 / 高 / xhigh / max で動的調整"~/.claude/settings.json で effortLevel: xhigh を default 化、frontmatter で skill 別に effort: max (architect / debugger / propose 等 28 ファイル) で上書き

ここで補足を 4 つ追加します。

Gotchas / Loading Constraints セクション が Tips で「最重要」と言われている理由は、SKILL.md の本文で「この skill が失敗しやすい条件 / 使ってはいけない場面」を明示すると、Claude が起動判断を間違えなくなるからです。筆者の ~/.claude/skills/grill-me/SKILL.md から実例を抜粋すると、以下のような構成になっています。

---
name: grill-me
description: 要件・設計を厳しい質問で詰めて曖昧性を排除する skill...
---

## When to Use
- タスク着手前の要件解像度向上
- 仕様が曖昧な状態で実装すると手戻りが大きい場面

## Gotchas (使ってはいけない場面)
- 既に明示指示済みの作業継続中 → 過剰な質問になる
- 純粋な事実確認 (Read / Grep で解決可) → AskUserQuestion を 1 回だけで十分

## Loading Constraints
- context が 50k tokens 超のときは skip 推奨 (詰問が context を圧迫する)
- 他 skill が in_progress の場合は割り込まない

このように ## Gotchas と ## Loading Constraints をセクション化しておくと、Claude が「今この skill を起動すべきか」を構造的に判断できます。逆にこれが無いと、不適切な場面で skill が暴発しやすくなります。

Path-scoped rule (lazy-load) とは、rule ファイルの frontmatter に paths: ["**/*.ts"] のような glob を書いておく方式です。その glob にマッチするファイルを Claude が Read した時だけ、rule が自動 load されます。frontmatter は以下のような形になります。

---
paths: ["**/*.ts", "**/*.tsx"]
---

# TypeScript Strict Mode 規範
- `any` 型は禁止
- ...

常時 load にすると context window を圧迫しますが、path-scoped にすればフロントエンド作業中はフロントエンド rule だけ、infra 作業中は terraform rule だけ、と必要なものだけが context に注入されます。筆者は 31 件中 20 件 (64%) を path-scoped 化して 200 行制約を実質的に回避しています。

Effort level は Opus 4.7 で推論の深さを動的に切り替えるパラメータ (low / medium / high / xhigh / max)。Anthropic 公式では coding/agentic タスクで xhigh が default 推奨です。max は overthinking (考えすぎ) + diminishing returns (= 投入量を増やしても得られる効果が頭打ちになる現象) リスクのため、日常 default にしないとされています。筆者は重要判断 (architect / debugger / propose 等) のみ frontmatter で max に上書きし、コスト効率を保ちつつ深い推論が必要な場面で精度を出しています。

Ratchet という用語が Tips に頻出します。これは「同じ失敗を 2 度起こしたら必ず rule / hook / learning のいずれかに永続化して、再発を構造的に不可能にする」原則のことで、筆者 harness では ~/.claude/rules/ratchet-workflow.md として規範化しています。Claude が同じミスを繰り返したら、その都度 prompt で叱るのではなく、deterministic な sensor (hook) や inferential guide (rule) に組み込んで「次は仕組みで防ぐ」という発想です。

なお ~/.claude/learnings/ には、core / frontend-vue / frontend-react / infra のカテゴリ別に 14 ファイル / 4,363 行の知見が蓄積されています。/learn skill の trigger 発話 (「追記して」「覚えといて」) で、1 件単位で即座に永続化する運用です。

採用判断

全 83 件を一度に読まず、直近で困っているカテゴリ だけ拾います。Context や Session Management で苦戦している人は Thariq の 16/Apr/26 まとめだけで方針が立ちます。Opus 4.7 や Auto Mode を試したい人は Boris の 16/Apr/26 まとめを優先。🚫👶 マークの Tips は中級者以上向けと捉えてください。

第 8 章: 12 本の Reports深掘り資料の地図​

reports/ ディレクトリには 12 本の深掘り解析が格納されています。Tips が「箇条書きで覚える知識」だとすれば、Reports は「文章で理屈を理解する読み物」です。

Report用途こんな読者に
why-harness-is-important「features は prompt と同じ」論への反論 (10 capability 表)harness の価値を疑っている人
claude-agent-memorymemory の 3 scope (user/project/local) を詳細解説セッション跨ぎ知識を永続化したい人
claude-global-vs-project-settings設定階層 6 段 + Tasks system個人 / チーム / 組織の設定境界を整理したい人
claude-agent-command-skill3 機能 (agent / command / skill) の境界線「どれを使うべきか」迷う人
claude-skills-for-larger-mono-reposmonorepo での skill 配置戦略複数 package を扱う人
claude-in-chrome-v-chrome-devtools-mcpブラウザ MCP (Claude in Chrome vs Chrome DevTools) の使い分けfrontend / E2E で Claude にブラウザ操作させたい人
llm-day-to-day-degradationモデル「劣化」現象の追跡と検証「最近 Claude が頭悪い気がする」と感じる人
claude-usage-and-rate-limitsrate limit の構造とプラン別上限業務利用でコスト管理する人
claude-advanced-tool-usetool use の高度パターンカスタム tool を実装する人
claude-agent-sdk-vs-cli-system-promptsAgent SDK vs CLI の system prompt 差分 (110+ fragments)SDK で独自 agent を組む人
claude-spinner-verbs-and-tipsCLI binary から抽出した hidden tipsClaude Code を deep dive したい人
learning-journey-weather-reporter-redesignweather example の設計再考過程orchestration pattern を学ぶ人

1 本だけ深掘り: why-harness-is-important.md​

12 本の中で最初に読むべき 1 本を選ぶなら why-harness-is-important.md です。これは「skills / commands / subagents / hooks も結局モデルに渡る prompt なんだから、強い prompt を 1 本書けば同じ結果になる」という reduction (還元論) への反論を、表形式で整理した論考です。

論旨の中核を要約すると次のようになります。

  • 単発タスク (例:「再帰版 flatten 関数を書け」) では確かに Output quality ≈ Prompt quality が成立する。これがチャットボットの世界。
  • だが本物のソフトウェア開発では Output quality = f(effective context, model capability, iteration loop) という関係になる。effective context (モデルが推論時に見るもの) はユーザーが打った prompt よりはるかに大きい。
  • harness の役割は、ユーザーが打った 6 トークンの prompt を、推論時には 5,000〜50,000 トークンの effective context に変換することにある。
  • harness にしかできない capability が 10 個ある。例えば context isolation (subagent が別 window で動く) や、harness-enforced tool restrictions (disallowedTools 等の deny 設定でモデルが tool を使う前にブロック)。lazy-loaded rules (paths: frontmatter)、hooks の deterministic な execution、model: による model routing、subagent の parallelism も挙がる。さらに memory による cross-session persistence、modular system prompt (CLI 内部で 110+ fragments を条件付き load) も該当する。最後が skill preloading と auto モードの permission classifier だ。これらは strong wording で代替できない。

ここで重要概念の Effective context について少し補足しておきます。これは「ユーザーが打鍵した prompt そのもの」ではなく、「harness が裏で注入する CLAUDE.md / rules / skills / agents 定義 / memory / MCP 出力をすべて合計した、推論時に実際にモデルが見る情報の総体」のことです。6 トークンの prompt が 5,000〜50,000 トークンの effective context に膨らむのが harness の役割です。これが「rules を強い文言で書けば済む」という reduction (還元論) では代替できない理由になっています。

このレポートを先に読んでおくと、第 2-4 章で紹介した機能群がなぜ存在するのかを理屈として捉えやすくなります。残り 11 本は自分の興味に応じて選ぶ形で問題ありません。memory に困っているなら claude-agent-memory、settings 階層を整理したいなら claude-global-vs-project-settings を選びます。ブラウザ自動化を考えているなら claude-in-chrome-v-chrome-devtools-mcp、という具合です。

筆者の実装例 (~/.claude/)

筆者は ~/.claude/ を Phase 0-13 の段階的進化として育ててきました。Phase は筆者固有の用語で、harness を一気に完成形にせず「節目ごとに rules / hooks / skills / agents を追加して必要性を検証する」運用の単位です。代表的な節目:

  • Phase 0: harness engineering 概念導入 (Guides × Sensors 二分法)
  • Phase 1: Computational Guards 実装 (check-suppression.sh / check-protected-files.sh 等の hook)
  • Phase 6: 4 指標 (Task Resolution Rate / Code Churn Rate / Verification Tax / Defect Escape Rate) による health check 計測
  • Phase 11: rules の path-scoped 化と token reduction (常時 load を 10 件 / 722 行に圧縮)
  • Phase 13: 持ち越し吸収 + Notification Sensor 整備 (最新の transitional)

各 Phase の意思決定は ADR (Architecture Decision Record) として ~/.claude/docs/adr/ に 16 件記録しています。ADR は「重要な設計判断を 1 件 1 ファイルで markdown 記録する慣習」で、「なぜそうしたか」を後から辿れます。代表的な ADR:

  • ADR-0001: harness self-review を月次 / 四半期 cron 化
  • ADR-0004: Phase 進化ロードマップ (Foundation 0-6 / Consolidation 7-9 / Next-Gen 10+)
  • ADR-0011: Opus 4.7 の effortLevel を env 撤去 + settings.json field に移行
  • ADR-0013: Plan-then-Execute を Workflow Gate として規範化

why-harness-is-important.md で紹介されている harness の 10 capability は、筆者環境では Phase 0-13 の追加ロードマップとほぼ対応しています。10 capability の内訳は context isolation / harness-enforced tool restrictions / lazy-loaded rules / hooks の deterministic execution / model routing です。残りが subagent parallelism / memory cross-session persistence / modular system prompt / skill preloading / Auto Mode classifier です。harness は「完成」ではなく「継続的に Ratchet を積み上げる」性質のもの、というのが Phase 運用から得た実感です。

なお Phase の詳細な背景理論や規範は別記事 harness-engineering でより深く扱っているので、harness の枠組み自体に興味がある方はそちらを参照してください。

採用判断

まず why-harness-is-important.md 1 本だけ読んで「features の価値」を腑に落とす。残り 11 本は「いま自分が困っているテーマ」のものだけ 1-2 本選んで読みます。全部読破しようとすると 30 分以上かかるので、必要な時に必要な分だけ。

第 9 章: 取捨選択ロードマップ自分のレベルで何を選ぶか​

ここまでで紹介してきた全要素から、自分のレベルに合うものだけ選ぶ ためのロードマップを 4 種類提示します。複数を中途半端に走らせるより、1 つを完走してから次に進む方が定着するため、まず自分の現在地に近いものを 1 つだけ選んでください。

9.1 初心者ロードマップまず Claude Code を動かせるようになる​

Claude Code をインストールしたばかり、または使い始めて 1 週間以内の段階を想定。

  1. セットアップ: tutorial/day0/README.md を読み、OS 別の手順 (linux / mac / windows) でインストール
  2. 初プロジェクト: tutorial/day1/README.md を辿って Claude Code を使った最初のコード生成を体験
  3. Tips 入門: Boris 13 Tips (03/Jan/26) を一読
  4. 実践: Tips の Prompting / Planning/Specs カテゴリだけ実践 (plan mode から始める / AskUserQuestion で仕様を引き出す / spec を書く)

この段階では subagent や hooks に手を出さず、まずは Claude Code 単体での会話と plan mode に慣れることに集中します。

9.2 中級者ロードマップ基本機能を組み合わせる​

Claude Code は使えているが、自分で .claude/ を育てるのはこれから、という段階を想定。

  1. 概念理解: best-practice/claude-subagents.md + claude-commands.md + claude-skills.md を順に通読
  2. showcase 実行: orchestration-workflow.md を clone して /weather-orchestrator を動かす
  3. Tips の応用: CLAUDE.md, Skills, Hooks カテゴリを実践 (CLAUDE.md を 200 行以下に整理、自分の skill を 1 個作る、PostToolUse hook で auto-format を仕込む)
  4. 自作: 自分の業務で 1 日 1 回以上やる作業を題材に、slash command を 1-2 個作る

この段階で自分の .claude/commands/ が 1 個でも増えれば、Claude Code との関係が変わってきます。

9.3 上級者ロードマップharness を設計する​

すでに自分の .claude/ を運用していて、次の改善方向を探している段階を想定。

  1. 理屈の整理: why-harness-is-important.md で harness の 10 capability を再確認
  2. 大規模ワークフローの精読: Superpowers (14 skills) と ECC (48 agents + 143 commands + 230 skills) のソースを読む
  3. cross-model 導入: cross-model-workflow.md を参考に Codex で QA レビューを 2-terminal で試す
  4. 並列化: agent teams / git worktrees / scheduled tasks の実装例を 1 つ試す
  5. 継続観察: Boris / Thariq の最新 tips を継続購読 (README の 🔔 SUBSCRIBE セクションに集約)
筆者の現在地

参考までに、筆者の ~/.claude/ は 2026 年 5 月時点で Phase 13 (持ち越し吸収 + Notification Sensor 整備) を完了しています。現在は Phase 14 (XML 全展開 + Six Sigma 統計手法 + Tree-of-Thoughts 推論パターン導入) に着手中です。第 8 章で書いたとおり Phase は筆者固有の節目単位で、ADR-0004 に進化ロードマップが残してあります。

実感としては、harness は 「完成して安定運用に入る」性質のものではなく、「四半期ごとに新しい Ratchet を積み上げる」性質のもの です。Claude Code 本体が頻繁にアップデートされる以上、当面はこの「継続的に harness を更新する」モードが続く見込みです。

並列化系 (agent teams / worktree / scheduled tasks) は導入済みですが、cross-model はまだ導入していません (第 6 章で書いた理由)。本格採用は claude-code-router 経由の router 方式から、というのが現時点の見立てです。

9.4 「3 つだけ」採用するなら時間がない人向け​

このリポを読む時間がなく、最も効くものを 3 つだけ採用したい場合の選び方。

  1. Plan Mode を必ず使う (Tips - Planning/Specs カテゴリ): 全ての複雑タスクで plan mode から入る。実装に飛びつかない。
  2. CLAUDE.md を 200 行以下に保つ (Tips - CLAUDE.md カテゴリ): プロジェクト指示書が肥大化すると Claude が無視し始める。簡潔に。
  3. feature 特化型 subagent を作る (best-practice/claude-subagents.md): general qa や backend engineer のような汎用名は避ける。payment-flow-verifier のような具体名の subagent を skill 付きで作る。

この 3 つだけでも Claude Code の出力の安定感は変わってきます。

採用判断

自分のレベルに最も近いロードマップを 1 つだけ選んで、それを完走してから次のレベルへ。並走させると認知負荷が上がって全部中途半端になるので、順序を守ることをおすすめします。

第 10 章: 注意点と Open Questions​

最後に、このリポを参考にする際の注意点と、作者が読者に投げかけている open question を確認します。

10.1 鵜呑みにしない 5 つの注意点​

  • 更新頻度の早さ: リポは Claude Code v2.1.145 (2026-05-19 リリース) ベース。Anthropic 側の機能名や仕様は頻繁に変わるため、重要な判断をする時は 公式 docs で必ず再確認してください。
  • 英語前提: 元 Tip の出典 (X tweet / YouTube / Reddit) は全て英語。リポ内の解説も英語のため、翻訳しながら読むか機械翻訳を併用する場面が出てきます。
  • コピペで動くわけではない: 多くは「実装ヒント」であり、.claude/agents/<name>.md の中身までは書かれていない場合があります。自分のプロジェクトに合わせた調整が前提です。
  • 業界トップの運用 ≠ 個人プロジェクトの最適解: Anthropic 社内や Boris 個人の workflow を、そのままチーム導入しても合わないことが多いです。「なぜそうしているのか」の理屈だけ抜き出して自分の状況に翻訳する姿勢が安全です。
  • コストへの注意: Cross-model workflow、Agent Teams の並列実行、Routines (cloud cron)、Computer Use 等の機能は API クレジット消費が大きく増えます。Anthropic Console で spending limit を必ず設定しておきましょう。

10.2 作者からの Open QuestionsBillion-Dollar Questions​

README 末尾には Billion-Dollar Questions というセクションがあり、作者自身が「自分にも答えがないが、解いた人がいたら教えてほしい」と公開している 13 個の未解決問題が並んでいます。代表的な 3 カテゴリを紹介します。

Memory & Instructions に関する問い (4 問):

  • CLAUDE.md に何を入れて何を入れないか
  • 既に CLAUDE.md がある状態で、別に constitution.md や rules.md は必要か
  • CLAUDE.md はどれくらいの頻度で更新すべきで、古くなったとどう判別するか
  • なぜ Claude は MUST と全大文字で書いても CLAUDE.md の指示を無視するのか (reddit 投稿: 80% 無視される事例)

Agents, Skills & Workflows に関する問い (6 問):

  • command vs agent vs skill はいつ使い分けるか — そして「vanilla な Claude Code」だけで十分なケースはどれか
  • agents / commands / workflows はモデル進化のたびに更新が必要か
  • generalist subagent vs feature/role 特化型 subagent はどちらが良いか
  • Claude Code 標準の plan mode を使うか、それともチームの workflow を強制する自前の plan command/agent を作るか
  • 個人 skill (例: 自分のコーディングスタイル付き /implement) とコミュニティ skill (例: /simplify) はどう共存させるか
  • 既存 codebase を spec markdown に変換 → コード削除 → AI に spec から再生成させて元と同じコードが復元できる時代は来るか

Specs & Documentation に関する問い (3 問):

  • 全 feature に spec markdown が必要か
  • spec の更新頻度はどう保つか
  • 新機能実装で他 spec への波及をどう管理するか

これらは「正解」を作者が知っているわけではなく、読者がそれぞれの現場で答えを見つける性質の問いです。本記事を読み終えた後の探求テーマとして覚えておくと、自分の運用が深まります。

採用判断

5 つの注意点を踏まえつつ、Open Questions は「自分の現場ではどう答えるか」を考えながら採用判断する。注意点 3 (コピペで動かない) と 4 (業界トップの運用が自分に合うとは限らない) は特に意識して、リポは「写経対象」ではなく「思考の材料」として扱うのがおすすめです。

第 11 章: まとめと関連リンク​

shanraisshan/claude-code-best-practice は、Claude Code をめぐる公式機能とコミュニティ実践を一次情報リンク付きで集約したキュレーション集です。本記事では 13 ディレクトリ構成、30+ の概念カタログ、12 の開発ワークフロー、8 + 2 のコレクション、3 種の cross-model 方式、83 個の Tips、12 本のレポートを概観し、レベル別の 4 ロードマップで取捨選択の道筋をまとめました。

このリポは「読んで終わり」というより、自分の .claude/ を育てる際の参照先として手元に置いておく類のものです。気になった概念があれば本記事のリンクから該当ファイルへ直接飛んで原文を読む、という使い方が向いています。

関連リンク​

最後に、このリポジトリは継続的にアップデートされています。本記事で紹介した数字 (445 ファイル / 83 Tips / 12 Workflows 等) は 2026 年 5 月 25 日時点のスナップショットです。最新の状態は元 README で確認してください。

Footnotes​

  1. isolation: worktree は subagent の frontmatter で指定する設定で、起動時に一時的な git worktree (作業用ディレクトリ) を自動生成し、変更を main workspace から隔離します。subagent が作業完了 (または失敗) すると、変更がなければ worktree は自動削除され、変更があれば path と branch が返ります。リファクタや大規模 debug など「失敗時に丸ごと破棄したい」作業で、main workspace を汚さずに済むのが利点です。 ↩

記事の感想・フィードバックは X でお気軽にどうぞ

𝕏 で感想をツイート