プロジェクトリソース

プロジェクトのリソースは、この一連の作業がどのコードを使い、どこで実行するかをエージェントに伝えます。リソースはプロジェクトに紐づいたまま保たれるため、リポジトリの URL やローカルパスをタスクごとに貼り直す必要はありません。

現在サポートされているリソースは 2 種類です。

リソースが実行に入る仕組み

エージェントがプロジェクト内のタスクを処理するとき、Multica はプロジェクト名、プロジェクトの説明、リソース一覧を実行コンテキストに追加し、作業ディレクトリに .multica/project/resources.json を書き込みます。

ワークスペースに紐づくリポジトリ一覧は、常に実行コンテキストに含まれます。プロジェクトに紐づくリポジトリは、それに加えて、この一連の作業で使うコードとデフォルトの ref を指定します。

ローカルディレクトリは、それを紐づけたデーモンに対してのみ有効です。実行を担当するデーモンに一致するローカルディレクトリがある場合、エージェントはそのディレクトリに直接入って作業します。ほかのコンピュータは引き続き、プロジェクトの GitHub リポジトリまたはワークスペースのリポジトリを使います。

GitHub リポジトリの追加

プロジェクトを開き、リソース で「リソースを追加」を選択します。ワークスペースに紐づけ済みのリポジトリを選ぶことも、Git URL を貼り付けることもできます。ワークスペースのリポジトリは 設定 → リポジトリ で管理します。GitHub を接続すると、同じページの GitHub から選択 で、App が認可済みのリポジトリをインポートできます。

リポジトリは GitHub に限定されません。ランタイムがアクセスできる Git URL であれば、どれでもリポジトリリソースとして使えます。セルフホストの Multica では、設定 → 連携 → Git ホスティング でセルフホストの Forgejo、Gitea、GitLab も接続できます。詳細はセルフホスト Git ホスティングを参照してください。

プロジェクトの作成時に、リポジトリ で直接リポジトリを選ぶこともできます。1 つのプロジェクトには複数の GitHub リポジトリを紐づけられます。

リソースの ref には、以後の checkout がデフォルトで使うブランチ、タグ、またはコミットを指定できます。default_branch_hint はエージェントにデフォルトブランチのヒントを与えるだけで、ブランチの切り替えを強制しません。

ローカルディレクトリの追加

ローカルディレクトリを追加する UI は Desktop でのみ提供されます。ブラウザからはコンピュータ上のフォルダを選択できないためです。

1. Desktop のローカルデーモンがオンラインであることを確認します。
2. プロジェクトの リソース を開きます。プロジェクト作成ダイアログの ローカルディレクトリ タブでも、プロジェクトができる前に同じ選択ができます。
3. 「ローカルディレクトリを追加」を選び、使用するフォルダを選択します。
4. 作業がそれをどう使うかを選びます — 直接 か 並行 で、違いは「作業がディレクトリを共有する方法」を参照してください。フォルダが git リポジトリで、そのマシンのランタイムが隔離を実行できる場合、Desktop は 並行 を、そうでなければ 直接 を初期選択します。その場で変更できますし、あとから リソース でディレクトリ横の鉛筆アイコンからも変更できます。

初期選択は、いま紐づけようとしているディレクトリにだけ適用されます。以前に紐づけたディレクトリは保存時のモードのままです — 既存の設定が知らないうちに切り替わることはありません。

ディレクトリは絶対パスで、すでに存在し、現在のデーモンが読み書きできる必要があります。次のパスは拒否されます: システムのルートとドライブのルート（/、C:\）、ホームディレクトリ自体と各ホームディレクトリの親（/Users、/home、/root など）、および /etc、/var、/tmp、/usr、/opt などのシステムディレクトリ。選択したパスがシンボリックリンクの場合は、まず実体のパスに解決してから同じルールでもう一度検証されます。直列ロックも実体のパスに対して働きます。

同じデーモンに紐づけられるローカルディレクトリは、プロジェクトごとに最大 1 つです。チーム内の別々のコンピュータは、同じプロジェクトにそれぞれ自分のディレクトリを紐づけられます。

作業がディレクトリを共有する方法

ローカルディレクトリには 2 つの実行モードがあり、リソースごとに設定します。リソースパネルから切り替えられるほか、CLI では --execution-mode を使います。Desktop での表示は 直接 と 並行 で、API・CLI とこのページの以降では識別子を使います。

in_place（既定）— 「直接」

エージェントはあなたのディレクトリで直接作業し、作業は一度に1つずつ実行されます。2 つの作業が同じ実体のディレクトリを使う場合、後から来た作業は waiting_local_directory に入り、先の作業がディレクトリを解放してから続行します。異なるシンボリックリンク経由で同じディレクトリに到達する 2 つのパスも、同じように直列化されます。

待機中にディレクトリが変更されることはありません。待機中の作業はキャンセルできます。キャンセルしなければ、ディレクトリが使えるようになるまで待ち続けます。

worktree — 「並行」

各作業が、あなたのリポジトリの独立した git ワークツリー を受け取ります。ワークツリーはランタイム自身のワークスペースディレクトリ内に作成されます。同じディレクトリに対する作業は並行して実行され、待機は発生しません。どの作業もあなたの作業コピーには書き込みません。

このモードには、コミットが 1 つ以上ある git リポジトリであることが必要です。そうでない場合、作業は黙って直列実行に戻るのではなく、明示的なエラーで失敗します。そのマシンのランタイムも、このモードを実装している必要があります。ランタイムは接続時にその能力を宣言し、Multica はバージョン番号ではなくこの宣言で判定します — 開発ビルドは、実装がまったくないまま十分に新しく見えるバージョン文字列を持ちうるからです。この宣言は 2 回検証されます。そのマシンのランタイムが能力を宣言していない間、リソースの保存は拒否され、そのマシンのアプリを更新するよう促されます。さらに各作業は実際にそれを受け取ったランタイムに対して再度検証されます — つまりリソース保存後にダウングレードされたマシンでは、作業が黙ってその場で実行されるのではなく、理由付きでキャンセルされます。worktree を選ぶことは隔離を求めることであり、代わりに作業コピーを書き換えることがフォールバックになることはありません。

エージェントが見るもの、あなたが受け取るもの:

• エージェントは HEAD ではなく、あなたが今見ている状態から開始します。 未コミットの変更と未追跡ファイルがワークツリーに再現されるため、すでに手元にないコードをレビューすることはありません。あなた自身の作業コピー、インデックス、stash リストが変更されることはありません。その状態を忠実に再現できない場合 — 再現の上限（2000 ファイル / 200 MiB）を超える未追跡コンテンツがある場合を含む — 作業は、見覚えのないツリーから開始する代わりに失敗します。通常の対処法は、まだ無視されていないビルド成果物を gitignore に加えるか削除することです。
• 成果物はあなたのリポジトリ内のブランチで、実行ごとではなくタスクごとに 1 本、agent/<agent>/<issue>（チャットなら agent/<agent>/chat-<session>）という名前が付きます。実行の「実行詳細」パネルにブランチ名が表示され（コピーも可能）、git branch でも見つけられます。git log / git diff でレビューし、マージするか cherry-pick するかは自分で決めます。Multica が代わりにマージすることはありません。途中で失敗した実行もブランチを報告します。エージェントが作った分はすでにコミットされているからです。
• 続きのコメントは前回の続きから始まります。 同じタスクへの次のコメントはそのブランチを再びチェックアウトするので、エージェントは直前に納品した成果の上で作業します。HEAD からやり直して前回の変更が別ブランチに取り残されることはありません。再適用されるのは前回以降にあなたが自分のディレクトリで変えた分だけです — それ以外はブランチがすでに持っています。ブランチをマージすれば、次の実行はまたあなたの HEAD から始まります。同じタスクで 2 つの実行が重なった場合、あとの実行は前の実行の成果から agent/<agent>/<issue>-<task> に分岐します。git では 1 つのブランチに 1 つの worktree しか持てないためです。
• あなたの変更がエージェントの成果と衝突したら、エージェントが解決します。 エージェントが書き換えたのと同じ行をあなたが書き換えた場合、git はどちらが正しいか決められません。その実行は衝突したままのワークツリーで始まり、何より先にマージを終わらせるよう指示されます（そのワークツリーで git status を実行すると未マージのファイルが並びます）。未マージのファイルが残ったままの実行は何も納品しません。作業は失敗し、ワークツリーは保持され、次の実行が同じ変更をもう一度提示するので、あなたの変更が黙って消えることはありません。
• Multica のものだと確認できたブランチだけを引き継ぎます。 引き継ぐかどうかは名前ではなく所有記録で決まります。記録にはどの対話のものかに加えて、そのブランチが最後に置かれたコミットも書かれています。あなたが自分で作った、たまたま agent/<agent>/<issue> という名前のブランチが、チェックアウトされることも、追記されることも、前回の成果として読まれることもありません。記録されたコミットをもう含まないブランチも同様なので、Multica のブランチを削除して同名のものを作り直したり、別の履歴へ force-move したりしても安全です。その場合作業は agent/<agent>/<issue>-<id> を使います。納品済みブランチの上にコミットするのは通常の使い方で、引き継ぎはそのまま続き、あなたのコミットは次の実行にそのまま含まれます。各ブランチはそれ自身のベースラインコミットから始まります。最初の実行が開始した時点のツリーを示すもので、あとでブランチを識別するのはこのコミットであり、git diff <baseline>..<branch> はちょうどエージェントの変更になります。ブランチを記録できなかった実行 — 途中で失敗した、記録の書き込みに失敗した、あるいはあなたの変更をブランチに取り込んだコミットより前にワークツリーをリセットした場合 — は失敗として報告されワークツリーを残します。以降の実行は自分のものだと証明できないブランチを引き継がず、新しいブランチから始めます。
• 黙って失われるものはありません。 エージェントが未コミットのまま残した変更は、ワークツリーが削除される前にそのブランチへコミットされます。作業が途中で失敗した場合も同様です。 ごくまれにそのコミット自体が実行できない場合 — 例えば commit.gpgSign が有効で、ランタイムが署名鍵を利用できないリポジトリ — ワークツリーは削除されずに意図的に保持され、作業は失敗として報告されます。あなたのリポジトリで git worktree list を実行すると、その変更を保持しているディレクトリが表示されます。
• 何も変更しなかった作業は、何も残しません。 そのブランチは git branch に空の項目として残らず、削除されます。ただし、それまでの実行の成果を持つタスクのブランチは常に残ります。

ワークツリーはランタイムのワークスペースディレクトリ内にあるため、通常のクリーンアップ周期で回収されます。あなたのリポジトリに残るのは 2 つ、ブランチと、ブランチごとの隠しref（refs/multica/local-state/ 配下）です。後者はそのブランチの所有者と、最後に引き継いだ時点のあなたのディレクトリの内容を記録します。隠しrefは git branch には現れません。git for-each-ref refs/multica で一覧できます。Multica はブランチと一緒に削除し、あなたが自分で消したブランチのrefは、そのリポジトリで次に作業が動くときに片付けます。git for-each-ref --format='%(refname)' refs/multica | xargs -n1 git update-ref -d で一括削除もできます。

実行中に書き込まれるもの

エージェントによるコードの変更のほかに、ランタイムは、現在の AI コーディングツールが必要とする指示ファイルと .multica/project/resources.json をディレクトリに書き込むことがあります。バージョン管理に含めたくない場合は .gitignore に追加してください。

Multica が実行環境をクリーンアップするとき、紐づけたローカルディレクトリを削除することはありません。エージェントによるこのディレクトリへの変更は、あなたがターミナルで AI コーディングツールを直接実行したときの変更と同じ性質のものであり、同じようにレビューが必要です。

CLI でリソースを管理する

# プロジェクト作成時にリポジトリを紐づける
multica project create \
  --title "Agent UX" \
  --repo https://github.com/multica-ai/multica

# リソースの一覧表示と追加
multica project resource list <project-id>
multica project resource add <project-id> \
  --type github_repo \
  --url https://github.com/multica-ai/multica \
  --ref main

# 特定のデーモン上のローカルディレクトリを紐づける
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id>

# ローカル git リポジトリを紐づけ、作業を各自のワークツリーで並行実行させる
multica project resource add <project-id> \
  --type local_directory \
  --local-path /absolute/path/to/repo \
  --daemon-id <daemon-id> \
  --execution-mode worktree

# 既存のローカルディレクトリのモードを切り替える
multica project resource update <project-id> <resource-id> --execution-mode worktree
multica project resource update <project-id> <resource-id> --execution-mode in_place


# リソースを削除する
multica project resource remove <project-id> <resource-id>

リソースの変更は、その後に作成される作業に反映されます。すでに終了した実行の記録が書き換えられることはありません。

次のステップ

• プロジェクト — プロジェクトのコンテキスト、進捗、リードを理解します。
• デーモンとランタイム — 作業をどのコンピュータが受け取るかを理解します。
• 作業 — waiting_local_directory などの実行ステートを確認します。