dot-claude-syncでClaudeで作ったドキュメントをworktree間共有しよう

dot-claude-syncについて

TL;DR

• .claudeディレクトリを複数のプロジェクト/worktree間で同期するGo製CLIツール
• グループ管理と優先度システムで柔軟な同期戦略を実現
• git worktree環境でのClaude Code活用を劇的に改善

はじめに

まず僕のやり方として、タスクを行う時にClaude Codeには調査やTODOを作らせてから、それらを確認・レビューをしコードを書いてもらいます。
その際、書いてもらったものを別のエディターを開いて見たくないので、そのドキュメントの場所はプロジェクトの中に作って欲しいのです。

しかし、毎回Gitの差分として出てしまい、global ignoreに入れるのも手間がかかります。
ルートに置くとClaudeが認知できるため、余計なプロンプトが混じる恐れもあります。
そこで、Claudeが自動で読み取らないフォルダである.claudeに目をつけました。

.claudeにドキュメントを配置すれば、管理しやすいのではないかと考え運用してみると、悪くなかったので使っていました。
例えば、ダッシュボードの修正タスクなどがあった場合は、.claude/custom-documentsというフォルダの中にdashboard-fix-XXXといったようなフォルダを作り、そこにタスクの内容を集約させるというものです。

そして同時に、Claude Codeを使っていると、.claudeディレクトリに便利なプロンプトやスキル、プロジェクトのコンテキストを保存することが多くなります。

しかし、git worktreeで複数ブランチを同時に開発していると、.claudeはgitignoreされているため、各worktree間で同期されません。

dot-claude-syncは、この問題を解決するために開発したツールです。

背景と課題

Claude Codeでの.claude活用

Claude Codeを使った開発では、以下のような情報を.claudeディレクトリにドキュメントとして保存すると便利です：

• 個人タスク固有のプロンプト
• よく使うスキルやコマンド
• 実装仕様書やTODOリスト
• プロジェクトのコンテキスト情報

これらはgitで管理しない（gitignore）ことで、リポジトリを汚さずにClaude専用の長期コンテキストとして活用できます。

もちろん、チームと連携し共有することもできますが、個人によってドキュメントの完成度はバラバラになったり増え続ける一方で整理されないと余計なコンテキストの紛れ込みの原因になります。

そこで、個人のものは個人で管理し、skillsなどで共有したいものはPlugin化してマーケットプレイスで共有することで綺麗に共有できます。

git worktreeでの課題

git worktreeを活用した開発フローでは問題が発生します：

my-project/
├── main/           # メインworktree
│   └── .claude/
│       └── prompts/useful-prompt.md
├── feature-a/      # feature-a worktree
│   └── .claude/    # 空っぽ！
└── feature-b/      # feature-b worktree
    └── .claude/    # 空っぽ！

• 作成時点では同期されていたとしても、使っていくうちにworktree間で.claudeの内容が共有されない
• 各worktreeで個別に設定が必要
• 便利なプロンプトを都度コピーする手間

dot-claude-syncの解決策

dot-claude-syncは「グループ」という概念でプロジェクトをまとめ、優先度システムで同期戦略を制御します。

基本的な使い方

1. インストール

Go install:

go install github.com/yugo-ibuki/dot-claude-sync@latest

短縮エイリアス版（dcsコマンド）もインストール可能:

go install github.com/yugo-ibuki/dot-claude-sync/cmd/dcs@latest

インストール後、dot-claude-syncコマンド（またはdcs）が使えるようになります。

$GOPATH/bin（通常は~/go/bin）にパスが通っている必要があります。

ソースからビルド:

git clone https://github.com/yugo-ibuki/dot-claude-sync.git
cd dot-claude-sync
go build                    # dot-claude-syncバイナリを生成
go build -o dcs ./cmd/dcs   # dcsエイリアスバイナリを生成

2. 初期設定（対話式）

dot-claude-sync init
# または短縮版
dcs init

このコマンドを実行すると、対話形式で初期設定を行います：

1. グループ名の入力: プロジェクトグループの名前を決めます（例: my-app, web-projects）
2. プロジェクトパスの入力: 同期したい.claudeディレクトリのパスを入力
   • 複数のパスを入力可能（空行で終了）
   • ~を使った相対パス指定も可能
3. 設定ファイルの自動作成: ~/.config/dot-claude-sync/config.yamlが作成されます

実行例:

$ dot-claude-sync init
グループ名を入力してください: my-app
プロジェクトパスを入力してください（空行で終了）:
Path 1: ~/projects/my-app/main/.claude
Path 2: ~/projects/my-app/feature-a/.claude
Path 3: ~/projects/my-app/feature-b/.claude
Path 4: [Enter]

設定ファイルを作成しました: ~/.config/dot-claude-sync/config.yaml

3. worktreeの自動検出（オプション）

手動でパスを入力する代わりに、detectコマンドでworktreeを自動検出できます：

dot-claude-sync detect ~/projects/my-app --group my-app
# または
dcs detect ~/projects/my-app --group my-app

このコマンドは：

• git worktree listを実行してworktreeを検出
• 各worktreeに.claudeディレクトリが存在するか確認
• 存在する場合、自動的に設定ファイルに追加

4. 設定の確認

dot-claude-sync list
# または
dcs list

現在の設定を確認できます。グループ名とその中のプロジェクトパスが表示されます。

5. 同期実行

dot-claude-sync push my-app
# または
dcs push my-app

指定したグループ内の全プロジェクトで.claudeディレクトリを同期します。

安全な実行（dry-runモード）:

dot-claude-sync push my-app --dry-run
# または
dcs push my-app --dry-run

実際にファイルをコピーせず、何が行われるかをプレビューできます。初回実行時は--dry-runでの確認を推奨します。

設定ファイルの例

~/.config/dot-claude-sync/config.yaml:

groups:
  my-app:
    paths:
      main: ~/projects/my-app/main/.claude
      feature-a: ~/projects/my-app/feature-a/.claude
      feature-b: ~/projects/my-app/feature-b/.claude
    priority:
      - main  # mainを最優先（マスター設定）

この設定でdot-claude-sync push my-appを実行すると：

1. 全プロジェクトから.claudeディレクトリのファイルを収集
2. ファイル名が重複する場合は、優先度の高いプロジェクト（main）のファイルを採用
3. 収集したファイルを全プロジェクトに配布

主要機能

🔍 detect - worktree自動検出

dot-claude-sync detect ~/projects/my-app --group my-app
# または
dcs detect ~/projects/my-app --group my-app

git worktreeを使っている環境で、複数のworktreeの.claudeディレクトリを一括で設定ファイルに追加できる機能です。

何をするか：

1. 指定されたディレクトリでgit worktree listを実行
2. 検出された各worktreeのパスに.claudeディレクトリが存在するか確認
3. 存在する場合、設定ファイル（~/.config/dot-claude-sync/config.yaml）に自動追加
4. worktreeのブランチ名をエイリアスとして使用（例: main, feature-a）

メリット：

• 手動で各worktreeのパスを入力する手間が不要
• worktreeの構成変更（追加・削除）に素早く対応できる
• タイポやパス間違いのリスクを削減

実行例：

# ~/projects/my-appにあるworktreeを検出してmy-appグループに追加
dcs detect ~/projects/my-app --group my-app

# 実行後、config.yamlは以下のように自動更新される
# groups:
#   my-app:
#     paths:
#       main: ~/projects/my-app/main/.claude
#       feature-a: ~/projects/my-app/feature-a/.claude
#       feature-b: ~/projects/my-app/feature-b/.claude

ユースケース：

• 新しいプロジェクトでworktree環境のセットアップを素早く完了したい
• 既存プロジェクトに新しいworktreeを追加した際の設定更新
• チームメンバーが同じworktree構成を簡単に再現したい場合

📤 push - 同期実行

dcs push my-app

グループ内の全プロジェクトから.claudeファイルを収集し、優先度に基づいて配布します。

💾 backup - バックアップ作成

dcs backup my-app

グループ内の全プロジェクトの.claudeディレクトリをタイムスタンプ付きでバックアップします。
バックアップは~/.local/share/dot-claude-sync/backups/に保存されます。

ユースケース：

• 初回同期前の安全確保
• 大規模な変更を行う前の保護
• 定期的なバックアップ運用

🗑️ rm - 一括削除

dcs rm my-app prompts/old-prompt.md

グループ内の全プロジェクトから指定ファイルを削除します。

📝 mv - 一括リネーム

dcs mv my-app old-name.md new-name.md

グループ内の全プロジェクトでファイルをリネーム/移動します。

⚙️ config - 設定管理

# グループ追加
dcs config add-group new-group

# プロジェクト追加
dcs config add-project my-app feature-c ~/projects/my-app/feature-c/.claude

# 優先度設定
dcs config set-priority my-app main feature-a feature-b feature-c

コマンドラインから設定ファイルを直接編集できます。

コマンドエイリアス

dot-claude-syncとdcsは完全に同じ機能を提供します。すべてのコマンドで両方のエイリアスが使用可能です：

# これらは全く同じ動作をします
dot-claude-sync init
dcs init

dot-claude-sync push my-app
dcs push my-app

dot-claude-sync list
dcs list

dcsは短く入力しやすいため、日常的な使用に推奨します。

ユースケース

ケース1: worktree環境の即座のセットアップ

# worktreeプロジェクトの.claudeディレクトリを自動検出・追加
dcs detect ~/projects/my-app --group my-app

# バックアップを作成（安全のため）
dcs backup my-app

# すぐに同期開始
dcs push my-app

ケース2: 共通設定の配布

groups:
  web-projects:
    paths:
      shared: ~/projects/shared-config/.claude  # 共通設定マスター
      frontend: ~/projects/frontend/.claude
      backend: ~/projects/backend/.claude
    priority:
      - shared  # shared が最優先

# shared プロジェクトの設定を全プロジェクトに配布
dcs push web-projects

ケース3: クライアントプロジェクトのテンプレート管理

groups:
  clients:
    paths:
      template: ~/templates/client/.claude
      client-a: ~/clients/a/.claude
      client-b: ~/clients/b/.claude
    priority:
      - template

テンプレートプロジェクトの設定を各クライアントプロジェクトに展開できます。

グローバルオプション

すべてのコマンドで以下のオプションが使用できます：

--config <path>   # 設定ファイルのパスを指定
--dry-run         # 実行内容をプレビュー（実際の変更なし）
--verbose         # 詳細なログを出力
--force           # 確認プロンプトをスキップ

使用例：

# dry-runで安全確認
dcs push my-app --dry-run

# 詳細ログ付きで実行
dcs push my-app --verbose

# カスタム設定ファイルを使用
dcs push my-app --config ~/custom-config.yaml

まとめ

dot-claude-syncは、git worktree環境でのClaude Code活用を改善する小さなツールです。

こんな人におすすめ：

• git worktreeを活用している
• 複数プロジェクトで共通の.claude設定を使いたい
• プロンプトやスキルの管理を効率化したい

興味を持っていただけた方は、ぜひ試してみてください！

リンク

• GitHub: https://github.com/yugo-ibuki/dot-claude-sync
• インストール:
  • メイン: go install github.com/yugo-ibuki/dot-claude-sync@latest
  • エイリアス: go install github.com/yugo-ibuki/dot-claude-sync/cmd/dcs@latest