new-workspace

新しい Git ワークスペースの作成

作業を始める前に — 必須

1. 現在のスコープを確認する：git rev-parse --git-common-dir と --show-toplevel を実行して、どのリポジトリを操作しているかを確認します。プロジェクト管理ルートを持つレイアウトでは、対象がルートリポジトリ、code/、paper/ のどれかを特定します。
2. memory/BRIEFING.md が存在する場合は、プロジェクトメモリを読む：
   • memory/BRIEFING.md — 現在のフェーズとアクティブなワークツリー
   • memory/project-conventions.md — このプロジェクトのワークツリー命名ポリシーとパス規約
3. 名前の衝突や孤立したワークツリーを避けるため、新規作成の前に git worktree list で既存のワークツリーを確認する。

手順 2 を省略すると、ワークツリーの配置先を誤ったり、既存のブランチやワークツリーのポリシーと競合する名前を使ったりするリスクがあります。

---

プロジェクト全体の管理とコンポーネントリポジトリの管理を混同せずに、ブランチまたは Git ワークツリーを作成します。

次の用途でこのスキルを使用します。

• コード、実験、ベースライン、機能、デバッグ、または反論実装用のブランチ
• NeurIPS、ICML、ICLR、CVPR、ACL、EMNLP などの投稿用の論文会議ブランチ
• arXiv 論文の公開
• カメラレディ版の論文

研究プロジェクト全体を扱う場合、コードのワークツリーは <ProjectName>/code-worktrees/ に、論文のワークツリーは <ProjectName>/paper-worktrees/ に配置します。

このスキルは次のスキルと組み合わせて使用します。

• 複雑な Git の状態、競合、またはサンドボックスへの書き込み失敗には safe-git-ops
• ワークツリーの目的と終了条件の記録には research-project-memory
• コードのワークツリーを SSH/HPC サーバーで使用する場合は remote-project-control
• 新しいワークスペースですぐにジョブを起動する場合は run-experiment
• 論文のワークツリーが投稿、arXiv、またはカメラレディ版用の場合は submit-paper
• 論文のワークツリーが採択版用の場合は camera-ready-finalizer

基本原則

• プロジェクト全体のルートではなく、コンポーネントリポジトリのワークツリーを作成します。
• コードのワークツリーは、<ProjectName>/code-worktrees/ 配下に兄弟ディレクトリとして作成することを推奨します。
• 論文のワークツリーは、<ProjectName>/paper-worktrees/ 配下に兄弟ディレクトリとして作成することを推奨します。
• ユーザーが明示的にそのレイアウトを求めない限り、code/ または paper/ 内にワークツリーをネストしないでください。
• すべての研究ワークツリーには、目的、関連する主張／リスク／実験、終了条件を設定します。
• 論文のワークツリーには、投稿先の会議／バージョン、投稿モード、テンプレート／スタイルの違い、クリーンアップ要件、ソースの公開範囲に関する前提も記録します。
• 論文ソースの公開範囲は投稿先とは独立しています。論文のワークツリーには、agent-private、author-visible、anonymous-submission、public-preprint、camera-ready-public、publisher-artifact を指定できます。
• experiments/ には実行可能なロジックを配置します。安定した結果の要約は docs/results/、レポートは docs/reports/、実行への参照は docs/runs/ に配置します。
• コードのワークツリーでは uv sync の後に専用の .venv/ を作成します。論文のワークツリーでは、デフォルトでローカルの TeX インストールは不要です。Overleaf/GitHub でのコンパイルを信頼できる唯一の情報源とする場合があります。

Step 1 - 対象を分類する

ユーザーに次の情報を尋ねます。

• ワークスペースの種類：branch または worktree
• コンポーネント：code または paper
• ブランチの種類：
  • コード：feature、exp、baseline、debug、rebuttal、または任意の種類
  • 論文：venue、submission、arxiv、camera-ready、rebuttal、paper-fix、または任意の種類
• 接頭辞を除いたブランチ名
• 対象リポジトリのパス（明らかでない場合）
• 論文のワークスペースの場合：ソース公開範囲の階層、読者、同期先、クリーンアップの条件
• ワークツリーメモリを記録するかどうか

<ProjectName>/ 内で作業する場合、実験、ベースライン、デバッグ、反論実装の作業には code/ リポジトリを優先します。 投稿先の変更、arXiv での公開、カメラレディ版の作成、ソースのクリーンアップ、論文のみの反論修正、または投稿形式への整形には、paper/ リポジトリを優先します。

<ProjectName>/code/ 内で作業する場合は、次のように推定します。

code repo root:      <ProjectName>/code/
project control root: <ProjectName>/
worktree root:      <ProjectName>/code-worktrees/

<ProjectName>/paper/ 内で作業する場合は、次のように推定します。

paper repo root:      <ProjectName>/paper/
project control root: <ProjectName>/
worktree root:        <ProjectName>/paper-worktrees/

単独のコードリポジトリ内で作業する場合は、フォールバックのワークツリールートを使用します。

<code-repo-parent>/worktrees/

単独の論文リポジトリ内で作業する場合は、フォールバックのワークツリールートを使用します。

<paper-repo-parent>/paper-worktrees/

ステップ 2 - Git の状態を確認する

対象のリポジトリで：

git -C <repo-root> rev-parse --show-toplevel
git -C <repo-root> status --short
git -C <repo-root> branch --show-current
git -C <repo-root> worktree list

コミットされていない変更がある場合は、コミットするか、スタッシュするか、ブランチのみで続行するか、キャンセルするかを確認します。

ステップ 3 - ブランチ名を選択する

次を使用します：

<branch-type>/<branch-name>

例：

• exp/new-loss
• baseline/fair-tuning
• debug/nan-loss
• rebuttal/add-ablation
• feature/data-loader
• venue/neurips
• venue/icml
• arxiv/v1
• camera-ready/neurips
• private/draft
• overleaf/main-clean

ワークツリーのディレクトリ名は、ファイルシステムで扱いやすいものにします：

<branch-type>-<branch-name-with-slashes-replaced-by-hyphens>

ステップ 4 - ブランチを作成する

ブランチのみで作業する場合：

git -C <repo-root> checkout -b <branch-type>/<branch-name>

その後、ブランチに研究目的がある場合は、コンポーネントのメモリーを更新します。

ステップ 5 - ワークツリーを作成する

ワークツリーのルートを決定します：

コードの場合：

1. <repo-root> が <ProjectName>/code/ の場合は、<ProjectName>/code-worktrees/ を使用します。
2. <repo-root>/../code-worktrees/ が存在する場合は、それを使用します。
3. プロジェクトのメモリーでコード用ワークツリーのルートが指定されている場合は、それを使用します。
4. それ以外の場合は、<repo-root>/../worktrees/ を使用します。

論文の場合：

1. <repo-root> が <ProjectName>/paper/ の場合は、<ProjectName>/paper-worktrees/ を使用します。
2. <repo-root>/../paper-worktrees/ が存在する場合は、それを使用します。
3. プロジェクトのメモリーで論文用ワークツリーのルートが指定されている場合は、それを使用します。
4. それ以外の場合は、<repo-root>/../paper-worktrees/ を使用します。

ワークツリーを作成します：

mkdir -p <worktree-root>
git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> -b <branch-type>/<branch-name>

ブランチがすでに存在する場合は、既存のブランチからワークツリーを作成するか確認します：

git -C <repo-root> worktree add <worktree-root>/<worktree-dir-name> <branch-type>/<branch-name>

ステップ 6 - ローカルのツール類をコピーし、共有アセットをリンクする

存在する場合は、IDE やツール類のローカルディレクトリをコピーします：

.vscode/
.cursor/
.claude/

各ワークツリーで個別の IDE 状態が必要になる場合があるため、シンボリックリンクではなくコピーしてください。

<repo-root>/.worktree-links が存在する場合は、そこから相対パスを読み取り、共有の大容量アセットをワークツリー内にシンボリックリンクします。一般的なエントリは次のとおりです：

data/
models/
.env
configs/local_settings.yaml

ワークツリーのパスからリンクが有効なままになるよう、絶対パスをシンボリックリンクのターゲットに使用します。

ステップ 7 - コンポーネント固有のパスを準備する

コード用ワークツリー

ワークツリー内で、次を確認します：

docs/results/
docs/reports/
docs/runs/
.agent/

ブランチ固有のエビデンスには、次のパスを使用します：

• docs/results/：安定した結果の要約、表の注記、図の注記
• docs/reports/：実験レポートと結果の説明
• docs/runs/：ジョブ ID、設定ファイルのパス、コミットハッシュ、リモートパス、簡潔な指標
• .agent/worktree-status.md：目的、関連する主張やリスク、最新の信頼できる状態、終了条件

生ログ、チェックポイント、wandb の実行データ、tensorboard のキャッシュ、大容量の出力は docs/ に保存しないでください。

論文用ワークツリー

論文用ワークツリーでは、次の項目を確認してください。

.agent/

論文バージョン用のフィールドを含む .agent/worktree-status.md を作成または更新してください。

• 対象の会議または公開先：NeurIPS、ICML、ICLR、CVPR、ACL、EMNLP、arXiv、カメラレディ
• 投稿モード：匿名投稿、プレプリント、カメラレディ、反論、または内部用
• メイン論文とのスタイルやテンプレートの違い
• ソースの公開範囲：
  • agent-private：.agent/、AGENTS.md、CLAUDE.md、執筆メモ、出典情報メモ、内部向け結果ドキュメント、CSV、プロット用スクリプトを含められます。Overleaf や公開リモートには同期しないでください
  • author-visible：共著者や Overleaf から閲覧可能です。.agent/、AGENTS.md、CLAUDE.md、生の CSV、内部向けドキュメント、プロット用スクリプト、査読者対応の戦略、非公開パスを除外する必要があります
  • anonymous-submission：会議やソースのアップロード先から閲覧可能です。匿名性を確保し、エージェント用および非公開ファイルを除外する必要があります
  • public-preprint：arXiv や一般公開向けのソースです。公開可能な状態にする必要があります
  • camera-ready-public：採択後の最終的な公開用または出版社向けソースです。匿名性を解除し、公開可能な状態にする必要があります
  • publisher-artifact：最終的な公開用ソースに、成果物やリリース向けのファイルのみを加えたものです
• 対象読者と同期先：なし、Overleaf-GitHub、GitHub、投稿システム、arXiv、出版社、または成果物
• 許可するパスと禁止するパス
• クリーンアップのタイミング：push 前、投稿前、arXiv 公開前、カメラレディ提出前、またはリリース前
• クリーンアップ要件：
  • arXiv／公開用ソース：TODO、著者コメント、査読メモ、TeX コメント内の内部向け図表の説明、非表示のメモ、匿名化の残りを削除します
  • 著者向け／Overleaf：.agent/、AGENTS.md、CLAUDE.md、生の CSV、内部向け結果ドキュメント、プロット用スクリプト、非公開パス、エージェント専用のメモを削除するか、含めないようにします
  • 会議への匿名投稿：匿名性と会議の書式を守ります。ソースがアップロードされる場合、ソース内のコメントもリスクになり得るため、それに頼らないでください
  • カメラレディ：匿名性を解除し、謝辞や研究助成情報を追加し、反論での約束事項を完了し、ドラフト専用のメモを削除します
• ソース形式の確認：tex-fmt がインストールされている場合は tex-fmt --check --nowrap --recursive . を実行します。ユーザーから依頼された場合、またはプロジェクトのポリシーで必要な場合に限り、tex-fmt --nowrap --recursive . でフォーマットします
• 使用する場合は、Overleaf／GitHub のコンパイル状況とブランチの対応関係

ユーザーが論文内のメモを明示的に希望しない限り、コード用ワークツリーの docs/results/、docs/reports/、docs/runs/ の運用規則を論文用ワークツリーに持ち込まないでください。論文バージョンごとのメモには .agent/ を、バージョンをまたいで保持する情報にはルートの memory/ を使用してください。

ステップ 8 - 環境の同期

コード用ワークツリーに pyproject.toml がある場合は、次を実行します。

cd <worktree-path>
uv sync

uv sync が失敗した場合はエラーを報告しますが、ワークツリーは削除しないでください。ユーザーがブランチを確認したり修正したりする可能性があります。

論文用ワークツリーでは、デフォルトで TeX をインストールしないでください。ユーザーがローカルでの TeX 使用を明示的に希望しない限り、プロジェクトのコンパイル手順に従い、ローカルでの静的チェック、利用可能な場合は tex-fmt、GitHub にリンクされた Overleaf を使用してください。

ステップ 9 - ワークツリーのメモリを記録する

ワークスペースに調査目的がある場合は、次を作成または更新します。

<worktree>/.agent/worktree-status.md

次の項目を含めます。

• ブランチ
• パス
• 作成日
• 親ブランチ
• 目的
• 関連する主張、実験、リスク、またはレビュアーの指摘
• main ブランチとの差分として想定される内容
• 論文用ワークツリーの場合：投稿先の会議／バージョン、テンプレート／スタイルの違い、ソースの整理方針、公開／非公開ソースに関する前提
• 論文用ワークツリーの場合：ソースの公開範囲、対象読者、同期先、許可／禁止ファイルの方針、クリーンアップの条件
• 結果／出力のパス
• 終了条件：マージ、継続、保留、または破棄
• 次の検証手順

プロジェクトメモリがある場合は、次への短い参照も追加します。

• memory/component-index.yaml：既知のワークツリーパス
• <component>/.agent/worktree-index.md：コンポーネント内のアクティブなワークツリーの一覧
• memory/source-visibility-board.md：論文用ワークツリーまたは公開ブランチのソース公開範囲とクリーンアップの条件
• memory/action-board.md：ワークツリーの次のアクション
• memory/current-status.md：このワークツリーが現在の作業対象である場合のみ
• memory/project-conventions.md：このワークツリーで、今後のエージェントが把握しておくべき新しい命名規則、ブランチポリシー、またはワークツリー範囲のルールを導入する場合は、worktree カテゴリに追加します

ルートレジストリとコンポーネントのワークツリーインデックスは、複数のワークツリーにまたがるメモリの保存先です。他の兄弟ブランチや論文バージョンの存在を今後のエージェントに伝えるために、1 つのワークツリー内のリーフステータスファイルだけに頼らないでください。

ステップ 10 - 最終サマリー

次の内容を報告します。

Workspace created

Repo: <repo-root>
Branch: <branch-type>/<branch-name>
Worktree: <path or branch-only>
Evidence paths:
  <code worktree only: docs/results/, docs/reports/, docs/runs/>
Memory:
  .agent/worktree-status.md <created|skipped>

Next:
  cd <worktree-path>
  <code: uv sync and run/edit the planned experiment>
  <paper: run submit-paper checks and sync to Overleaf/GitHub if needed>

エラー処理

• Git リポジトリではない場合：停止して、対象のリポジトリを確認します。
• 作業ツリーに未コミットの変更がある場合：コミット、スタッシュ、続行、キャンセルのいずれにするかを確認します。
• ブランチが存在する場合：既存のブランチを使うか、新しい名前を選ぶかを確認します。
• ワークツリーのパスが存在する場合：新しい名前を選ぶか、既存のパスを調べるかを確認します。
• サンドボックスで Git メタデータへの書き込みがブロックされた場合：権限の問題として扱い、safe-git-ops を使用します。
• UV の同期に失敗した場合：ワークツリーを保持し、環境の問題を報告します。
• ローカルで論文をコンパイルできない場合：デフォルトでは TeX をインストールせず、Overleaf／GitHub を使用します。

設定ファイルのテンプレート

.worktree-links が存在しない場合は、次の作成を提案します。

# .worktree-links
#
# Symlinks to create in new worktrees.
# List paths relative to the code repo root.

# data/
# models/
# .env
# configs/local_settings.yaml

最終確認

• ブランチまたはワークツリーが、意図したコンポーネントリポジトリに作成されている
• 明示的に依頼された場合を除き、ワークツリーが code/ または paper/ の内部にネストされていない
• git worktree list に想定したパスが表示される
• コード用ワークツリーでは、コードの根拠となるパスが存在する
• 論文用ワークツリーでは、論文のバージョン方針が記録されている
• 論文用ワークツリーでは、特に Overleaf／共著者から見えるブランチや公開ソースのブランチについて、論文ソースの公開方針が記録されている
• 関連する場合、ワークツリーのメモリに目的と終了条件が記録されている
• プロジェクトメモリには、ログではなく、長期的に役立つ参照のみが更新されている