Skip to content

Commit 6315983

Browse files
morningmanclaude
andcommitted
[doc](connector) add project tracking system for catalog SPI migration
This multi-month refactor needs persistent state for progress, decisions, risks, and cross-session agent handoff. Establishes a file-based tracking system including dashboard, ADR decision log, deviation log, risk register, per-stage task files, per-connector tracking, and an agent collaboration playbook covering context budget / subagent usage / handoff norms. Closes 18 design decisions (D-001..D-018) and registers 14 risks (R-001..R-014). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent 68d4eb3 commit 6315983

20 files changed

Lines changed: 3948 additions & 0 deletions

‎plan-doc/00-connector-migration-master-plan.md‎

Lines changed: 369 additions & 0 deletions
Large diffs are not rendered by default.

‎plan-doc/01-spi-extensions-rfc.md‎

Lines changed: 1248 additions & 0 deletions
Large diffs are not rendered by default.

‎plan-doc/AGENT-PLAYBOOK.md‎

Lines changed: 280 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
# Agent 协作规范 — Context 管理与最佳实践
2+
3+
> 本项目是大型多阶段重构,预计跨数月、上百个 PR、可能跨数十个 LLM agent session。
4+
> 本规范旨在让"无论哪一次 session、由哪个 agent 接手,都能高质量推进",**核心是 context 管理**。
5+
6+
---
7+
8+
## 一、为什么需要规范
9+
10+
LLM agent 协作的三大失效模式:
11+
12+
1. **Context 中毒**:单 session 累积太多无关信息,模型注意力分散、决策质量下降、出现幻觉。
13+
2. **认知断层**:换 session 后失去前情,重复探索 / 推翻已有决策 / 重新发明轮子。
14+
3. **维护脱节**:代码改了文档不改,下次进 session 时基于过时文档做错误判断。
15+
16+
本规范用三类工具应对:
17+
- **Context 预算与监控**(§2)—— 防失效模式 1
18+
- **Subagent 与 Handoff**(§3、§4)—— 防失效模式 1、2
19+
- **强制纪律**(§5)—— 防失效模式 3
20+
21+
---
22+
23+
## 二、Context 预算
24+
25+
### 2.1 单 session 预算
26+
27+
| Context 使用率 | 状态 | 推荐行为 |
28+
|---|---|---|
29+
| **0–40%** | 🟢 健康 | 正常工作,可以做任何任务 |
30+
| **40–60%** | 🟢 健康偏高 | 开始倾向于把"独立的探索 / 大文件读"转给 subagent |
31+
| **60–75%** | 🟡 警觉 | **不再读 ≥500 行的整文件**;只做精确 grep / offset+limit read;准备 handoff 草稿 |
32+
| **75–85%** | 🟠 高危 | **停止接新任务**;完成手头 1 个原子工作;写 HANDOFF.md;通知用户切 session |
33+
| **>85%** | 🔴 危险 | **只做记录性工作**(更新 PROGRESS / HANDOFF);不再做任何决策 / 代码生成 |
34+
35+
> Claude Code 中可通过 `/context` 查看当前用量;如不可见,按"已发起的工具调用数 + 已读文件总行数"粗略估算。
36+
37+
### 2.2 用户对 session 的隐式预期
38+
39+
如果用户在一次 session 中要求"重构 X 模块 + 写文档 + 提交 PR",agent 应:
40+
41+
- 评估 context 占用:单凭 RFC + 现有代码探索就可能吃掉 30-40%
42+
- **主动报告**:在开始执行前告知 "此任务预计占用约 40% context,是否需要先写 handoff 占位以便分两个 session 完成?"
43+
44+
### 2.3 节省 context 的硬性技巧
45+
46+
1. **永远不要 `Read` 整个 >1000 行的文件** —— 用 `grep` 定位行号,再用 `offset + limit` 精读。
47+
2. **永远不要重复 grep 同一个 pattern** —— 在 session 心智里记住结果。
48+
3. **避免 `cat` / `find -type f -name '*.java'` 全量列举** —— 用更精准的 grep / find 加过滤。
49+
4. **避免 `git log -p`** —— 用 `git log --oneline -20`,需要 diff 再单独 `git show <hash>`。
50+
5. **大文件总结优先用 subagent**(见 §3):让 subagent 读 5000 行返回 200 字总结。
51+
52+
---
53+
54+
## 三、Subagent 使用规范
55+
56+
### 3.1 何时**必须**用 subagent
57+
58+
- **跨 5+ 文件的代码搜索 / 调研**(如"找出 fe-core 中所有 instanceof HMSExternalCatalog 的地方")
59+
- **读取 >1000 行的单文件后只取关键信息**(如 IcebergMetadataOps.java 1247 行,只需了解 createTable 路径)
60+
- **独立的、不影响主线决策的小重构**(如"批量改 import 路径",给 subagent prompt + 文件列表,背景执行)
61+
- **独立的代码评审**(如"review 这次 PR 的安全性",需要重读大量上下文)
62+
63+
### 3.2 何时**不要**用 subagent
64+
65+
- 主线决策环节 —— subagent 给的建议你最终还是要消化,不如自己做
66+
- 1-2 次 grep / read 就能解决的简单查找 —— 启动 subagent 的固定开销不值得
67+
- 需要持续交互的探索(边读边问"那 X 呢")—— subagent 一次性输出,互动不便
68+
- 涉及"修改后立即验证"的小改动 —— 主 session 闭环更快
69+
70+
### 3.3 写 subagent prompt 的硬性规则
71+
72+
```
73+
1. 自包含:不能假设 subagent 知道主线对话内容。明确说"working directory: /...",
74+
"background: 这是 XX 项目的 YY 阶段,目标是 ZZ"。
75+
2. 输出格式约束:明确"返回 markdown 表格 / 总字数 ≤ 500 / 只列文件路径不带代码"。
76+
3. 范围约束:明确"只看 fe-core 目录"、"忽略 test 目录"、"不读 README"。
77+
4. 决策权约束:明确"只调研,不做任何修改"或"可以修改 X 但不能动 Y"。
78+
5. 一次性:避免让 subagent 内部继续延伸调研——主 session 来决定下一步。
79+
```
80+
81+
### 3.4 Subagent 类型选择(Claude Code 内)
82+
83+
| 任务类型 | 推荐 subagent | 备注 |
84+
|---|---|---|
85+
| 大范围代码搜索 | `Explore` | 只读、快、context 隔离 |
86+
| 多步独立工作 | `general-purpose` | 可以执行 grep / read / edit |
87+
| 实现计划设计 | `Plan` | 只产出方案不写代码 |
88+
| 都不适合 | `claude`(默认)| 兜底 |
89+
90+
### 3.5 Background 模式
91+
92+
长耗时任务(如 `mvn test`、跨模块 build)使用 `run_in_background: true`,主 session 不被阻塞。完成时会自动通知,**不要 sleep 轮询**。
93+
94+
---
95+
96+
## 四、Handoff(跨 session 接管)
97+
98+
### 4.1 何时**必须**写 handoff
99+
100+
- Context 使用率 ≥ 70%(§2.1)
101+
- 当前 P 阶段结束(如 P0 → P1 切换)
102+
- 工作天然分段(如"下周再继续")
103+
- 出现长时间阻塞,等其他人 review / 等 CI 跑(≥4 小时)
104+
- 用户主动说"今天到此为止"
105+
106+
### 4.2 何时**不需要**写 handoff
107+
108+
- 同一 session 内自然继续
109+
- Context < 50% 且任务还很短
110+
111+
### 4.3 Handoff 文档结构
112+
113+
见 [`HANDOFF.md`](./HANDOFF.md) 模板。核心字段:
114+
115+
1. **本 session 完成了什么**(具体到 task ID、PR、commit)
116+
2. **当前正在做的事是否完整**(如果中途停的,写明卡在哪个文件、哪一行)
117+
3. **关键认知 / 临时发现**(如"刚发现 X 类的 Y 方法有意外副作用"——这种东西不写下来下次会重复踩坑)
118+
4. **下一个 session 第一件事做什么**(精确到 task ID + 第一行代码 / 命令)
119+
5. **当前 session 没解决但需要标记的问题**(不是 TODO 而是"开放问题")
120+
121+
### 4.4 Handoff 文件存放
122+
123+
- 单个滚动文件 `plan-doc/HANDOFF.md`
124+
- 每次 session 结束时**覆盖式更新**
125+
- 历史 handoff 通过 `git log plan-doc/HANDOFF.md` 查看
126+
- **不要**建 `handoffs/2026-05-24.md` 这种归档目录 —— git history 已经胜任
127+
128+
### 4.5 接管新 session 的开场流程
129+
130+
新 session 开始第一件事(**所有 agent 必须遵守**):
131+
132+
```
133+
1. Read plan-doc/PROGRESS.md ← 全局状态
134+
2. Read plan-doc/HANDOFF.md ← 上次留言
135+
3. 如果 HANDOFF 标记当前 task:
136+
Read plan-doc/tasks/Pn-*.md 中对应 task 块
137+
4. 用一句话向用户复述:"上次 session 做完了 X,下一步是 Y,对吗?"
138+
5. 等用户确认后开始
139+
```
140+
141+
**不要**在没读 HANDOFF 的情况下问"我们上次做到哪了" —— 这是失败模式。
142+
143+
---
144+
145+
## 五、强制纪律
146+
147+
### 5.1 文档同步纪律
148+
149+
每次完成 task:
150+
1. 更新 `tasks/Pn-*.md` 对应 task 状态
151+
2. 更新 `PROGRESS.md` §三和§四
152+
3. 更新 `connectors/<name>.md`(如果该 task 属于某个连接器)
153+
4. 如果产生新决策 → `decisions-log.md` 新增 D-NNN
154+
5. 如果发现偏差 → `deviations-log.md` 新增 DV-NNN
155+
156+
**5 步缺一不可**。否则下次 session 看到的状态就是错的。
157+
158+
### 5.2 RFC 修改纪律
159+
160+
任何修改 `01-spi-extensions-rfc.md` 的行为:
161+
1. 先在 `deviations-log.md` 或 `decisions-log.md` 留痕(区别见 [README §3.1](./README.md))
162+
2. 在 RFC 该节加 `(D-NNN / DV-NNN 修订 YYYY-MM-DD)`脚注
163+
3. 不要 silent edit
164+
165+
### 5.3 Task ID 纪律
166+
167+
- Task ID 一旦分配**永不复用**
168+
- 删除的 task 标 `[deleted YYYY-MM-DD]` 保留占位行
169+
- 重命名 task 不改 ID
170+
171+
### 5.4 提交信息纪律
172+
173+
PR title 第一行必须 `[Pn-Tnn] <subject>`,例如:
174+
```
175+
[P0-T03] Implement ConnectorMetaInvalidator interface
176+
```
177+
178+
---
179+
180+
## 六、Anti-Patterns(绝对禁止)
181+
182+
| 反模式 | 为什么禁止 | 正确做法 |
183+
|---|---|---|
184+
| 一个 session 又读 RFC、又改 SPI、又写实现、又跑测试 | Context 爆炸;决策质量下降 | 拆 session:阅读/设计 → handoff → 实现 → handoff → 验证 |
185+
| 跨 session 凭记忆继续工作 | 模型完全没记忆,认知断层 | 强制读 HANDOFF |
186+
| Subagent 也用来做"小事" | 启动开销大于收益 | <2 次 grep 直接主线做 |
187+
| 把 RFC 当 PROGRESS 用 | RFC 是设计稳定文档,频繁更新会污染 git history | PROGRESS / tasks / handoff 才是状态文件 |
188+
| Handoff 写得像周报 | 周报对用户有用,对下一个 agent 无用 | 写"下一步第一行命令是什么"才有用 |
189+
| 多个 session 并发改同一 task | 重复劳动 / 文档冲突 | 同一时刻一个 task 只一个 owner |
190+
| Decision / Deviation 直接写到 RFC 里不进 log | 失去追溯性 | 先 log 再改 RFC |
191+
192+
---
193+
194+
## 七、各类 session 的典型节奏(参考)
195+
196+
### 7.1 "设计 + 评审" session(高密度阅读)
197+
198+
```
199+
开场:Read PROGRESS + HANDOFF (3% context)
200+
主体:Read 3-5 个核心文件 + RFC 某节 (25% context)
201+
↓
202+
与用户来回讨论 5-10 轮 (+30% context)
203+
↓
204+
Edit / Write 文档(RFC 修改、decision 记录) (+10% context)
205+
收尾:更新 PROGRESS + 写 HANDOFF (+5% context)
206+
─────────
207+
~73% 健康终止
208+
```
209+
210+
### 7.2 "代码实现" session(中等密度)
211+
212+
```
213+
开场:Read PROGRESS + HANDOFF + 对应 task (5%)
214+
主体:Read 现有相关代码(精读,offset+limit) (15%)
215+
↓
216+
Write / Edit 实现 (+15%)
217+
↓
218+
Run tests(如可),修复错误 (+15%)
219+
收尾:更新 task 状态 + PROGRESS + git commit + HANDOFF (+10%)
220+
─────────
221+
~60%
222+
```
223+
224+
### 7.3 "调研 / 探索" session(高度依赖 subagent)
225+
226+
```
227+
开场:Read PROGRESS + HANDOFF (3%)
228+
主体:dispatch subagent 做 5-10 路并行调研 (+10% 主线 +50% subagent)
229+
↓
230+
综合 subagent 结果做决策 (+10%)
231+
↓
232+
Write 调研结论文档(如新 RFC) (+10%)
233+
收尾:更新 PROGRESS + decisions-log + HANDOFF (+5%)
234+
─────────
235+
~38%
236+
```
237+
238+
---
239+
240+
## 八、Context "重启"策略
241+
242+
如果 context 已经超 75% 但任务还没做完:
243+
244+
1. **优先保存状态**:立即写 HANDOFF.md,详细到下一行代码该写什么
245+
2. **完成原子收尾**:当前正在 Edit 的文件**改完 + 保存**,不要留半截
246+
3. **更新 PROGRESS**:把已完成的 task 标 ✅
247+
4. **提醒用户切 session**:"Context 已 ~78%,建议开新 session 继续。HANDOFF 已写好,新 session 第一句话发 'continue from handoff' 即可。"
248+
5. **不要硬撑**:每多用 1% context 都在降低质量
249+
250+
---
251+
252+
## 九、Multi-agent 协作的边界
253+
254+
本项目原则上一个 task 由一个 agent 推进,但允许:
255+
256+
- **并行 subagent**:调研 / 测试 / build 等独立任务并行
257+
- **审计 subagent**:让一个 subagent 审核主线工作(如"以挑刺 reviewer 视角看这次改动")
258+
- **接力**:handoff 后由完全不同的 agent / 人接手
259+
260+
**不允许**:
261+
- 同时两个 agent 改同一 task
262+
- Subagent 跨阶段(subagent 只做本 session 的工作,不要让 subagent 自己写 HANDOFF)
263+
264+
---
265+
266+
## 十、面向"未来 agent"的元规则
267+
268+
如果你(未来 agent)发现本规范本身需要修改:
269+
270+
1. 不要直接改本文件 —— 先在 `deviations-log.md` 写 `DV-NNN: AGENT-PLAYBOOK 规则 X 在场景 Y 不适用`
271+
2. 与用户讨论后再修改本文件
272+
3. 修改时在文末 §十一 加版本号 + 变更说明
273+
274+
---
275+
276+
## 十一、版本
277+
278+
| 版本 | 日期 | 变更 |
279+
|---|---|---|
280+
| v1 | 2026-05-24 | 初版(与 README、PROGRESS、HANDOFF 同时建立) |

0 commit comments

Comments
 (0)