複数リポジトリでClaude Codeのルール・スキルを一元管理する

はじめに

Claude Code を複数のリポジトリで使っていると、同じルールやスキルを各リポジトリにコピーしたくなります。
ただ、この運用は長く続けると負担が増えていきます。

• 共通ルールを更新するたびに、各リポジトリを修正する必要がある
• どこまでが共通で、どこからがリポジトリ固有なのかが曖昧になる
• スキルや運用手順が少しずつズレていく

そこで今回は、「チーム共通のルール・スキルは1か所で管理し、リポジトリ固有の内容は各 CLAUDE.md に残す」という構成を紹介します。

実現方法はシンプルです。

• 共通ルール・スキルは専用リポジトリで管理する
• 各リポジトリからはシンボリックリンクで参照する
• Claude Code の SessionStart Hook で、起動時に共通リポジトリのローカル clone を更新する

検証環境は macOS / Linux です。Windows 環境では動作確認していません。

共通ルールを使って実際にどんなワークフローができるかは、Claude Code と GitHub Projects で、チーム開発のコンテキスト共有とタスク管理を自動化する を参照してください。

この記事の方針

この記事で分けたいのは、次の 2 種類です。

• チーム共通のルール・スキル: タスク管理、PR レビュー観点、コミットメッセージ規約
• リポジトリ固有のルール: 技術スタック、ディレクトリ構造、コーディング規約、固有ラベル

共通の運用知識は専用リポジトリにまとめ、各プロジェクトの CLAUDE.md から参照します。
Claude Code では CLAUDE.md が起動時に読み込まれ、さらに @path/to/file 形式で他ファイルを import できます。相対パス・絶対パスのどちらも使えます。

全体像

やっていることは 3 つです。

1. 共通ルール・スキルは専用リポジトリで管理する
2. 各リポジトリからはシンボリックリンクで参照する
3. SessionStart Hook で、Claude Code 起動時に共通リポジトリのローカル clone を更新する

なぜシンボリックリンクか

いくつかの方法を検討しました。

• コピー: 各リポジトリにファイルをコピーする。依存関係はないが、更新時は全リポジトリを修正する必要がある
• Git Submodule: 共通リポジトリを埋め込む。バージョン固定やディレクトリ構造の自由度は高いが、clone 時や更新時に専用コマンドが必要
• GitHub Actions: 共通リポジトリ更新時に各リポジトリへ PR を自動作成する。反映管理はしやすいが、構成がやや大掛かりになる
• シンボリックリンク: 共通リポジトリをローカルで参照する。設定が比較的シンプルで、ローカルの共通リポジトリが更新されれば参照先にもすぐ反映される。リンク自体は Git で追跡できる

Git Submodule には、バージョン固定や配置の自由度といった利点があります。
ただ、今回の用途では次のような条件がありました。

• 共通ルールは常に最新を使いたい
• 各リポジトリは同じ親ディレクトリ配下に置ける
• なるべくシンプルに運用したい

これらの条件を踏まえると、シンボリックリンクが最も扱いやすいと判断しました。

前提条件と制約

相対パスで共有する前提

シンボリックリンク自体は絶対パスでも作成できます。
ただし今回は、「開発者間で同じリンク設定を Git で共有しやすいよう、相対パスで作成する」という前提にしています。

そのため、各リポジトリと共通リポジトリは、同じ親ディレクトリ配下に配置する必要があります。

~/projects/                    ← 親ディレクトリ
├── shared-rules-repo/         ← 共通ルール管理
├── repo-web/                  ← Web フロントエンド
├── repo-mobile/               ← モバイルアプリ
└── repo-backend/              ← バックエンドAPI

この構成であれば、各リポジトリから共通リポジトリへの相対パスを固定できます。

他の開発者が使うときの前提

各リポジトリ側のリンク設定は Git で配布できますが、利用者のローカル環境にも、リンク先となる共通リポジトリが所定の位置に clone されている必要があります。

つまり、「1 人が設定してコミットすれば終わり」ではなく、以下のような役割分担になります。

• 各リポジトリ側の準備は代表者が用意できる
• 各利用者は、共通リポジトリを同じ相対位置に配置する

Step 1. 共通ルール用リポジトリを作る

まず、共通のルールやスキルを配置する専用リポジトリを作成します。

shared-rules-repo/
├── shared-claude-rules/
│   └── workflow-rules.md
└── shared-claude-skills/
    ├── deploy/
    │   └── SKILL.md
    ├── review/
    │   └── SKILL.md
    └── continue/
        └── SKILL.md

たとえば shared-claude-rules/workflow-rules.md に、チーム共通のタスク管理ルールを書きます。

# タスク管理（GitHub Projects カンバン）

## 作業フロー
1. 着手時: assignee を自分に設定し、ステータスを「In progress」に変更
2. 完了時: ステータスを「In review」に変更
3. 作業中: 進捗を Issue コメントに記録

## よく使うコマンド
- カンバン確認: `gh project item-list <PROJECT_NUMBER> --owner <ORG> --format json`
- ステータス変更: `gh project item-edit --project-id <ID> ...`

Step 2. 各リポジトリからシンボリックリンクで参照する

各開発リポジトリでは、共通リポジトリ内のファイルへシンボリックリンクを作成します。

cd repo-web

# ルール置き場を作成
mkdir -p .claude/rules

# 共通ルールへのシンボリックリンクを作成
ln -s ../../../shared-rules-repo/shared-claude-rules/workflow-rules.md \
      .claude/rules/workflow-rules.md

# スキルも同様
mkdir -p .claude/skills/deploy
ln -s ../../../../shared-rules-repo/shared-claude-skills/deploy/SKILL.md \
      .claude/skills/deploy/SKILL.md

# Git に追加
git add .claude/rules/ .claude/skills/
git commit -m "feat: 共通ルール・スキルへのシンボリックリンクを追加"

シンボリックリンクの確認

正しく設定できているかは ls -la で確認できます。

ls -la .claude/rules/
# lrwxr-xr-x  1 user  staff  ... workflow-rules.md -> ../../../shared-rules-repo/...

• 先頭が l で始まる行がシンボリックリンク
• -> の後ろにリンク先パスが表示される
• リンク先が存在しない場合は、環境によっては色や表示で判別できる

Step 3. CLAUDE.md から参照する共通ルール

.claude/rules/ には、チーム共通で使うルールを配置します。

CLAUDE.md では、必要な共通ルールを @path 構文で読み込みます。

## 共通ルール

@.claude/rules/session-start-rules.md
@.claude/rules/kanban-rules.md

## このリポジトリ固有の補足

- Issue を作成する場合、ラベルは `frontend` を付与する。

Step 4. SessionStart Hook で共通リポジトリを自動更新する

シンボリックリンクは、ローカルにある共通リポジトリを参照しているだけです。
そのため、共通リポジトリのリモート側が更新されても、手元の clone が古いままでは最新のルールは取り込まれません。

そこで、Claude Code の SessionStart Hook を使って、起動時に共通リポジトリを git fetch / git pull するようにします。

Claude Code の Hook は設定ファイルで管理できます。SessionStart はセッション開始時に実行され、startup / resume / clear / compact の matcher が使えます。また、SessionStart Hook の stdout は追加コンテキストとして Claude Code に渡されます。

設定ファイルの置き場所

Hook は以下のような設定ファイルで管理できます。チームで共有したい場合は .claude/settings.json、個人ごとに持ちたい場合は .claude/settings.local.json が適しています。

• ~/.claude/settings.json: ユーザー全体設定
• .claude/settings.json: プロジェクト設定
• .claude/settings.local.json: ローカル専用設定（通常はコミットしない）

Hook の設定

まずは一番シンプルな方法として、設定ファイルにインラインで記述する例を紹介します。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "(cd ../shared-rules-repo 2>/dev/null || { echo '⚠ shared-rules-repo が見つかりません'; exit 0; }; git fetch --quiet 2>/dev/null || { echo '⚠ fetch に失敗しました'; exit 0; }; LOCAL=$(git rev-parse HEAD); REMOTE=$(git rev-parse @{u} 2>/dev/null || echo ''); [ -z \"$REMOTE\" ] && { echo '⚠ upstream が設定されていません'; exit 0; }; [ \"$LOCAL\" = \"$REMOTE\" ] && { echo '✓ 共通ルールは最新です'; exit 0; }; git pull --ff-only --quiet 2>/dev/null && echo '✓ 共通ルールを更新しました' || echo '⚠ pull に失敗しました')"
          }
        ]
      }
    ]
  }
}

処理の流れは以下のとおりです。

Claude Code 起動
    ↓
SessionStart Hook 実行
    ↓
shared-rules-repo で git fetch
    ↓
ローカルと upstream を比較
    ↓
差分があれば git pull --ff-only
    ↓
結果を stdout に出力
    ↓
その内容がセッション開始時の追加コンテキストとして Claude Code に渡る

SessionStart Hook の stdout は、通常の会話本文ではなく、セッション開始時の追加コンテキストとして Claude Code に渡されます。成功時に「✓ 共通ルールを更新しました」のような短いメッセージを出力しておくと、Claude Code が現在の状態を把握しやすくなります。

Hook の動作確認

意図どおりに更新されるかは、共通リポジトリ側に差分を作って確認できます。

cd ../shared-rules-repo

# 最新を取得（pull はしない）
git fetch

# ローカルと upstream の差分を確認
git log HEAD..@{u} --oneline

ここでコミットが表示されれば、ローカルは未更新の状態です。

この状態で Claude Code を起動すると、Hook が git pull --ff-only を実行し、次回以降は最新の共通ルールを参照できるようになります。

なお、Hook 設定はセッション開始時に読み込まれます。設定ファイルを変更しても、その変更は現在のセッションには即時反映されません。動作を確認したいときは、新しいセッションを開始するのが確実です。

運用上の注意

オフライン時や upstream 未設定時は更新に失敗しますが、その場合でも既存のローカル内容を参照するため、作業自体は続けられます。
ただし、チームの最新ルールとズレる可能性があります。

共通リポジトリに未コミットの変更があると git pull --ff-only が失敗しやすいため、共通ルールは PR ベースで更新する運用が安全です。

Hook はローカルで任意のコマンドを実行できる仕組みなので、チームで共有する場合は内容をレビューし、設定変更も Git で追える形にしておくことをおすすめします。

誰が何をやるか

初回セットアップで代表者が用意できること

リポジトリ数が多い場合は、リンク作成や Hook 配置をスクリプト化しておくと楽です。

各利用者がやること

共通スキルも同じ考え方で配布できる

同じ構成で、チーム共通のスキル定義ファイルも共有できます。

shared-rules-repo/
└── shared-claude-skills/
    ├── deploy/SKILL.md
    ├── review/SKILL.md
    └── continue/SKILL.md

各リポジトリでは、必要なスキルだけシンボリックリンクを作成します。

mkdir -p .claude/skills/review
ln -s ../../../../shared-rules-repo/shared-claude-skills/review/SKILL.md \
      .claude/skills/review/SKILL.md

その上で、必要に応じて CLAUDE.md から参照する構成にしておくと、どの知識を使わせたいかが整理しやすくなります。

どんなルールを共有するとよいか

判断基準はシンプルです。「どのリポジトリでも同じかどうか」で決めます。

たとえば、技術スタックやディレクトリ構造、命名規則などはプロジェクトごとに異なりやすいので、各 CLAUDE.md に残した方が自然です。
一方で、タスク管理やレビュー観点のようなチーム全体の運用知識は、共有リポジトリで一元管理すると効果が出やすくなります。

まとめ

複数リポジトリで Claude Code を運用するなら、以下の構成がおすすめです。

• チーム共通のルール・スキルは専用リポジトリで管理する
• 各リポジトリ固有の文脈は CLAUDE.md に残す
• シンボリックリンクで参照し、SessionStart Hook でローカル clone を同期する

この構成にすれば、更新コストを抑えながら、共通運用と個別文脈を分離できます。

派手な仕組みではありませんが、以下の点でチーム運用にはちょうどよいバランスだと感じています。

• Git で追える
• 仕組みが理解しやすい
• 複数リポジトリへ横展開しやすい

参考

• Claude Code と GitHub Projects で、チーム開発のコンテキスト共有とタスク管理を自動化する
• Claude Code Hooks
• Claude Code Memory