CLIDevToolsClaude Code2026-02-21

Claude Code の設定ファイルをリポ間で共有しようとして、やめた話

きっかけ

Claude Code を複数のリポジトリで使っていると、同じスキルやルールを展開したくなる。/plan コマンド、コーディングスタイルのルール、サブエージェントの定義——どれも汎用的だ。

今までは Claude に「このリポのスキルを見て、あっちにも同じ手法で入れて」と頼んでいた。動くが、スケールしない。

共有の仕組みを考える前に、まず「何が共有可能で何がリポ固有か」を分析した。

スキルには「本質→方法論→実装手段→固有設定」の4層がある。たとえば未使用コード検出なら、「健全性を保つ」が本質、「CI で自動検出」が方法論、「knip」が今の実装手段、「ignore パターン」がリポ固有。持ち運びたいのは方法論の層で、実装手段はいつ入れ替わってもおかしくない。

そこで claude-toolkit という git リポに汎用的な資産を切り出した。他のプロジェクトはここから必要なものを取り込む。

.claude/ はプロジェクトレベルとグローバルレベル（~/.claude/）の2箇所に置ける。公式ドキュメントにも .claude/rules/ の symlink サポートが明記されている。

toolkit を ~/.claude/ に symlink すれば全プロジェクトで使えるのでは——と思ったが、ここで設定ファイルの種類をちゃんと理解しているか不安になった。

Claude Code にはスラッシュコマンドを定義する仕組みが .claude/commands/ と .claude/skills/ の2つある。自分のプロジェクトでは6個が Commands、2個が両方に存在、1個が Skills のみ。使い分けのルールがなかった。

公式ドキュメントを調べると Commands は非推奨で、Skills に統合済み だった。後方互換のために動くが、Skills のほうが model 指定やツール制限など機能が多い。Commands は Skills の機能制限版だった。

結果、4種類はこう整理できる。

脱線ついでにプロジェクト内の Commands を全部 Skills に移行した。commands/name.md を skills/name/SKILL.md に移動して frontmatter に name を追加するだけ。

本題に戻る。グローバルとプロジェクトに同名の設定がある場合の優先順位が、種類ごとに違う。

Rules と Agents は直感的だ。プロジェクト固有の設定がグローバルを上書きできる。

Skills だけ逆。 toolkit を ~/.claude/ に置くと、特定のプロジェクトだけ /plan の挙動をカスタマイズしたくても、できない。グローバルが常に勝つ。

Enterprise managed policy の設計思想で、上位スコープのポリシーを下位で上書きできないようにする仕様らしい。Agents は逆にプロジェクトのカスタマイズ優先。同じ .claude/ の中にあるのに解決ルールがバラバラ。

さらに、symlink そのものにも既知バグがあった。

どちらも 2026年2月時点で Open。

種類ごとに配布戦略を分ける案（Rules はグローバル、Skills は per-project、Agents もグローバル……）も考えたが、問題を解決するどころか新しい問題を作っている。

toolkit リポは汎用パターンの参照先として残し、junction による自動同期はやめた。

調べた結果だけでも役に立つと思うので置いておく。

Rules:   両方ロード。矛盾時は Project > Personal
Agents:  CLI > Project > Personal > Plugin
Skills:  Enterprise > Personal > Project > Plugin

Skills だけ逆。これを知っているだけで、「~/.claude/skills/ に置いたら上書きできない」というハマりを避けられる。

初出: Zenn