handoff-bridge

English | 日本語

handoff-bridge は、コーディングエージェントが把握している作業状況を、次のセッションが迷わず再開できる引き継ぎ文書にまとめるスキルです。

全文ログを複製するのではなく、目的、現在地、決定事項、次の行動、未解決事項と、確認すべきコードや仕様などへの参照を選んでまとめます。引き継ぎは作成時点の記録であり、内容が食い違う場合は参照先のコードや仕様などを優先します。

インストール

プロジェクトのルートで、利用するエージェントを1つ指定します。

npx handoff-bridge@latest --codex
npx handoff-bridge@latest --claude
npx handoff-bridge@latest --gemini

別のプロジェクトへ入れる場合はパスを末尾に指定します。

npx handoff-bridge@latest --codex /path/to/project

配置先は次のとおりです。

エージェント	配置先
Codex	.agents/skills/handoff-bridge/
Claude	.claude/skills/handoff-bridge/
Gemini CLI	.gemini/skills/handoff-bridge/

このインストーラーはモデルを実行せず、API キーや Claude Subscription の認証も使いません。npx が npm パッケージを取得する通信だけが発生する場合があります。

使い方

インストール後、エージェントへ次のように依頼します。

handoff-bridgeで次のセッションへの引き継ぎを作って。

Gemini CLIはskillからslash commandを自動的に用意するため、次の形でも起動できます。

/handoff-bridge
/handoff-bridge 保存先を docs/handoff.md にして

起動中のGemini CLIへインストールした場合は、/skills reloadを実行してください。skillやcommandが表示されない場合は、最初にそのprojectを信頼する確認へ同意したか確かめてから、/skills listで認識状態を確認します。

保存先を指定しなければ、検証済みの引き継ぎ書は project 直下の .handoff-bridge/ に handoff-<UTC日時>-<短いタイトル>.md という新しいファイルとして保存され、会話には保存先だけが案内されます。この領域は内包の .gitignore によって Git 管理の対象外です。同じ名前になる場合は、既存ファイルを変えずに -2、-3 と連番の別ファイルを作ります。

本文を会話でそのまま受け取りたい場合はその旨を明示し、別の場所へ保存したい場合は保存先のパスを省略せず指定してください。保存に失敗しても、本文が別の場所へ勝手に出力されることはありません。

.handoff-bridge/ や過去の引き継ぎ書が存在しても、次のセッションが自動で読み込み・再開することはありません。読み込むときは、対象のファイルを明示して依頼してください。

ファイル保護

インストールは skill の配置に加えて、project 直下に既定保存用の .handoff-bridge/（作成した利用者だけが入れる権限）と、内容が * の .gitignore を用意します。既存の同名ディレクトリは権限を変えずに再利用し、内容の異なる .gitignore がある場合は skill も含めて何も書き込まずに中止します。

インストール前に、すべての配置先を確認します。

• 対象のファイルがなければ新規作成します。
• 同じ内容の通常ファイルは変更せずスキップします。
• 内容が異なる既存ファイルが1つでもあれば、何も書き込まずにインストールを中止します。
• 配置先までの途中にシンボリックリンクがある場合や、ディレクトリではないものが含まれる場合は中止します。
• 既存ファイルは上書きしません。

書き込み開始後に I/O エラーやプロセス停止が起きた場合、自動で元の状態には戻さないため、新規ファイルの一部が残ることがあります。同じ内容のファイルは再実行時にスキップされるため、原因を直して再実行できます。

設計

詳しい考え方は 理論的背景 を参照してください。スキルを実行するときの規則は SKILL.md にあります。

ライセンス

MIT