Claude CodeのワークスペースをGitHubで作る｜スキル・フック・サブエージェント・MCPの設計

「Claude Codeを入れた。それは一番小さな作業だった」——2026年7月9日、AI開発について発信するエンジニアの @granite0x 氏が、自身のX Article「Build Your Opus 4.8 Workspace on GitHub」へのリンクを投稿した。導入文はこう続く。ツールのインストールは本番ではなく、”The setup is everything around the CLI”（セットアップとはCLIの周りにある全部だ）——スキル、フック、サブエージェント、MCPサーバー、ワークフローYAML、そしてcanary。要点は明快だ。Claude Codeというコマンドを入れることは最小の作業で、価値を生むのはその外側の設定一式である、と。

この記事は、その「CLIの外側」を分解し、なぜそれを個人の秘伝にせず GitHubで管理する のかを、公式ドキュメントの一次情報と具体的な設定ファイルで解き明かす。@granite0x氏の投げかけを尊重しつつ、「①結局この設計で何ができる／②何を解決する／③従来の何を代替するのか」に一つずつ答えていく。

Claude Codeのワークスペースとは何か——CLIは「最小の部分」

Claude Codeのインストール自体は、npm install -g @anthropic-ai/claude-code の一行で終わる。だが、それで生産性が跳ね上がるわけではない。実際に効いてくるのは、Claudeに「このプロジェクトではこう振る舞え」「この手順を踏め」「この外部ツールを使え」「この操作は禁止」と教える、CLIの周辺設定である。@granite0x氏はこの周辺設定のまとまりを「ワークスペース」と呼び、その正体を6つに分解した。スキル、サブエージェント、フック、MCPサーバー、ワークフローYAML、そしてcanaryだ。

なぜ「ワークスペース」という言葉が響くのか。Claude Codeを使い込むほど、ユーザーは ~/.claude/（ホームディレクトリの個人設定）と、プロジェクト直下の .claude/（そのリポジトリ専用の設定）に、スキルやエージェントやフックを積み上げていく。これらは単なる設定ファイルの寄せ集めではなく、「自分（やチーム）がAIをどう働かせるか」を定義した、ひとつのプロジェクトになる。ならば、それを他のコードと同じようにGitHubで管理すべきだ——というのが今回の中心的な主張である。

考えてみれば当然の話だ。アプリのコードはバージョン管理するのに、そのコードを書かせるAIの設定は、なぜかローカルのホームディレクトリに散らばったまま、という状態はよくある。新しいマシンに移れば一から作り直し、チームメンバーとは口頭やSlackで「あのフックどう書いてた？」と共有する。ワークスペースをリポジトリ化するとは、この属人性を解体し、設定そのものをレビュー可能・再現可能な資産に変えることに他ならない。

Claude Codeそのもののインストール手順やCLAUDE.mdの全体像、本番運用の基礎は、当サイトの Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き で網羅している。本記事は、その先にある「設定一式をどう構造化し、どうGitHubに載せるか」に絞って掘り下げる。土台はそちらに譲り、ここでは設計の話に集中しよう。

なお、Claude Codeの標準モデルは現行のOpus系（claude-opus-4-8）で、Claude Codeでは思考の深さを表す effort の既定が xhigh になっているなど、長時間の自律作業に振った設計になっている。@granite0x氏がタイトルに「Opus 4.8 Workspace」と冠したのは、こうした自律実行を前提に、CLIの外側をしっかり作り込む価値が高まっているという含意だろう。

ワークスペースを構成する6レイヤー

まずは全体像を押さえる。ワークスペースは、下の6つのレイヤーで構成される。それぞれ「何をするか」「どのファイル／場所に置くか」「いつ効くか」が異なる。

6つの役割を、配置場所とあわせて表にまとめる。

この6つを「内向き」と「外向き」で分けると理解しやすい。スキル・サブエージェント・フックは、Claude Code内部の振る舞いを形づくる内向きの層だ。MCPは外部システムへつなぐ外向きの層。ワークフローYAMLは、その全体をローカルの端末だけでなくGitHubのCI上でも回すための層。そしてcanaryは、これらすべてが期待通りに動いているかを見張る番人である。以降のセクションで、この6つを2つずつペアにして具体的に見ていく。

読者の関心に引き付けて言い換えると、この6レイヤーはそれぞれ別の問いに答えている。「同じ指示を毎回打ちたくない」に答えるのがスキル、「調査ログで会話が埋まる」に答えるのがサブエージェント、「整形やテストを忘れる／危険なコマンドを走らせたくない」に答えるのがフック、「別ツールのデータをコピペしている」に答えるのがMCPだ。ワークフローYAMLは「手元だけでなくPR上でもAIに働いてほしい」に、canaryは「いつの間にか設定が壊れていた」に答える。裏を返せば、いま自分が抱えている摩擦がどれかを見極めれば、6つすべてを一度に作る必要はなく、効くレイヤーから一つずつ足していけばよい、ということでもある。ワークスペースは最初から完成させるものではなく、摩擦を感じた順に育てていくものだ。

スキルとサブエージェント——判断とコンテキストを外部化する

最初のペアは、Claudeの「頭の使い方」を外部化する2つ、スキルとサブエージェントだ。まず、ひとつの要求がどう流れるかを見よう。

スキル：手順と判断をSKILL.mdに切り出す

スキルは、繰り返し使う手順・チェックリスト・多段の作業を、SKILL.md というMarkdownファイルに切り出す仕組みだ。「チャットに同じ指示を何度も貼っている」「CLAUDE.mdの一節が、事実ではなく手順になってきた」——そう感じたら、それはスキルにする合図である。CLAUDE.mdの内容が常時コンテキストに載るのに対し、スキルの本文は使うときだけ読み込まれる（プログレッシブ・ディスクロージャー）。だから、長い参照資料を持たせても、使われるまでのコストはほぼゼロで済む。

構造は驚くほど素朴だ。name と description を持つフロントマターに、本文として手順を書く。公式ドキュメントの最小例に沿うと、こうなる。

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

未コミットの変更を要約し、リスクのある箇所を指摘する。
1. `git diff` と `git status` を確認する
2. 変更をファイルごとに一行で要約する
3. 破壊的変更・秘密情報の混入・未テスト箇所を警告する

肝は description である。Claudeは各スキルの説明文を読んで「いま関連するか」を判断し、関連する場面でだけ本文を読み込む。だから説明は「何をするか」だけでなく「いつ使うべきか」まで書くのがコツだ。上の例が「ユーザーが差分のレビューを求めたとき」と明示しているのは、そのためである。置き場所は次の3つで、名前が衝突したときは個人設定がプロジェクトを上書きする。

・個人：~/.claude/skills/<名前>/SKILL.md（全プロジェクトで使える）
・プロジェクト：.claude/skills/<名前>/SKILL.md（そのリポジトリだけ）
・プラグイン：<プラグイン>/skills/<名前>/SKILL.md（プラグイン名:スキル名 の名前空間）

なお、旧来の .claude/commands/ に置いたカスタムコマンドはスキルへ統合された。.claude/commands/deploy.md と .claude/skills/deploy/SKILL.md はどちらも /deploy を作り、同じように動く。スキル設計をさらに深掘りしたい場合は、Claude Skillsを徹底解説｜スキルはフォルダ と、Anthropic社内で数百個のスキルを運用する知見をまとめた ClaudeチームThariqが明かしたSkills設計9カテゴリ が参考になる。

サブエージェント：副作業を別コンテキストに追い出す

サブエージェントは、調査・レビュー・大量のログ読みといった副作業を、独立したコンテキスト窓で走らせる仕組みだ。狙いは主会話の汚染防止にある。二度と参照しない検索結果やファイル内容で主会話を埋め尽くす代わりに、サブエージェントがその作業を自分の窓で片づけ、要約だけを返す。結果として、主会話のコンテキストは実装の本筋に集中したまま保たれる。

定義は .claude/agents/<名前>.md に置く。フロントマターで name・description・tools・model を指定し、本文がそのエージェントのシステムプロンプトになる。公式ドキュメントの最小例はこうだ。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

重要な設計上の性質が3つある。第一に、サブエージェントは主会話とは別のコンテキスト窓を持ち、渡されるのは上のシステムプロンプトと作業ディレクトリ程度で、Claude Code本体のフルなシステムプロンプトは受け取らない。第二に、tools で使えるツールを絞れる（上の例は読み取り系のみ）。破壊的な操作をさせたくないレビュー用エージェントには、Write・Edit を渡さない、といった制約をかけられる。第三に、model で担当モデルを選べる。単純な探索は速くて安いモデルへ、難所は上位モデルへ、とコストを配分できる。Claudeは各サブエージェントの description を読んで委譲するか判断するので、ここでも「いつ使うか」を明確に書くことが効いてくる。

フックとMCP——決定論的な自動化と外部接続

次のペアは、Claudeの「振る舞いの保証」と「外の世界との接続」だ。スキルとサブエージェントがClaudeの判断に委ねる仕組みだったのに対し、フックは判断に委ねない仕組みである。

フック：ライフサイクルの要所で必ずシェルを走らせる

フックは、Claude Codeのライフサイクルの決まった地点で、ユーザー定義のシェルコマンドを必ず実行する仕組みだ。公式ドキュメントの言葉を借りれば、「Claudeがそれを選ぶことに頼るのではなく、決まった動作を確実に起こす」ための決定論的な制御である。設定は settings.json の hooks ブロックに書く。たとえば、ファイルを編集したら必ずPrettierで整形する、というフックはこうなる。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

matcher で対象ツールを絞り（ここでは Edit と Write）、command にシェルを書く。フックが発火できるライフサイクルイベントは複数あり、代表的なものを挙げる。

・SessionStart：セッション開始・再開時。環境変数や文脈を注入する
・UserPromptSubmit：あなたが送信した直後、Claudeが処理する前。入力を検査できる
・PreToolUse：ツール実行の直前。危険な操作をブロックできる
・PostToolUse：ツール実行が成功した後。整形・テスト・リントを走らせる
・SubagentStop / Stop：サブエージェントやClaudeの応答が終わったとき。通知や後片付けに使う

PreToolUse でブロックできる点が特に強力だ。たとえば「.env への書き込みを禁止」「特定ディレクトリ外の削除を拒否」といったガードを、LLMの判断ではなく設定として保証できる。整形忘れやテスト漏れが「Claudeがうっかり」で起きないのは、この決定論性ゆえである。フックの実運用のコツは前掲のClaude Code実装手引きでも触れているが、要はワークスペースの中で「絶対に守らせたいこと」をフックに、「状況次第で判断させたいこと」をスキルやサブエージェントに振り分けるのが設計の勘所だ。

MCP：外部ツールへClaudeを接続する

MCP（Model Context Protocol）は、issueトラッカー・監視ダッシュボード・社内DB・デザインツールといった外部システムへClaude Codeを接続する、オープンな標準だ。「別のツールからデータをチャットにコピペしている」と気づいたら、それはMCPサーバーを繋ぐ合図である。繋いでしまえば、Claudeは貼り付けられた内容ではなく、そのシステムを直接読んで動ける。

プロジェクトで共有するMCPサーバーは、リポジトリ直下の .mcp.json に書く。プラグインのMCP設定例だが、構造は共通だ。

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": { "DB_URL": "${DB_URL}" }
    }
  }
}

リモートのHTTPサーバーなら、コマンドで追加するのが手早い。トランスポートはHTTP（推奨）とSSE（非推奨）、ローカルのstdioがある。

# リモートHTTPサーバーを追加（例：Notion）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 認証ヘッダー付き
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

MCPには3つのスコープがあり、どこに設定が書かれ、チームと共有されるかが変わる。ワークスペースをGitHubで管理するうえで、この違いは決定的に重要だ。

チームで共有したいMCPサーバーは project スコープ（＝ .mcp.json）に置く。これがGitHubに載り、クローンした全員に届く。逆に、個人の実験的なサーバーや認証情報を含むものは local に留め、バージョン管理から外す。この線引きが、後述するシークレット管理の話につながる。

ワークフローYAMLとcanary——GitHubで回す

ここまでの4レイヤー（スキル・サブエージェント・フック・MCP）は、主にローカルの端末でClaude Codeを動かすための設定だった。最後のペアは、それをGitHub上でも回し、しかも壊れていないことを保証するための層だ。まず、ワークスペース全体がどう連動して動くかを一枚のフローで俯瞰する。

ワークフローYAML：CIでClaude Codeを走らせる

anthropics/claude-code-action を使うと、GitHubのPRやissueで @claude とメンションするだけで、Claudeがコードを解析し、PRを作り、機能を実装し、バグを直す——すべてリポジトリの CLAUDE.md の規約に従って、である。導入はClaude Codeのターミナルで /install-github-app を実行するのが最短で、GitHub Appのインストールと、ワークフローファイル・APIキーの登録まで対話的に案内される。

ワークフローの最小形はこうだ。.github/workflows/ に置く。

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: $
          # コメント中の @claude メンションに反応する

ANTHROPIC_API_KEY はリポジトリのSecretsに入れて参照する。ワークフローファイルに直書きしてはいけない。ワークフローYAMLをワークスペースの一部としてリポジトリに載せておけば、ローカルの端末で使っているのと同じスキルやCLAUDE.mdの規約が、CIの中のClaudeにもそのまま適用される。actions/checkout を挟めば、リポジトリの .claude/skills/ に置いたスキルを prompt: "/skill-name" としてCIから直接呼び出すこともできる。ローカルとCIで同じワークスペースが動く——これがGitHubに載せる大きな効用だ。

canary：設定が静かに壊れたことに気づく

@granite0x氏が6番目に挙げた「canary」は、Claude Codeの公式機能名ではなく、運用パターンである。炭鉱のカナリアと同じで、設定一式が静かに壊れたことを、被害が出る前に知らせる最小の検査を指す。スキルの description を書き換えたら意図せず発火しなくなった、MCPの認証が切れて接続できなくなった、フックのコマンドが環境変更で動かなくなった——こうした退行は、普段の作業では気づきにくい。「昨日まで動いていたのに」と後で気づくのが最悪のパターンだ。

canaryの実装は難しくない。CIのジョブで、既知の入力に対してClaude Codeを走らせ、期待した副作用が起きたかを検証するだけだ。単体テストがコードの退行を捕まえるのと同じ発想を、設定一式に当てはめると考えればよい。たとえば、「テスト用ファイルを編集させ、PostToolUseフックのPrettier整形が実際に走ったか」をチェックする。あるいは「MCPサーバーに1件だけ問い合わせて、接続できるかを確かめる」。定期実行（cron）とプッシュ時の両方で回し、失敗したらCIを赤にする。

name: Workspace Canary
on:
  push:
    paths: [".claude/**", ".mcp.json", ".github/workflows/**"]
  schedule:
    - cron: "0 9 * * *"   # 毎朝、設定の生死を確認する
jobs:
  canary:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: $
          prompt: "canaryスキルを実行し、フックの発火とMCP接続を確認して結果を報告せよ"

ポイントは paths を .claude/**・.mcp.json・.github/workflows/** に絞っていることだ。設定を変えたときだけcanaryが走り、退行があればそのPRのCIが赤くなる。ワークスペースをリポジトリ化して初めて、この「設定変更をトリガーにした自動検査」が可能になる。ローカルのホームディレクトリに設定が散らばっている限り、こうしたゲートはかけられない。canaryは、ワークスペースをGitHubに載せることの価値を最も象徴する層だといえる。

Claude Codeワークスペースをリポジトリとして設計する——構成・再現性・詰まりどころ

最後に、6レイヤーを実際にひとつのリポジトリへまとめる。従来のコピペ運用と何が違うのかを対比してから、ディレクトリ構成と、踏みやすい落とし穴を押さえる。

ディレクトリ構成

典型的なワークスペースは、プロジェクト直下の .claude/（チーム共有）と .github/、そしてホームの ~/.claude/（個人）に分かれる。プロジェクト側の構成はこうだ。

your-project/
├─ .claude/
│  ├─ skills/
│  │  ├─ summarize-changes/SKILL.md
│  │  └─ deploy/SKILL.md
│  ├─ agents/
│  │  └─ code-reviewer.md
│  ├─ settings.json          # チーム共有のフック・設定（コミットする）
│  └─ settings.local.json    # 個人設定（gitignoreする）
├─ .mcp.json                 # プロジェクト共有のMCPサーバー
├─ .github/
│  └─ workflows/
│     ├─ claude.yml           # @claude で反応するワークフロー
│     └─ canary.yml           # 設定の生死を見張るcanary
└─ CLAUDE.md                 # プロジェクトの規約（Claudeが常時参照）

この構成をリポジトリに載せると、git clone した瞬間に、スキルもエージェントもフックもMCPも、そして規約もまるごと再現される。従来の「新マシンで一から作り直す」「Slackで設定を教え合う」が消える。設定変更は普通のコードと同じくPRで提案し、レビューを受け、履歴に残る。設定がドリフト（少しずつズレる）していく問題が、gitのdiffで可視化される。

詰まりやすいポイント

リポジトリ化には固有の落とし穴がいくつかある。順に潰しておく。

もう一点、フックのセキュリティにも触れておく。フックは任意のシェルコマンドを実行できる。つまり、他人のワークスペースをクローンして中身を確認せずに信頼すると、意図しないコマンドが走りうる。共有リポジトリのフックは、中身をレビューしてから使うのが鉄則だ。外部から取り込むスキルやサブエージェント、MCP設定も同様で、ワークスペースを「実行可能な設定」として扱う以上、コードと同じ警戒心でレビューする姿勢が要る。

スコープの混乱も定番の落とし穴だ。「なぜかチームメンバーの環境にサーバーが出ない」の多くは、local スコープ（自分専用・~/.claude.json）で追加してしまい、project スコープ（.mcp.json）に載せ忘れているのが原因だ。共有したいものは .mcp.json、個人のものは local、と最初に決めておけば迷わない。同じくフックも、チーム共通は settings.json、個人の実験は settings.local.json（gitignore対象）に分けるのが基本形になる。

導入の順序についても触れておく。いきなり6レイヤー全部をリポジトリ化しようとすると、たいてい息切れする。現実的なのは、まず CLAUDE.md とスキルを1〜2個コミットするところから始め、次に整形やテストの PostToolUse フックを足し、外部ツールへの依存が出てきた段階でMCPを project スコープに載せ、CIで回したくなったらワークフローYAMLとcanaryを追加する、という段階導入だ。各段で「本当にリポジトリ全員に配ってよいか」を確認しながら進めれば、シークレット混入や過剰な自動化を避けられる。ワークスペースの設計は、最初に完璧な構成を描くことより、変更をPRとして積み上げ、git log に設計判断の履歴を残していくことに価値がある。半年後に「なぜこのフックを入れたのか」を思い出せるのは、コミットメッセージに理由を書いた人だけだ。

まとめ

@granite0x氏の投げかけ——「Claude Codeを入れることは最小の作業で、本当のセットアップはCLIの外側にある」——を、6つのレイヤーに分解して見てきた。最後に、冒頭の3つの問いに答えて締めよう。

①この設計で何ができるのか。 スキルで手順と判断を、サブエージェントで副作業のコンテキストを外部化し、フックで「必ず守らせたいこと」を決定論的に保証し、MCPで外部ツールへ繋ぐ。それをワークフローYAMLでCIにも展開し、canaryで壊れを検知する。結果として、再現可能で、レビュー可能で、壊れたら気づけるAI開発環境が手に入る。

②何を解決するのか。 「毎回同じ指示を貼る」「マシンごとに設定がバラつく」「動いてたのに壊れた」という、Claude Code運用の三大ストレスを解消する。設定を個人の秘伝からチームの資産へ変える。

③従来の何を代替するのか。 ホームディレクトリに散らばったその場しのぎの設定、口頭やSlackでの共有、dotfilesの手動同期を代替する。git clone 一発で環境ごと再現し、git diff で設定変更を追える世界に移る。

Claude CodeのようなエージェントCLIは、effort の既定が高く設定されるなど、席を外しても作業を進める自律実行へと重心を移している。だからこそ、その足回りであるワークスペースをどう設計し、どうGitHubで管理するかが、これからの生産性を左右する。まずは既存の ~/.claude/ を眺め、スキル1つ・フック1つをリポジトリに切り出すところから始めてみてほしい。ループを設計する時代の、その土台の話である。関連して、エージェントを「回し続ける」設計そのものについては ループエンジニアリングとは も合わせて読むと立体的に見えてくる。

参照ソース

・元ツイート：Granite (@granite0x) — Build Your Opus 4.8 Workspace on GitHub（X Article、2026-07-09）
・Extend Claude with skills — Claude Code 公式ドキュメント（Anthropic）
・Create custom subagents — Claude Code 公式ドキュメント（Anthropic）
・Automate actions with hooks — Claude Code 公式ドキュメント（Anthropic）
・Connect Claude Code to tools via MCP — Claude Code 公式ドキュメント（Anthropic）
・Claude Code GitHub Actions — Claude Code 公式ドキュメント（Anthropic）
・anthropics/claude-code-action — GitHub（Anthropic）
・Introducing Claude Opus 4.8 — Anthropic（Anthropic）