@adamchanadam/agent-handoff-kit 0.2.2 → 0.3.0
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.md +303 -269
- package/bin/agent-handoff-kit.mjs +1434 -1285
- package/package.json +1 -1
- package/packs/integrations.md +179 -0
- package/packs/knowledge.md +35 -31
- package/packs/onboarding.md +389 -298
- package/packs/safety.md +37 -29
- package/runtime-core/AGENTS.core.md +153 -144
- package/runtime-core/PROJECT_INDEX.md +136 -93
- package/runtime-core/RULE_PACKS.md +20 -19
- package/runtime-core/SESSION_HANDOFF.md +151 -150
package/README.md
CHANGED
|
@@ -1,269 +1,303 @@
|
|
|
1
|
-
# Agent Handoff Kit
|
|
2
|
-
|
|
3
|
-
狀態:`v0.
|
|
4
|
-
|
|
5
|
-

|
|
6
|
-
|
|
7
|
-
Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
8
|
-
|
|
9
|
-
它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
|
|
10
|
-
|
|
11
|
-
> 🚀 **第一次用?你不需要先讀本 README 或任何文檔。**
|
|
12
|
-
>
|
|
13
|
-
> 安裝完成後,在 AI 對話中講一句:
|
|
14
|
-
>
|
|
15
|
-
> ```
|
|
16
|
-
> Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
17
|
-
> ```
|
|
18
|
-
>
|
|
19
|
-
> AI 會自動引導你選擇情景(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
|
|
20
|
-
|
|
21
|
-
想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想睇實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情景(整理電腦下載目錄、開咖啡店市場調查)嘅七步流程完整示範。README 則保留安裝、日常使用與限制。
|
|
22
|
-
|
|
23
|
-
## 它解決甚麼問題
|
|
24
|
-
|
|
25
|
-
用 AI 做長期項目,常見四個問題:
|
|
26
|
-
|
|
27
|
-
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
28
|
-
|---|---|
|
|
29
|
-
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
30
|
-
| 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
31
|
-
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
|
|
32
|
-
| AI 可能亂改、亂刪或誤發佈 | 內置 safety 工作模式;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
33
|
-
|
|
34
|
-
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
35
|
-
|
|
36
|
-
## 三步上手
|
|
37
|
-
|
|
38
|
-
### 一、安裝
|
|
39
|
-
|
|
40
|
-
在你的專案資料夾打開 Terminal,執行:
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
npx @adamchanadam/agent-handoff-kit init
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
出現確認問題時,輸入 `yes`。
|
|
47
|
-
|
|
48
|
-
安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
|
|
49
|
-
|
|
50
|
-
### 二、開工
|
|
51
|
-
|
|
52
|
-
打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
|
|
53
|
-
|
|
54
|
-
**第一次用(新手引導 trigger)**:
|
|
55
|
-
|
|
56
|
-
```text
|
|
57
|
-
Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
AI 會自動載入 onboarding pack,引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。
|
|
61
|
-
|
|
62
|
-
**之後 session(你已熟悉 v2 之後)可用更直接 prompt**:
|
|
63
|
-
|
|
64
|
-
```text
|
|
65
|
-
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
|
|
69
|
-
|
|
70
|
-
### 三、收工
|
|
71
|
-
|
|
72
|
-
工作完成想結束時,只需輸入:
|
|
73
|
-
|
|
74
|
-
```text
|
|
75
|
-
收工
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
也可以輸入:
|
|
79
|
-
|
|
80
|
-
```text
|
|
81
|
-
wrap up
|
|
82
|
-
handoff
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
|
|
86
|
-
|
|
87
|
-
```text
|
|
88
|
-
START_NEXT_SESSION_PROMPT.txt
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
|
|
92
|
-
|
|
93
|
-
## 檢查是否安裝完整
|
|
94
|
-
|
|
95
|
-
如要檢查安裝是否完整,可在 Terminal 執行:
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
npx @adamchanadam/agent-handoff-kit doctor
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
|
|
102
|
-
|
|
103
|
-
這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
|
|
104
|
-
|
|
105
|
-
## 會安裝甚麼
|
|
106
|
-
|
|
107
|
-
安裝工具會在你的專案中建立:
|
|
108
|
-
|
|
109
|
-
```text
|
|
110
|
-
AGENTS.md
|
|
111
|
-
CLAUDE.md
|
|
112
|
-
GEMINI.md
|
|
113
|
-
START_NEXT_SESSION_PROMPT.txt
|
|
114
|
-
dev/SESSION_HANDOFF.md
|
|
115
|
-
dev/SESSION_LOG.md
|
|
116
|
-
dev/PROJECT_INDEX.md
|
|
117
|
-
dev/PROJECT_DECISIONS.md
|
|
118
|
-
dev/DOC_SYNC_REGISTRY.md
|
|
119
|
-
dev/RULE_PACKS.md
|
|
120
|
-
dev/rules/*.md
|
|
121
|
-
```
|
|
122
|
-
|
|
123
|
-
| 文件 | 用途 |
|
|
124
|
-
|---|---|
|
|
125
|
-
| `AGENTS.md` | AI 開工時最先讀的入口文件。 |
|
|
126
|
-
| `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
|
|
127
|
-
| `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
|
|
128
|
-
| `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
|
|
129
|
-
| `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
|
|
130
|
-
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。主檔長期保持短小;N=11+ 嘅舊條目自動 archive 至 `dev/SESSION_LOG_archive/`,trace-back 用。接力靠 `SESSION_HANDOFF.md`,本檔屬冷資料層。 |
|
|
131
|
-
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
132
|
-
| `dev/PROJECT_DECISIONS.md` | 保存項目嘅長期演進、決策、架構取捨、學習觀察。屬 warm 資料層 —— AI 開工**不需要讀**本檔;遇到「之前點解咁做」嘅問題時 AI 自己嚟搵。短期單一 task 項目本檔保持近空;長期項目 AI 喺收工時自動 maintain。 |
|
|
133
|
-
| `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
|
|
134
|
-
| `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
|
|
135
|
-
| `dev/rules/*.md` | 按任務載入的細分工作規則。含
|
|
136
|
-
|
|
137
|
-
你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
|
|
138
|
-
|
|
139
|
-
## SESSION_LOG 嘅自動整理機制
|
|
140
|
-
|
|
141
|
-
長期使用後,`dev/SESSION_LOG.md` 唔會無止境膨脹。每次你講「收工」,AI 會自動執行 N 規則整理(N 代表 session 嘅 entry 數,N=1 為最新):
|
|
142
|
-
|
|
143
|
-
- **N=1–3**:最新三條 session 條目保留完整內容(safety buffer,萬一交接出錯仍有 fallback)。
|
|
144
|
-
- **N=4–10**:核心內容已被 `dev/SESSION_HANDOFF.md` 等真源吸收嘅條目,自動降為短索引(日期 + 標題 + 真源 anchor)。
|
|
145
|
-
- **N=11+**:自動 archive 入 `dev/SESSION_LOG_archive/archive_<批次>_<日期區間>.md`;主檔末尾留一份 archive index 做 trace-back 入口。
|
|
146
|
-
|
|
147
|
-
接力責任由 `dev/SESSION_HANDOFF.md` 對賬式更新承擔;`dev/SESSION_LOG.md` 屬 trace-back / 審計用嘅冷資料層。**新 AI session 開工唔需要讀完整 LOG**,只需要讀 `AGENTS.md` + `dev/SESSION_HANDOFF.md` + 索引文件就足夠接力。
|
|
148
|
-
|
|
149
|
-
所以你部電腦嘅 `dev/` 資料夾唔會被 session log 不停撐大,亦唔需要你手動清理。如果主檔意外膨脹(11 條以上未 archive,或單檔超過 1500 行),`doctor` 會喺輸出顯示一個 warning 提醒 AI 下次收工執行整理;但呢個只屬提醒,唔會令 `doctor` 失敗、亦唔阻擋安裝。
|
|
150
|
-
|
|
151
|
-
## 項目決策日誌
|
|
152
|
-
|
|
153
|
-
`dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察 narrative。屬 warm 資料層 —— AI 開工**不需要讀**本檔;當你問「之前為何這樣做」時,AI 自己會從這裡找答案。
|
|
154
|
-
|
|
155
|
-
- 短期 single-task 項目:本檔保持近空,你不需要 maintain
|
|
156
|
-
- 長期持續演進項目:AI 會在每次收工時自動 maintain
|
|
157
|
-
- HANDOFF 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 條時,AI 自動 split 舊條目至此
|
|
158
|
-
- 觀察到任務需求演進、架構取捨、累積學習 pattern 時,AI 主動 append entry
|
|
159
|
-
|
|
160
|
-
本檔含 4 個固定 H2 section:
|
|
161
|
-
|
|
162
|
-
- **Evolution Timeline** —— 任務需求嘅長期演進
|
|
163
|
-
- **Decisions Archive** —— 累積決策嘅冷封存
|
|
164
|
-
- **Architecture Choices** —— 主要架構取捨同 rationale
|
|
165
|
-
- **Insights & Learnings** —— 多 session 累積嘅學習觀察
|
|
166
|
-
|
|
167
|
-
本檔同 SESSION_LOG 嘅 archive 機制屬同一套 hot / warm / cold 分層紀律 —— 你部電腦嘅 `dev/` 資料夾長期使用都唔會被無關 narrative 撐大,亦唔需要你手動清理。新手用戶完全唔需要打開本檔,亦唔需要記任何 schema —— 一切由 AI 自律執行。
|
|
168
|
-
|
|
169
|
-
##
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
##
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
```bash
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
1
|
+
# Agent Handoff Kit
|
|
2
|
+
|
|
3
|
+
狀態:`v0.3.0` 已正式發佈到 GitHub 與 npm。這是早期可用版本,尚未宣稱所有需求已完成。
|
|
4
|
+
|
|
5
|
+

|
|
6
|
+
|
|
7
|
+
Agent Handoff Kit 是 **AI Session 之間的接力棒**。
|
|
8
|
+
|
|
9
|
+
它只處理一件狹窄但重要的事:AI 跨對話失憶。每次開新對話,AI 往往不記得你上次做到哪裡,也認不出中途新建的文件、你引入的參考資料、哪些檔案是真源。這套工具把進度、下一步、風險、檔案登記與下次開工提示寫進固定文件,讓下一個 AI 工具能接得上上一棒。
|
|
10
|
+
|
|
11
|
+
> 🚀 **第一次用?你不需要先讀本 README 或任何文檔。**
|
|
12
|
+
>
|
|
13
|
+
> 安裝完成後,在 AI 對話中講一句:
|
|
14
|
+
>
|
|
15
|
+
> ```
|
|
16
|
+
> Work in <你的資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
17
|
+
> ```
|
|
18
|
+
>
|
|
19
|
+
> AI 會自動引導你選擇情景(寫代碼 / 寫報告 / 整理知識庫 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。本 README 與下方介紹頁是參考對照,不是必讀。
|
|
20
|
+
|
|
21
|
+
想先看非技術版介紹,可打開 GitHub Pages 上的 [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html) —— 新手 60 秒入門。看完想睇實際操作示範,可開 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html) —— 兩個日常情景(整理電腦下載目錄、開咖啡店市場調查)嘅七步流程完整示範。README 則保留安裝、日常使用與限制。
|
|
22
|
+
|
|
23
|
+
## 它解決甚麼問題
|
|
24
|
+
|
|
25
|
+
用 AI 做長期項目,常見四個問題:
|
|
26
|
+
|
|
27
|
+
| 問題 | Agent Handoff Kit 怎樣處理 |
|
|
28
|
+
|---|---|
|
|
29
|
+
| 新 AI 不知做到哪 | 用 `dev/SESSION_HANDOFF.md` 保存目前狀態、下一步、風險與驗收。 |
|
|
30
|
+
| 新建檔案、參考資料變孤兒 | 用 `dev/PROJECT_INDEX.md` 與 `dev/DOC_SYNC_REGISTRY.md` 登記檔案角色、真源與同步責任。 |
|
|
31
|
+
| 不同 AI 工具入口不同 | 同時安裝 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`,全部指向同一套開工流程。 |
|
|
32
|
+
| AI 可能亂改、亂刪或誤發佈 | 內置 safety 工作模式;高風險操作必須先講計劃,破壞性指令與未批准發佈一律禁止。 |
|
|
33
|
+
|
|
34
|
+
它不是聊天機器人,也不是開發框架。它比較像一本固定放在專案內的交接簿。
|
|
35
|
+
|
|
36
|
+
## 三步上手
|
|
37
|
+
|
|
38
|
+
### 一、安裝
|
|
39
|
+
|
|
40
|
+
在你的專案資料夾打開 Terminal,執行:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
npx @adamchanadam/agent-handoff-kit init
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
出現確認問題時,輸入 `yes`。
|
|
47
|
+
|
|
48
|
+
安裝完成後,你會看到一段 `Work in ...` 文字。請特別留意:那一段不是給 Terminal 的指令,而是要貼到 AI 對話。
|
|
49
|
+
|
|
50
|
+
### 二、開工
|
|
51
|
+
|
|
52
|
+
打開你想用的 AI 工具,在新對話貼上安裝工具顯示的文字。
|
|
53
|
+
|
|
54
|
+
**第一次用(新手引導 trigger)**:
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
Work in <你的專案資料夾>. I just installed agent-handoff-kit. Help me get started.
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
AI 會自動載入 onboarding pack,引導你選擇情景(寫代碼 / 研究報告 / 知識庫整理 / 學寫代碼 / 其他),然後一步一步帶你做第一個任務。
|
|
61
|
+
|
|
62
|
+
**之後 session(你已熟悉 v2 之後)可用更直接 prompt**:
|
|
63
|
+
|
|
64
|
+
```text
|
|
65
|
+
Work in <你的專案資料夾>. Read AGENTS.md and follow it. Before changing anything, tell me the current state and your recommended next step.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
然後用日常話描述你要完成的任務。AI 應先讀交接文件,說明目前狀態、下一步與風險,再開始工作。
|
|
69
|
+
|
|
70
|
+
### 三、收工
|
|
71
|
+
|
|
72
|
+
工作完成想結束時,只需輸入:
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
收工
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
也可以輸入:
|
|
79
|
+
|
|
80
|
+
```text
|
|
81
|
+
wrap up
|
|
82
|
+
handoff
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
AI 應更新交接文件,並輸出下一次可直接貼上的開工文字。最終回覆會把那段文字放在 fenced `text` code block 內,方便完整複製。安裝後也會有一個更直覺的副本檔:
|
|
86
|
+
|
|
87
|
+
```text
|
|
88
|
+
START_NEXT_SESSION_PROMPT.txt
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
這個檔案只是方便你複製下次開工提示;真正權威來源仍是 `dev/SESSION_HANDOFF.md` 裡的 `Next Session Opening Message`。若兩者不同,永遠以 `dev/SESSION_HANDOFF.md` 為準重生副本。
|
|
92
|
+
|
|
93
|
+
## 檢查是否安裝完整
|
|
94
|
+
|
|
95
|
+
如要檢查安裝是否完整,可在 Terminal 執行:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
npx @adamchanadam/agent-handoff-kit doctor
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
看到 `status: passed`,代表必要文件、基本結構與 `START_NEXT_SESSION_PROMPT.txt` 副本一致性通過檢查。
|
|
102
|
+
|
|
103
|
+
這個檢查只能確認文件結構,不代表 AI 已理解你的專案。真正開始工作前,仍應要求 AI 先讀入口文件並說明目前狀態。
|
|
104
|
+
|
|
105
|
+
## 會安裝甚麼
|
|
106
|
+
|
|
107
|
+
安裝工具會在你的專案中建立:
|
|
108
|
+
|
|
109
|
+
```text
|
|
110
|
+
AGENTS.md
|
|
111
|
+
CLAUDE.md
|
|
112
|
+
GEMINI.md
|
|
113
|
+
START_NEXT_SESSION_PROMPT.txt
|
|
114
|
+
dev/SESSION_HANDOFF.md
|
|
115
|
+
dev/SESSION_LOG.md
|
|
116
|
+
dev/PROJECT_INDEX.md
|
|
117
|
+
dev/PROJECT_DECISIONS.md
|
|
118
|
+
dev/DOC_SYNC_REGISTRY.md
|
|
119
|
+
dev/RULE_PACKS.md
|
|
120
|
+
dev/rules/*.md
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
| 文件 | 用途 |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `AGENTS.md` | AI 開工時最先讀的入口文件。 |
|
|
126
|
+
| `CLAUDE.md` | 讓 Claude Code 找到同一套入口。 |
|
|
127
|
+
| `GEMINI.md` | 讓 Gemini CLI 找到同一套入口。 |
|
|
128
|
+
| `START_NEXT_SESSION_PROMPT.txt` | 下次開工時可直接貼上的便利副本;由 handoff 產生。 |
|
|
129
|
+
| `dev/SESSION_HANDOFF.md` | 保存目前狀態、下一步、風險、驗收結果與下一次開工文字。 |
|
|
130
|
+
| `dev/SESSION_LOG.md` | 保存近期實際做過的事與檢查結果。主檔長期保持短小;N=11+ 嘅舊條目自動 archive 至 `dev/SESSION_LOG_archive/`,trace-back 用。接力靠 `SESSION_HANDOFF.md`,本檔屬冷資料層。 |
|
|
131
|
+
| `dev/PROJECT_INDEX.md` | 記錄專案檔案、必讀資料、外部來源與常用檢查。 |
|
|
132
|
+
| `dev/PROJECT_DECISIONS.md` | 保存項目嘅長期演進、決策、架構取捨、學習觀察。屬 warm 資料層 —— AI 開工**不需要讀**本檔;遇到「之前點解咁做」嘅問題時 AI 自己嚟搵。短期單一 task 項目本檔保持近空;長期項目 AI 喺收工時自動 maintain。 |
|
|
133
|
+
| `dev/DOC_SYNC_REGISTRY.md` | 記錄哪些文件改動後需要同步。 |
|
|
134
|
+
| `dev/RULE_PACKS.md` | 告訴 AI 不同任務應讀哪些工作規則。 |
|
|
135
|
+
| `dev/rules/*.md` | 按任務載入的細分工作規則。含 10 個 pack:safety / coding / writing / research / agent-governance / release / knowledge / communication / onboarding(v0.2.0 新加,新手第一次用時 AI 主動載入做 walk-through)/ **integrations**(v0.3.0 新加,外部工具治理 — Connectors / MCPs / Plugins / Skills 跨 session resilience + 機密分離原則)。 |
|
|
136
|
+
|
|
137
|
+
你不需要自己逐一閱讀全部文件。你的工作是描述目標;AI 的工作是讀入口文件、判斷要讀哪些資料,再告訴你它準備怎樣做。
|
|
138
|
+
|
|
139
|
+
## SESSION_LOG 嘅自動整理機制
|
|
140
|
+
|
|
141
|
+
長期使用後,`dev/SESSION_LOG.md` 唔會無止境膨脹。每次你講「收工」,AI 會自動執行 N 規則整理(N 代表 session 嘅 entry 數,N=1 為最新):
|
|
142
|
+
|
|
143
|
+
- **N=1–3**:最新三條 session 條目保留完整內容(safety buffer,萬一交接出錯仍有 fallback)。
|
|
144
|
+
- **N=4–10**:核心內容已被 `dev/SESSION_HANDOFF.md` 等真源吸收嘅條目,自動降為短索引(日期 + 標題 + 真源 anchor)。
|
|
145
|
+
- **N=11+**:自動 archive 入 `dev/SESSION_LOG_archive/archive_<批次>_<日期區間>.md`;主檔末尾留一份 archive index 做 trace-back 入口。
|
|
146
|
+
|
|
147
|
+
接力責任由 `dev/SESSION_HANDOFF.md` 對賬式更新承擔;`dev/SESSION_LOG.md` 屬 trace-back / 審計用嘅冷資料層。**新 AI session 開工唔需要讀完整 LOG**,只需要讀 `AGENTS.md` + `dev/SESSION_HANDOFF.md` + 索引文件就足夠接力。
|
|
148
|
+
|
|
149
|
+
所以你部電腦嘅 `dev/` 資料夾唔會被 session log 不停撐大,亦唔需要你手動清理。如果主檔意外膨脹(11 條以上未 archive,或單檔超過 1500 行),`doctor` 會喺輸出顯示一個 warning 提醒 AI 下次收工執行整理;但呢個只屬提醒,唔會令 `doctor` 失敗、亦唔阻擋安裝。
|
|
150
|
+
|
|
151
|
+
## 項目決策日誌
|
|
152
|
+
|
|
153
|
+
`dev/PROJECT_DECISIONS.md` 保存項目的長期演進、決策、架構取捨與學習觀察 narrative。屬 warm 資料層 —— AI 開工**不需要讀**本檔;當你問「之前為何這樣做」時,AI 自己會從這裡找答案。
|
|
154
|
+
|
|
155
|
+
- 短期 single-task 項目:本檔保持近空,你不需要 maintain
|
|
156
|
+
- 長期持續演進項目:AI 會在每次收工時自動 maintain
|
|
157
|
+
- HANDOFF 的「Confirmed Decisions」或同類 decisions section 累積至 30+ 條時,AI 自動 split 舊條目至此
|
|
158
|
+
- 觀察到任務需求演進、架構取捨、累積學習 pattern 時,AI 主動 append entry
|
|
159
|
+
|
|
160
|
+
本檔含 4 個固定 H2 section:
|
|
161
|
+
|
|
162
|
+
- **Evolution Timeline** —— 任務需求嘅長期演進
|
|
163
|
+
- **Decisions Archive** —— 累積決策嘅冷封存
|
|
164
|
+
- **Architecture Choices** —— 主要架構取捨同 rationale
|
|
165
|
+
- **Insights & Learnings** —— 多 session 累積嘅學習觀察
|
|
166
|
+
|
|
167
|
+
本檔同 SESSION_LOG 嘅 archive 機制屬同一套 hot / warm / cold 分層紀律 —— 你部電腦嘅 `dev/` 資料夾長期使用都唔會被無關 narrative 撐大,亦唔需要你手動清理。新手用戶完全唔需要打開本檔,亦唔需要記任何 schema —— 一切由 AI 自律執行。
|
|
168
|
+
|
|
169
|
+
## 外部工具治理
|
|
170
|
+
|
|
171
|
+
當你項目涉及外部工具(Notion、Google Drive、Dropbox、Slack、Linear、GitHub、HubSpot 等),Kit 提供完整跨 session 治理紀律 —— 但 **不教你點 install**(安裝行為由 Anthropic 官方文檔 + 各工具自身 setup guide 負責,屬中階用戶責任)。Kit 專注「**已裝好之後,點樣治理跨 session 穩定可用**」。
|
|
172
|
+
|
|
173
|
+
### Installed Integrations 登記表
|
|
174
|
+
|
|
175
|
+
`dev/PROJECT_INDEX.md` 內 `## Installed Integrations` section 係項目嘅外部工具能力 registry,4 個 subsection:
|
|
176
|
+
|
|
177
|
+
- **Connectors**(Anthropic 官方 vetted)—— 譬如 Notion / Drive / Slack 經 Claude Desktop Settings → Extensions 一鍵安裝
|
|
178
|
+
- **MCPs**(community / custom)—— 用戶自建或第三方 MCP server
|
|
179
|
+
- **Plugins**(Claude Code plugin bundle)—— 經 `/plugin` command 安裝嘅 bundle
|
|
180
|
+
- **Skills**(SKILL.md instruction set)—— 由 plugin 攜帶或直接安裝
|
|
181
|
+
|
|
182
|
+
加 `### Source-of-truth Architecture` sub-table 描述多層持久化分工 —— 譬如「Notion DB Index 記真源 metadata、本機 `reference/` 儲真源檔、Drive folder 做持久化參考檔 mirror、本機 `output/` 做 AI working draft」。
|
|
183
|
+
|
|
184
|
+
### 機密分離原則
|
|
185
|
+
|
|
186
|
+
**API key / OAuth token / 任何 credential value 永不寫入 `dev/*` 任何檔**。Credential 由 AI 工具自身 secure storage(OS Keychain / Credential Manager / AI tool config)管理,與 Kit 完全分離。Kit 嘅 doctor 對 `dev/PROJECT_INDEX.md` + `dev/SESSION_HANDOFF.md` + `dev/SESSION_LOG.md` 強制 grep 14 種 credential prefix patterns,命中即 `status: failed`。
|
|
187
|
+
|
|
188
|
+
### Connector-first default
|
|
189
|
+
|
|
190
|
+
新手第一次貼起步句進入 onboarding 後,AI 主動引問:「你已裝邊啲 Connector / MCP / Plugin / Skill 我可以用?」用戶 declare 後 AI 寫入 Installed Integrations registry,之後每次新 session 開工自動 verify availability + 跨 session leverage。當 declared Connector functional,AI 用直接 MCP tool call(譬如 `mcp__notion__*` 讀寫 Notion DB);unavailable 才 fallback paste packet。
|
|
191
|
+
|
|
192
|
+
### 跨 session 治理 lifecycle 6 階段
|
|
193
|
+
|
|
194
|
+
1. **First-contact declaration**(onboarding 階段,AI 主動引問)
|
|
195
|
+
2. **Initial recording**(寫入 PROJECT_INDEX `## Installed Integrations`)
|
|
196
|
+
3. **Cross-session handoff**(SESSION_HANDOFF `## Durable Anchors` 強制要求新 AI 讀本 section)
|
|
197
|
+
4. **Startup availability probe**(新 AI 開工自動 verify 每個 declared Integration)
|
|
198
|
+
5. **Mid-session drift handling**(auth 失靈即 surface,唔自動 fix,紀錄入 PROJECT_INDEX + SESSION_LOG)
|
|
199
|
+
6. **Multi-tool 環境 cross-tool 一致性**(PROJECT_INDEX declaration 屬 project-level,唔 lock 一個 AI tool)
|
|
200
|
+
|
|
201
|
+
詳細紀律見 `dev/rules/integrations.md`(新 session 涉外部工具時 AI 自動 load)。
|
|
202
|
+
|
|
203
|
+
## 工作模式
|
|
204
|
+
|
|
205
|
+
你不需要記規則包名稱,只要描述任務。AI 會按任務切換工作模式。
|
|
206
|
+
|
|
207
|
+
| 你的任務 | AI 應使用的工作規則 |
|
|
208
|
+
|---|---|
|
|
209
|
+
| 寫或改代碼、檢查錯誤、執行測試 | `coding`;涉及刪除、覆寫、Git、套件管理或外部服務時加 `safety` |
|
|
210
|
+
| 查資料、比較來源、整理證據 | `research` |
|
|
211
|
+
| 改 README、寫說明、整理文案 | `writing`,通常再加 `communication` |
|
|
212
|
+
| 整理 Notion、Google Drive 或知識庫 | `knowledge` |
|
|
213
|
+
| 準備發佈說明 | `release`;真正發佈、上傳或建立版本前必須加 `safety` |
|
|
214
|
+
| 改規則、改流程、整理交接 | `agent-governance`;先找既有真源,不盲目新增規則 |
|
|
215
|
+
|
|
216
|
+
原則是只讀當前任務需要的規則,不是每次讀全部文件。
|
|
217
|
+
|
|
218
|
+
## 安全護欄
|
|
219
|
+
|
|
220
|
+
就算你不懂代碼,這套工具也會要求 AI 在高風險操作前停下來講清楚。
|
|
221
|
+
|
|
222
|
+
- 禁止破壞性指令:例如 `rm -rf`、`git reset --hard`、強制推送、系統根路徑操作。
|
|
223
|
+
- 機密保護:`.env`、API key、token 不可印出、不可 commit、不可上傳。
|
|
224
|
+
- 查證不猜:用第三方 API、CLI、SDK 前先查官方文件;查不到就標示未核實。
|
|
225
|
+
- 權限不足就停手:檔案被鎖或沒有權限時,輸出手動操作清單,不嘗試繞過。
|
|
226
|
+
- 發佈需明確批准:tag、GitHub Release、npm publish、部署或上傳都不能因「準備好了」而自動執行。
|
|
227
|
+
|
|
228
|
+
## 已安裝舊版,或已有 AI 記憶文件?
|
|
229
|
+
|
|
230
|
+
如果你的專案已經裝過舊版 Agent Handoff Kit,或本來已有 `AGENTS.md`、`CLAUDE.md`、`GEMINI.md` 等 AI 記憶文件,先用最新版 CLI dry-run 預演會發生甚麼:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
npx @adamchanadam/agent-handoff-kit@latest upgrade --dry-run
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
確認沒有問題後,再執行:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
npx @adamchanadam/agent-handoff-kit@latest upgrade
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
`@latest` 代表使用 npm 上最新的 Agent Handoff Kit CLI。`upgrade` 則負責把專案內已安裝的 Kit 文件、規則與檢查結構安全更新。升級工具會保留既有檔案;能安全合併時才合併,不能安全合併時會報 conflict,不會靜默覆寫。
|
|
243
|
+
|
|
244
|
+
看到 `conflict` 不代表檔案壞掉。它只代表工具不能安全判斷怎樣合併,所以先停手,等你或 AI 判斷下一步。最簡單做法是把 dry-run 輸出貼給 AI,請它幫你判斷要保留、合併,還是手動修改。
|
|
245
|
+
|
|
246
|
+
## 版本提示
|
|
247
|
+
|
|
248
|
+
CLI 執行時會短暫檢查 npm 上是否有更新版本。若有新版,會顯示更新提示與 release notes 連結;若離線、網路逾時或檢查失敗,原本的 `init`、`upgrade`、`doctor` 仍會照常執行。
|
|
249
|
+
|
|
250
|
+
若你不想檢查更新,可設定:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
AGENT_HANDOFF_KIT_NO_UPDATE_CHECK=1
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## 語言使用
|
|
257
|
+
|
|
258
|
+
安裝後的核心指令文件預設使用英文,原因是不同 AI 工具對英文結構較穩定。這不是限制你的專案必須用英文。
|
|
259
|
+
|
|
260
|
+
你的交接筆記、任務說明和文件內容可以使用中文或其他語言。需要機器檢查的結構,會由模板內的 `ack:section:*` 與 `ack:field:*` 標記承擔。
|
|
261
|
+
|
|
262
|
+
## 原始碼倉庫驗收
|
|
263
|
+
|
|
264
|
+
以下指令供維護者檢查原始碼倉庫,不是一般用戶日常必須執行的步驟:
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
npm run qa:prototype
|
|
268
|
+
npm run qa:packs
|
|
269
|
+
npm run qa:upgrade
|
|
270
|
+
npm run qa:release
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
這些檢查涵蓋安裝、`doctor`、套件預演、過時字串、公開輸出污染標記、工作規則路由、升級安全,以及從安裝到收工再到下一次開工的流程模擬。
|
|
274
|
+
|
|
275
|
+
## 套件邊界
|
|
276
|
+
|
|
277
|
+
npm package 只包含安裝所需內容:
|
|
278
|
+
|
|
279
|
+
- `bin/`
|
|
280
|
+
- `runtime-core/`
|
|
281
|
+
- `packs/`
|
|
282
|
+
- `README.md`
|
|
283
|
+
- `LICENSE`
|
|
284
|
+
- `package.json`
|
|
285
|
+
|
|
286
|
+
GitHub Pages 上的兩個 onboarding 頁 —— [`agent-handoff-kit-intro.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-intro.html)(60 秒入門)與 [`agent-handoff-kit-guide.html`](https://adamchanadam.github.io/agent-handoff-kit/agent-handoff-kit-guide.html)(實操指南)—— 由原始碼倉庫根目錄發佈;兩個 HTML 與 `images/` 是原始碼倉庫資產,不會安裝到你的專案。
|
|
287
|
+
|
|
288
|
+
## 配合 Adam-AI-Instructions 使用
|
|
289
|
+
|
|
290
|
+
Agent Handoff Kit 同 [Adam-AI-Instructions](https://github.com/prompt-templates/Adam-AI-Instructions)(Meta Instruction for AI)配合使用效果最好。兩者分工互補,不重疊:
|
|
291
|
+
|
|
292
|
+
- **Adam-AI-Instructions** 負責 AI 喺**單一對話**內嘅做事規矩:語氣、做事優先序、回覆骨架、計算紀律、用語紀律、安全護欄、輸出層分工。屬「AI 應該點答你」嘅持久基準。
|
|
293
|
+
- **Agent Handoff Kit** 負責 AI 喺**對話之間**嘅接力:當前狀態、下一步、檔案登記、收工同下次開工。屬「AI 對話之間點記憶你個項目」嘅持久基準。
|
|
294
|
+
|
|
295
|
+
到該 repo 嘅「**五、Prompt 索引**」揀啱你 AI 工具嘅 prompt(Claude Cowork / Claude Code / OpenAI Codex / ChatGPT 等),複製對應子目錄嘅 `prompt.md` 全文,貼入 AI 工具嘅 system prompt、personal preferences 或 project instructions(例如 Claude Cowork 的 Global Instructions、Claude Code 的 `~/.claude/CLAUDE.md`、ChatGPT 的 Custom Instructions)。然後再喺項目資料夾跑 `npx @adamchanadam/agent-handoff-kit init` 安裝呢套 Kit。兩者配合就能涵蓋「單次對話質素」+「跨對話接力」兩個維度。
|
|
296
|
+
|
|
297
|
+
## 目前限制
|
|
298
|
+
|
|
299
|
+
- `v0.3.0` 是 GitHub 與 npm 同步發佈版本。
|
|
300
|
+
- 這是早期可用版本,尚未宣稱完整穩定。
|
|
301
|
+
- 升級合併仍是窄範圍策略,不是完整的複雜合併工具。
|
|
302
|
+
- `doctor` 能檢查結構,不能代替 AI 對專案內容的理解。
|
|
303
|
+
- 未取得明確批准前,不應因安裝成功而自動建立新版本、發佈或上傳任何內容。
|