他製品からの移行

Spantail は、特定の製品からの移行を前提とした専用ツールやマニュアルを用意していません — 「ツール X からインポート」といったウィザードは存在しません。移行は Spantail 自身のツール、 すなわち MCP サーバーと CLI を、 Claude Code のような AI コーディングエージェントに操作させて 行います。エージェントがエクスポートの形に合わせて調整してくれるため、双方に決まったフォーマットは 必要ありません。

この方法で一括移行できるのは作業エントリだけです。エージェント活動はインポート対象では ありません — エージェントを接続した時点からセッションが流れ始めます。

移行元のツールからエクスポートする

まず移行元システムからデータを取り出します。データベースのダンプファイル、CSV エクスポート、 JSON/JSONL の API ダンプなど、出せるものなら何でも構いません。1 テーブル（または 1 エンティティ） につき 1 ファイルにしておくと、下記の各ステップと対応づけやすくなります。

テーブルごとに、依存順でインポートする

Spantail のエンティティは入れ子になっています — ワークスペースがプロジェクトを含み、作業エントリは ワークスペースに属し、プロジェクトをスラッグで、作成者をメールで参照します。親から子の順で インポートしてください。子は親をスラッグで、作成者をメールで解決し、Spantail が欠けている親を自動 作成することはありません（未知のプロジェクトスラッグがあると実行は失敗し、存在するスラッグの一覧が 表示されます）。Claude Code にエクスポートしたファイルを渡し、次の順序でテーブルを進めます — 各 ステップのプロンプト例を添えます。

1. ワークスペース — 移行先のワークスペースを最初に作成します。

   departments.csv を読み、各行につき 1 つ Spantail のワークスペースを API 経由で作成して。 各ワークスペースの名前・id・スラッグを出力して。

2. プロジェクト — 続いて各ワークスペース内にプロジェクトを作成します。エントリのインポートは プロジェクトをスラッグで解決するため、移行元の識別子と一致する（またはきれいに対応づく） スラッグを付けます。

   projects.csv の各行について、department 列の名前のワークスペースにプロジェクトを作成して。 key 列をプロジェクトのスラッグに使って。

3. 人（メンバー） — 各エントリを取り込む前に、全員分のアカウントを用意します（下記参照）。

   users.csv から、作成すべきアカウント（名前・メール）の一覧を出して。email/password 認証の ために、各人にインポート前にサインインできる仮パスワードも生成して。

4. 作業エントリ — 最後にインポートします。インスタンス管理者として実行すれば、チーム全員の 履歴を 1 回でまとめて取り込めます。

   time-logs.csv を JSONL 一括インポート形式に変換して。各行をプロジェクトのスラッグと作成者の メールに対応づけ、externalId に移行元の行 ID をセットして、まず --dry-run でインポートして。

5. エージェント活動 — 移行対象外です。エージェント活動の捕捉に 従ってエージェントをインスタンスへ向けると、その時点からセッションが流れ始めます。

人（メンバー）: アカウントを先に用意する

各人が自分でサインインして自分の履歴をインポートする必要はありません。移行先のアカウントを先に 用意し、そのうえで全員分のエントリをまとめてインポートします。エントリが着地する時点でアカウントが すでに存在しているため、次のようになります。

• ソーシャルログイン（例: Google）は初回サインイン時にメールでアカウントを照合します — 本人はそのままサインインでき、別途サインアップは不要です。
• email/password ログインには照合する相手がないため、管理者があらかじめ各アカウントに 仮パスワードを設定して配布します。

アカウントが揃っていれば、インスタンス管理者がエントリのインポートをチーム全員分まとめて 1 回 実行します。各行は作成者のメールを user フィールドに持つ（無い行は --user にフォールバック）ため、 各エントリは実行した管理者ではなく本来の作成者に帰属します。

変換は Claude Code に任せる

Claude Code にエクスポートしたファイルと Spantail の MCP サーバー（または CLI）を渡し、各テーブルを 上記の対応するステップに割り当てさせます。インポートの仕方はデータ量によって変わります。

• 少量のデータ — エージェントにエクスポートを読ませ、MCP や CLI のツールを 1 レコードずつ直接 呼ばせます（log_work、または最大 100 件まとめる log_work_batch）。スクリプトは不要です。
• 大量のデータ — エージェントに、各ダンプを JSONL 一括インポート形式へ 変換する小さなスクリプトを書かせ、spantail entries import を実行します。エントリはアトミックな バッチで送信されるため、数千行でも確実に登録でき、失敗したバッチは再実行できます。

どちらの方法でも、各エントリの externalId に移行元システムでの ID を指定してください。これにより インポートが冪等になり — 同じデータを再実行しても重複ではなく更新になり — 一部で予行演習し、 マッピングを直してから全件を安心して流せます。JSONL インポートは --dry-run で予行演習でき、 何も書き込む前に全行を検証し、すべてのプロジェクトスラッグ（と作成者のメール）を解決します。

spantail entries import work-entries.jsonl --workspace acme --dry-run

エージェントが対象とすべきフィールドの一覧は 一括インポート（JSONL）を参照してください。