mcpField
W
worktrees

worktrees

github.com/jayden-dang開発146 回インストール1 日前に更新
リポジトリ

worktrees について

worktreesは、機能開発を独立したGit worktreeで行い、変更前に開始時の状態を確認するエージェントスキルです。既存の隔離環境を検出し、ハーネス標準のワークスペースツールを優先しつつ、依存関係の導入とベースラインテストを含むGit手順を示します。

主な機能

  1. 01既存worktreeの隔離を検出
  2. 02標準ワークスペースツールを優先
  3. 03Git worktreeの代替手順
  4. 04プロジェクトファイルから依存関係を導入
  5. 05作業前にベースラインテストを実行

活用シーン

  1. 01機能ブランチを現在のチェックアウトから隔離
  2. 02実装前のワークスペース準備
  3. 03変更前に既存テストの状態を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/jayden-dang/skills --skill worktrees

インストール後、Claude Code で/worktreesを入力して読み込まれたか確認します。

詳細

ワークツリー

検証済みのクリーンな状態から始められる、機能開発用の隔離されたワークスペースを用意します。優先順位は、既存の隔離環境を検出する → ハーネス標準のワークスペースツールを使う → 手動で git worktree にフォールバックする、の順です。ハーネスの動作を妨げないでください。

ステップ 0 — 検出して同意を得る

すでにリンクされたワークツリー内にいるか確認します。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
  • GIT_DIR != GIT_COMMON → リンクされたワークツリーの可能性があります。ただし、先にサブモジュールでないことを確認してください。git rev-parse --show-superproject-working-tree がパスを出力する場合、サブモジュール内にいます。通常のチェックアウトとして扱ってください。そうでなければ、すでに隔離されています。パスとブランチを報告し、作成をスキップしてステップ 2 に進みます。
  • GIT_DIR == GIT_COMMON → 通常のチェックアウトです。ユーザーがワークツリーに関する希望を明示している場合は、何も聞かずにその希望に従います。そうでない場合は、「現在のブランチに手を加えずに済むよう、隔離されたワークツリーで作業を始めましょうか？」と尋ねます。断られた場合は、現在の場所で作業し、ステップ 2 に進みます。

完了条件：3 つのケースのどれに該当するか把握し、作成する場合は同意を得ていること。

ステップ 1 — ワークスペースを作成する

1a. まず標準ツールを使う。 ハーネスにワークスペース／ワークツリーの仕組み（EnterWorktree のような名前のツール、/worktree コマンド、--worktree フラグ）がある場合は、それを使ってステップ 2 に進みます。標準ツールは配置、ブランチ、クリーンアップを自ら管理します。その横に手動のワークツリーを作ると、ハーネスから認識できない不整合な状態が残ります。標準ツールがない場合に限り、次の方法に進んでください。

1b. Git にフォールバックする。 次の優先順位でディレクトリを選びます。

  1. ユーザーによる明示的な指示 — 常に最優先
  2. リポジトリのルートにある既存の .worktrees/
  3. 既存の worktrees/（両方ある場合は .worktrees/ を優先）
  4. どちらもない場合 → .worktrees/ を作成

選んだディレクトリを $DIR に割り当て、以下のすべてのコマンドで使用します。上記の優先順位が実際に意味を持つのは、コマンドがそれに従う場合だけです。

DIR=.worktrees   # or DIR=worktrees if that existing dir was selected above

プロジェクト内のディレクトリに何かを作成する前に、必ず Git の無視対象であることを確認してください。エントリは未コミットの作業ツリーの変更として残します。Git はすぐにその設定を反映します。ここで .gitignore をコミットすると、ユーザーの現在のブランチにコミットが作成されます。このスキルが変更しないと約束している、まさにその対象です。

git check-ignore -q "$DIR" || printf '%s/\n' "$DIR" >> .gitignore

次に作成して移動します。

git worktree add "$DIR/<branch-name>" -b "<branch-name>"

サンドボックスまたは権限エラーで作成に失敗した場合は、ユーザーに伝えて、現在の場所で作業してください。

完了条件：ワークスペース内にいること（または、そうできなかった理由を報告していること）。

ステップ 2 — 依存関係をインストールする

ロックファイル／マニフェストからパッケージマネージャーを自動判定して、インストールを実行します。pnpm-lock.yaml → pnpm、bun.lock* → bun、yarn.lock → yarn、package-lock.json／単独の package.json → npm、Cargo.toml → cargo build、uv.lock → uv、poetry.lock → poetry、requirements.txt → pip、go.mod → go mod download。マニフェストがない場合はスキップします。

ステップ 3 — クリーンなベースライン

docs/agents/project.md に記載されたコマンドでテストスイートを実行します（ファイルがない場合はその旨を伝え、setup-repo を提案して、各エコシステムのデフォルトのテストランナーを使用します）。

  • ベースラインが成功 → 続行します。
  • ベースラインが失敗 → 停止し、続行する前にユーザーに確認します。失敗しているベースラインから始めると、自分のバグと既存の問題を区別できません。

報告

Workspace ready at <absolute path> (branch <name>)
Baseline: <N> tests passing, 0 failures
Ready to start <task>.

警告 — 絶対にしないこと

  • ステップ 0 ですでにワークツリー内にいると判明した場合に、ワークツリーを作成する
  • 標準ツールがある場合に、git worktree add を使う
  • 無視対象であることを確認せずに、プロジェクト内のワークツリーディレクトリを作成する
  • ベースラインテストを省略する、または失敗したベースラインについてユーザーに確認せずに続行する

コメント

Markdown 対応