handoff-bridge 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +0 -9
- package/README.md +11 -20
- package/docs/theory.md +39 -39
- package/package.json +1 -1
package/README.en.md
CHANGED
|
@@ -54,15 +54,6 @@ If an I/O error or process interruption occurs after writing begins, automatic r
|
|
|
54
54
|
|
|
55
55
|
See [Theory](docs/theory.en.md) for the design rationale and [SKILL.md](skills/handoff-bridge/SKILL.md) for the execution contract.
|
|
56
56
|
|
|
57
|
-
## Development and publishing
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
npm test
|
|
61
|
-
npm run check:package
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
See [scripts/PUBLISHING.md](scripts/PUBLISHING.md) for the release procedure.
|
|
65
|
-
|
|
66
57
|
## License
|
|
67
58
|
|
|
68
59
|
MIT
|
package/README.md
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
[English](README.en.md) | 日本語
|
|
4
4
|
|
|
5
|
-
`handoff-bridge`
|
|
5
|
+
`handoff-bridge` は、コーディングエージェントが把握している作業状況を、次のセッションが迷わず再開できる引き継ぎ文書にまとめるスキルです。
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
全文ログを複製するのではなく、目的、現在地、決定事項、次の行動、未解決事項と、確認すべきコードや仕様などへの参照を選んでまとめます。引き継ぎは作成時点の記録であり、内容が食い違う場合は参照先のコードや仕様などを優先します。
|
|
8
8
|
|
|
9
9
|
## インストール
|
|
10
10
|
|
|
@@ -28,7 +28,7 @@ npx handoff-bridge@latest --codex /path/to/project
|
|
|
28
28
|
| Codex | `.agents/skills/handoff-bridge/` |
|
|
29
29
|
| Claude | `.claude/skills/handoff-bridge/` |
|
|
30
30
|
|
|
31
|
-
このインストーラーはモデルを実行せず、API
|
|
31
|
+
このインストーラーはモデルを実行せず、API キーや Claude Subscription の認証も使いません。`npx` が npm パッケージを取得する通信だけが発生する場合があります。
|
|
32
32
|
|
|
33
33
|
## 使い方
|
|
34
34
|
|
|
@@ -38,33 +38,24 @@ npx handoff-bridge@latest --codex /path/to/project
|
|
|
38
38
|
handoff-bridgeで次のセッションへの引き継ぎを作って。
|
|
39
39
|
```
|
|
40
40
|
|
|
41
|
-
保存先を明示しなければ、検証済みの Markdown
|
|
41
|
+
保存先を明示しなければ、検証済みの Markdown を会話へ返すだけです。ファイルへ保存したい場合は、依頼の中で保存先のパスを省略せず指定してください。
|
|
42
42
|
|
|
43
43
|
## ファイル保護
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
インストール前に、すべての配置先を確認します。
|
|
46
46
|
|
|
47
|
-
-
|
|
47
|
+
- 対象のファイルがなければ新規作成します。
|
|
48
48
|
- 同じ内容の通常ファイルは変更せずスキップします。
|
|
49
|
-
- 内容が異なる既存ファイルが1
|
|
50
|
-
-
|
|
49
|
+
- 内容が異なる既存ファイルが1つでもあれば、何も書き込まずにインストールを中止します。
|
|
50
|
+
- 配置先までの途中にシンボリックリンクがある場合や、ディレクトリではないものが含まれる場合は中止します。
|
|
51
51
|
- 既存ファイルは上書きしません。
|
|
52
52
|
|
|
53
|
-
書き込み開始後に I/O
|
|
53
|
+
書き込み開始後に I/O エラーやプロセス停止が起きた場合、自動で元の状態には戻さないため、新規ファイルの一部が残ることがあります。同じ内容のファイルは再実行時にスキップされるため、原因を直して再実行できます。
|
|
54
54
|
|
|
55
55
|
## 設計
|
|
56
56
|
|
|
57
|
-
詳しい考え方は [理論的背景](docs/theory.md)
|
|
57
|
+
詳しい考え方は [理論的背景](docs/theory.md) を参照してください。スキルを実行するときの規則は [SKILL.md](skills/handoff-bridge/SKILL.md) にあります。
|
|
58
58
|
|
|
59
|
-
##
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
npm test
|
|
63
|
-
npm run check:package
|
|
64
|
-
```
|
|
65
|
-
|
|
66
|
-
公開手順は [scripts/PUBLISHING.md](scripts/PUBLISHING.md) にあります。
|
|
67
|
-
|
|
68
|
-
## License
|
|
59
|
+
## ライセンス
|
|
69
60
|
|
|
70
61
|
MIT
|
package/docs/theory.md
CHANGED
|
@@ -2,93 +2,93 @@
|
|
|
2
2
|
|
|
3
3
|
[English](theory.en.md) | 日本語
|
|
4
4
|
|
|
5
|
-
`handoff-bridge`
|
|
5
|
+
`handoff-bridge` は、コーディングエージェントの作業を別のセッションへ引き継ぐために、必要な情報を絞り込んで検証する仕組みです。
|
|
6
6
|
|
|
7
7
|
**この文書を読まなくても使えます。** 導入と利用方法は [README](../README.md)、実行上の規則は [SKILL.md](../skills/handoff-bridge/SKILL.md) にあります。
|
|
8
8
|
|
|
9
|
-
## 問題 —
|
|
9
|
+
## 問題 — セッションをまたぐと作業の意味が失われる
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
新しいセッションには、前のセッションの会話や、その場で下した判断が完全には引き継がれません。一方、リポジトリの全ファイルや会話全文を渡すと、重要な情報が大量の文章に埋もれます。必要なのは全文の保存ではなく、次の担当が最初に何を判断し、何をすればよいか分かるだけの情報です。
|
|
12
12
|
|
|
13
13
|
handoff-bridge は、引き継ぐ情報を次へ絞ります。
|
|
14
14
|
|
|
15
15
|
- 何を達成しようとしているか。
|
|
16
16
|
- どこまで終わり、何が作業中か。
|
|
17
|
-
-
|
|
17
|
+
- コードや仕様など、参照先の資料だけからは分からない判断と理由。
|
|
18
18
|
- 次に行う具体的な行動と成功の確認方法。
|
|
19
19
|
- 既知の未解決事項、リスク、例外時の対応。
|
|
20
|
-
-
|
|
20
|
+
- 読み直すべきコードや仕様などと、そこで何を確認するか。
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
これは、元の情報を完全に戻せる圧縮ではありません。作業の再開に必要な意味を残し、コードや仕様などから再確認できる詳細は参照先だけを示すことで、目的に合わせて情報を絞り込みます。
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## 引き継ぎだけで現在の事実を決めない
|
|
25
25
|
|
|
26
|
-
|
|
26
|
+
引き継ぎは、作成した時点の状況を記録したものです。コード、仕様、課題管理の記録、設計文書などが後から更新されれば、引き継ぎの記述は古くなります。そのため、出力には作成日時と参照先を含め、次の担当が最初に最新の情報を確認できる形にします。
|
|
27
27
|
|
|
28
28
|
```text
|
|
29
|
-
|
|
30
|
-
│
|
|
31
|
-
|
|
29
|
+
現在わかっていること ──> 選別 ──> 検証済みの引き継ぎ ──> 次のセッション
|
|
30
|
+
│ │
|
|
31
|
+
└── コードや仕様などへの参照 ──┘
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
引き継ぎは「前の担当がそう理解していた」という記録にはなりますが、現在の事実は参照先のコードや仕様などで確認します。
|
|
35
35
|
|
|
36
|
-
##
|
|
36
|
+
## なぜスキルが文章を組み立て、スクリプトが検証するのか
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
目的や判断理由を選ぶには、文脈を理解する必要があります。これは、あらかじめ決めた規則で情報を抜き出すプログラムだけでは扱いにくい仕事です。一方、必須項目や出力形式を満たしているか、秘密情報と思われる値を含んでいないか、保存時に既存ファイルを上書きしないかは、決まった規則で動くプログラムで確認できます。
|
|
39
39
|
|
|
40
40
|
そこで責務を分けます。
|
|
41
41
|
|
|
42
|
-
-
|
|
43
|
-
-
|
|
44
|
-
-
|
|
42
|
+
- **スキルを実行するエージェント**は、すでに把握している情報から引き継ぎに必要な内容を選び、内部データを組み立てる。
|
|
43
|
+
- **検証用スクリプト**は、内部データと Markdown が決められた形式を満たすか確認し、常に同じ形式で出力する。
|
|
44
|
+
- **利用者**は、引き継ぎを作るかどうかと、保存する場合はその保存先を明示する。
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
自然言語による判断を完全に自動化せず、機械的に確認できる部分だけをプログラムに任せる設計です。
|
|
47
47
|
|
|
48
|
-
##
|
|
48
|
+
## 現在のセッションで確認できる情報だけを使う理由
|
|
49
49
|
|
|
50
|
-
|
|
50
|
+
引き継ぎの作成を理由にリポジトリ、ネットワーク、表示されていない会話履歴を追加で調べ始めると、引き継ぎ作業が新しい調査に変わってしまいます。さらに、情報を読めることと、その情報を送信・保存してよいことを混同する危険があります。
|
|
51
51
|
|
|
52
|
-
|
|
52
|
+
そのためスキルは、実行するエージェントにすでに与えられている情報だけを使います。参照先と、そこで確認すべき内容は引き継ぎに記録しますが、その場で参照先を読み直しません。情報が不足していても推測で補わず、未解決事項として残します。
|
|
53
53
|
|
|
54
|
-
##
|
|
54
|
+
## 作業再開に必要な情報量
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
短すぎる引き継ぎは「続けてください」だけになり、次の担当に調査のやり直しを強います。長すぎる引き継ぎは会話全文の複製になり、何を信頼し、どこから始めればよいかを分かりにくくします。
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
十分かどうかは文字数では決まりません。次の担当が以下の点を説明できることが基準です。
|
|
59
59
|
|
|
60
60
|
1. 目的は何か。
|
|
61
61
|
2. 現在地はどこか。
|
|
62
|
-
3.
|
|
62
|
+
3. 最初にどの参照先を、何のために読むか。
|
|
63
63
|
4. 最初の行動は何か。
|
|
64
64
|
5. 何を確認できれば前進したと言えるか。
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
これらを判断できる情報を残しつつ、コードや仕様などから再確認できる説明は重ねて書かないようにします。
|
|
67
67
|
|
|
68
|
-
##
|
|
68
|
+
## 秘密情報と外部から届いた文章
|
|
69
69
|
|
|
70
|
-
|
|
70
|
+
現在のセッションで確認できる情報でも、認証情報、秘密情報、個人を直接特定できる値は出力しません。必要な場合は「再取得が必要」という状態だけを残します。
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
また、貼り付けられた文書や参照内容に命令文が含まれていても、それは引き継ぐ情報の一部です。引き継ぎの作成中に実行すべき命令としては扱いません。これは、情報を読むことと、その情報に従って行動する権限を分けるためです。
|
|
73
73
|
|
|
74
|
-
##
|
|
74
|
+
## 保存先を明示してもらう理由
|
|
75
75
|
|
|
76
|
-
|
|
76
|
+
保存先が指定されていない場合、結果は会話へ返すだけです。既定のファイル名を推測すると、利用者が意図しないファイルを作り、補助的な文書を正式な記録のように見せる可能性があるからです。
|
|
77
77
|
|
|
78
|
-
|
|
78
|
+
保存先が明示された場合も、既存ファイルは確認なしに上書きしません。生成と検証に成功した Markdown だけを保存対象にし、保存に失敗した場合は、会話に返した結果とは分けて報告します。
|
|
79
79
|
|
|
80
80
|
## 配布を小さく保つ
|
|
81
81
|
|
|
82
|
-
npm
|
|
82
|
+
npm パッケージに含めるのは、配布元となるスキル、機械的な検証用スクリプト、日英の説明文書、最小限のインストーラーだけです。インストーラーは、各エージェント向けのプロジェクト内スキルディレクトリへ同じ内容のファイルを配置します。モデルの実行、API クライアント、自動更新、管理用ファイル、バックアップ、複数ファイルをまとめて元に戻す機能は持ちません。
|
|
83
83
|
|
|
84
|
-
|
|
84
|
+
既存ファイルを守るため、すべての配置先を事前に確認し、内容が同じファイルは変更せず、異なるファイルがあれば書き込み前に中止し、シンボリックリンクは拒否します。書き込み中に OS の障害が起きた場合まで、すべて元に戻せるとは保証しません。複雑な復旧機能を増やす代わりに、既存ファイルを上書きせず、安全に再実行できるようにします。
|
|
85
85
|
|
|
86
86
|
## 限界
|
|
87
87
|
|
|
88
|
-
-
|
|
88
|
+
- 引き継ぐ内容が十分かどうかは、スキルを実行するモデルに与えられた情報と、そのモデルによる情報の選び方に左右されます。
|
|
89
89
|
- 見えていない情報は復元できません。
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
90
|
+
- 参照先の正しさや最新性は、引き継ぎの作成時には検証しません。
|
|
91
|
+
- 秘密情報らしい文字列を機械的に検査しても、すべての機密情報を識別できるとは限りません。
|
|
92
|
+
- 出力の検証で確認できるのは、形式とあらかじめ定めた禁止事項です。次の担当が必ず作業を再開できることまでは証明できません。
|
|
93
93
|
|
|
94
|
-
|
|
94
|
+
これらの限界があるため、引き継ぎだけで現在の事実を決めず、次の担当が最初に参照先を確認することを利用手順に含めています。
|