add-coder 0.1.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.
Files changed (97) hide show
  1. package/README.md +50 -0
  2. package/bin/add-coder.js +2 -0
  3. package/dist/index.d.ts +1 -0
  4. package/dist/index.js +576 -0
  5. package/package.json +64 -0
  6. package/templates/adapters/claude/hooks/doc-format-guard.sh +17 -0
  7. package/templates/adapters/claude/hooks/notification.sh +9 -0
  8. package/templates/adapters/claude/hooks/permission-gate.sh +18 -0
  9. package/templates/adapters/claude/hooks/post-tool-failure.sh +10 -0
  10. package/templates/adapters/claude/hooks/post-tool-use.sh +18 -0
  11. package/templates/adapters/claude/hooks/pre-compact.sh +14 -0
  12. package/templates/adapters/claude/hooks/pre-tool-use.sh +28 -0
  13. package/templates/adapters/claude/hooks/prompt-submit.sh +16 -0
  14. package/templates/adapters/claude/hooks/review-checklist.sh +10 -0
  15. package/templates/adapters/claude/hooks/session-start.sh +23 -0
  16. package/templates/adapters/claude/hooks/stop-check.sh +10 -0
  17. package/templates/adapters/claude/hooks/subagent-guard.sh +15 -0
  18. package/templates/adapters/claude/mcp.json +13 -0
  19. package/templates/adapters/claude/settings.json +125 -0
  20. package/templates/adapters/qoder/hooks/doc-format-guard.sh +164 -0
  21. package/templates/adapters/qoder/hooks/lib/context-inject.sh +96 -0
  22. package/templates/adapters/qoder/hooks/lib/state-detect.sh +104 -0
  23. package/templates/adapters/qoder/hooks/lib/vocabulary.sh +49 -0
  24. package/templates/adapters/qoder/hooks/notification.sh +22 -0
  25. package/templates/adapters/qoder/hooks/permission-gate.sh +8 -0
  26. package/templates/adapters/qoder/hooks/post-tool-failure.sh +8 -0
  27. package/templates/adapters/qoder/hooks/post-tool-use.sh +20 -0
  28. package/templates/adapters/qoder/hooks/pre-compact.sh +12 -0
  29. package/templates/adapters/qoder/hooks/pre-tool-use.sh +77 -0
  30. package/templates/adapters/qoder/hooks/prompt-submit.sh +72 -0
  31. package/templates/adapters/qoder/hooks/review-checklist.sh +157 -0
  32. package/templates/adapters/qoder/hooks/session-start.sh +16 -0
  33. package/templates/adapters/qoder/hooks/stop-check.sh +71 -0
  34. package/templates/adapters/qoder/hooks/subagent-guard.sh +11 -0
  35. package/templates/adapters/qoder/mcp.json +13 -0
  36. package/templates/adapters/qoder/settings.json +125 -0
  37. package/templates/adapters/qoder/sync-policy.json +18 -0
  38. package/templates/adapters/vscode/extensions.json +5 -0
  39. package/templates/adapters/vscode/launch.json +16 -0
  40. package/templates/adapters/vscode/settings.json +16 -0
  41. package/templates/adapters/vscode/tasks.json +38 -0
  42. package/templates/core/agents/add-flow-guardian.md +276 -0
  43. package/templates/core/agents/add-orchestrator.md +217 -0
  44. package/templates/core/plans/2026-07/08/farm-agent-add-coder-npm-package-add-route-v1.md +323 -0
  45. package/templates/core/plans/2026-07/08/farm-agent-add-coder-npm-package-handoff-v1.md +678 -0
  46. package/templates/core/plans/2026-07/08/farm-agent-add-coder-npm-package-plan-v1.md +785 -0
  47. package/templates/core/prisma/add.prisma +34 -0
  48. package/templates/core/reports/REPORT-WORKFLOW.md +250 -0
  49. package/templates/core/reports/boundary-runtime-report.md +134 -0
  50. package/templates/core/reports/code-review-combined-report.md +227 -0
  51. package/templates/core/reports/code-review-fix-verification-report.md +505 -0
  52. package/templates/core/reports/code-review-suggestions.md +66 -0
  53. package/templates/core/reports/index.md +57 -0
  54. package/templates/core/reports/runtime-report/gateway.md +741 -0
  55. package/templates/core/rules/project_rules.md +905 -0
  56. package/templates/core/rules/theory-practice-map.toml +105 -0
  57. package/templates/core/scripts/mcp-server.ts +3492 -0
  58. package/templates/core/skills/add-paradigm/SKILL.md +1086 -0
  59. package/templates/core/skills/session-init/SKILL.md +215 -0
  60. package/templates/core/specs/farm-agent-add-coder-npm-package/checklist.md +125 -0
  61. package/templates/core/specs/farm-agent-add-coder-npm-package/spec.md +343 -0
  62. package/templates/core/specs/farm-agent-add-coder-npm-package/tasks.md +203 -0
  63. package/templates/core/templates/01-/346/236/266/346/236/204//343/200/212ADD/345/274/200/345/217/221/345/267/245/344/275/234/350/267/257/345/276/204/344/270/216/346/226/207/346/241/243/345/215/217/345/220/214/350/247/204/350/214/203/343/200/213.md +386 -0
  64. package/templates/core/templates/TERMINOLOGY.md +81 -0
  65. package/templates/core/templates/add-route-template-heavyweight.md +288 -0
  66. package/templates/core/templates/add-route-template.md +242 -0
  67. package/templates/core/templates/add-route-template.schema.json +35 -0
  68. package/templates/core/templates/checklist-template.md +72 -0
  69. package/templates/core/templates/checklist-template.schema.json +20 -0
  70. package/templates/core/templates/fix-verification-template.md +132 -0
  71. package/templates/core/templates/fix-verification-template.schema.json +54 -0
  72. package/templates/core/templates/handoff-multi-round-template.md +295 -0
  73. package/templates/core/templates/handoff-multi-round.schema.json +48 -0
  74. package/templates/core/templates/handoff-single-round-template.md +145 -0
  75. package/templates/core/templates/handoff-single-round.schema.json +92 -0
  76. package/templates/core/templates/index.md +60 -0
  77. package/templates/core/templates/report-template.md +126 -0
  78. package/templates/core/templates/report-template.schema.json +69 -0
  79. package/templates/core/templates/review-implementation-template.md +66 -0
  80. package/templates/core/templates/review-implementation-template.schema.json +58 -0
  81. package/templates/core/templates/review-runtime-template.md +73 -0
  82. package/templates/core/templates/review-runtime-template.schema.json +47 -0
  83. package/templates/core/templates/review-template.md +37 -0
  84. package/templates/core/templates/review-template.schema.json +42 -0
  85. package/templates/core/templates/runtime-report-template.md +73 -0
  86. package/templates/core/templates/runtime-report-template.schema.json +48 -0
  87. package/templates/core/templates/simple-plan-template.md +166 -0
  88. package/templates/core/templates/simple-plan-template.schema.json +109 -0
  89. package/templates/core/templates/spec-template.md +22 -0
  90. package/templates/core/templates/spec-template.schema.json +41 -0
  91. package/templates/core/templates/standard-plan-template.md +96 -0
  92. package/templates/core/templates/standard-plan-template.schema.json +73 -0
  93. package/templates/core/templates/tasks-template.md +54 -0
  94. package/templates/core/templates/tasks-template.schema.json +43 -0
  95. package/templates/core/tools/README.md +361 -0
  96. package/templates/core/vocabulary/add-governance-vocabulary.md +370 -0
  97. package/templates/shared/hooks-lib/common.sh +22 -0
@@ -0,0 +1,72 @@
1
+ # Checklist
2
+
3
+ > **证据规范**:每项 [x] 必须附带可验证证据。不得空勾选、不得推测通过。
4
+ > - `[T]` = 编译期验证—证据: 命令+结果(如 `tsc=0` / `vitest 18/18`)
5
+ > - `[R]` = 运行时验证—证据: 部署后确认(如 `curl 200`)
6
+ > - `[E]` = 静态检查—证据: grep/diff 输出
7
+ >
8
+ > **审计链(证据→devlog→checklist)**:
9
+ > - 初验规则: 先找证据(命令+结果)→ 调 `record_dev_operation` 落库 → 将返回的真实 cuid(25位)写入 checklist。**禁止抄写 `cmq...` 占位符**。
10
+ > - 复验规则: 先查 checklist 是否已有真实审计 ID → 重新验证证据 → 证据一致则不复写 devlog日志(走mcp),不一致则追写新 devlog(新 cuid)
11
+
12
+ ## 一、编译与 Lint 门禁
13
+
14
+ - [ ] [T] 检查项1 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid,**禁止写 `cmq...` 占位符**)
15
+ - [ ] [T] 检查项2 — 证据: (待填写)|审计: (初验从 record_dev_operation 返回值写入真实 cuid,**禁止写 `cmq...` 占位符**)
16
+
17
+ ## ADD 规则合规检查
18
+
19
+ - [ ] [T] ESLint 零 error — 证据: `npx eslint src/ 2>&1 | tail -5` 结果包含 `✖ 0 problems` 或无 error 行
20
+ - [ ] [E] ADD-1 可观测性优先 — 证据: `grep -c 'agentAudit' src/agents/nodes/`
21
+ - [ ] [E] ADD-2 打点标记对称 — 证据: check_phase_symmetry 结果
22
+ - [ ] [E] ADD-4 三通道输出 — 证据: console + file + DB 三通道确认
23
+ - [ ] [E] ADD-5 审计数据即业务数据 — 证据: query_audit_logs 回查
24
+ - [ ] [E] Plan/Spec 一致性 — 证据: check_spec_sync 结果
25
+ - [ ] [E] Plan/Spec 修订记录 — 证据: record_dev_operation 审计ID
26
+
27
+ ## 跨项目联调检查(涉及多仓库时必做)
28
+
29
+ > `[T]` = 编译期可验证(AI 可在代码环节直接检查)
30
+ > `[R]` = 运行时验证(需部署运行后才能确认,自动流转到 review-runtime.md)
31
+
32
+ ### 格式契约
33
+
34
+ - [T] 所有跨系统 API:发送方参数类型 = 接收方解析类型,字段名一致
35
+ - [T] 响应 Content-Type 匹配客户端解析器(JSON vs `text/event-stream` vs NDJSON)
36
+
37
+ ### 框架版本
38
+
39
+ - [T] 确认 `package.json` 主版本号,查 breaking changes
40
+ - [R] 编译产物 mtime 晚于源码(如 `.next/server/middleware.js` ≥ `src/proxy.ts`)
41
+
42
+ ### 数据模型
43
+
44
+ - [R] Prisma 外键字段对应的表中有记录存在
45
+ - [T] `create()` 的 `userId` 等字段是真实存在的 ID,不是硬编码字符串
46
+
47
+ ### 环境变量
48
+
49
+ - [T] `npm run` 命令 → `--mode` → `.env.*` → 每个变量的值逐项验证
50
+ - [T] 三套环境(dev/local/prod)指向正确后端地址
51
+
52
+ ### API 选择
53
+
54
+ - [T] 模块导出多个相似函数时,确认选的是场景匹配的(同步版 vs 流式版 vs 批处理版)
55
+
56
+ ### E2E curl
57
+
58
+ - [R] 用有效凭证对每个端点 curl,检查 HTTP 状态码 + 响应格式
59
+ - [R] OPTIONS 预检 CORS 头正确
60
+
61
+ ---
62
+
63
+ > **流程衔接(AI 执行指令)**:
64
+ >
65
+ > 当所有 `[T]` 编译期检查项均为 `[x]` 时(`[R]` 项可保持 `[ ]`),AI 必须执行:
66
+ >
67
+ > 1. **读取** `review-implementation-template.md`,逐项填写实现审查内容
68
+ > 2. **读取** `review-runtime-template.md`,复制为 `.qoder/reviews/{project}-review-runtime.md`
69
+ > - 替换占位符(标题、关联文档路径)
70
+ > - §1 发现列表初始化为 "尚无运行时发现"
71
+ > - §1 末尾自动插入本 checklist 中所有 `[R]` 项的清单,标记为 "待运行时验证"
72
+ > 3. **提示用户**:"review-runtime.md 已就绪,包含 N 项运行时验证。部署后 `npm run dev` 启动时会扫描此文件。"
@@ -0,0 +1,20 @@
1
+ {
2
+ "template": "checklist-template.md",
3
+ "sections": [
4
+ {
5
+ "id": "audit_note",
6
+ "heading": "审计链(证据→devlog→checklist)",
7
+ "required": true
8
+ },
9
+ {
10
+ "id": "compile",
11
+ "heading": "## 一、编译与 Lint 门禁",
12
+ "required": true
13
+ }
14
+ ],
15
+ "placeholders": [],
16
+ "forbidden_terms": [ "Phase",
17
+ "阶段",
18
+ "步骤"
19
+ ]
20
+ }
@@ -0,0 +1,132 @@
1
+ # {项目名} Code Review 修复验证对照报告
2
+
3
+ > 生成时间:{YYYY-MM-DD}(第 {N} 次验证)
4
+ > 源报告:`{combined-report.md}`({n} 个问题)
5
+ > 验证方式:{逐文件读取 / diff 对比 / 运行时验证}
6
+
7
+ ---
8
+
9
+ ## 总览
10
+
11
+ | 状态 | 数量 | 占比 |
12
+ |------|------|------|
13
+ | ✅ 已修复 | {n} | {p}% |
14
+ | ⚠️ 部分修复 | {n} | {p}% |
15
+ | ❌ 仍存在 | {n} | {p}% |
16
+ | **总计** | **{n}** | **100%** |
17
+
18
+ ---
19
+
20
+ ## 逐条对照
21
+
22
+ ---
23
+
24
+ ### 一、{分类名}({n} 项)
25
+
26
+ #### #{issue编号} {问题标题} → ✅ 已修复
27
+
28
+ - **文件**: [`{file}:{line}`](file://{path}#L{line})
29
+ - **原问题**:
30
+
31
+ ```typescript
32
+ // 修复前的代码
33
+ {原始问题代码}
34
+ ```
35
+
36
+ - **当前代码**:
37
+
38
+ ```typescript
39
+ // 修复后的代码
40
+ {修复后代码}
41
+ ```
42
+
43
+ - **判定**: ✅ 已修复
44
+
45
+ ---
46
+
47
+ #### #{issue编号} {问题标题} → ❌ 仍存在
48
+
49
+ - **文件**: [`{file}:{line}`](file://{path}#L{line})
50
+ - **原问题**:
51
+
52
+ {问题描述}
53
+
54
+ - **当前代码**:
55
+
56
+ ```typescript
57
+ {仍存在的问题代码}
58
+ ```
59
+
60
+ - **判定**: ❌ 仍存在
61
+ - **未修复原因**: {说明}
62
+
63
+ ---
64
+
65
+ #### #{issue编号} {问题标题} → ⚠️ 部分修复
66
+
67
+ - **文件**: [`{file}:{line}`](file://{path}#L{line})
68
+ - **原问题**:
69
+
70
+ {问题描述}
71
+
72
+ - **当前代码**:
73
+
74
+ ```typescript
75
+ {部分修复后的代码}
76
+ ```
77
+
78
+ - **判定**: ⚠️ 部分修复
79
+ - **遗留**: {哪些部分尚未处理}
80
+
81
+ ---
82
+
83
+ ## 状态汇总表
84
+
85
+ | # | 分类 | 问题 | 当前文件 | 状态 |
86
+ |---|------|------|------|:----:|
87
+ | {1} | {分类} | {标题} | {文件} | ✅ |
88
+ | {2} | {分类} | {标题} | {文件} | ❌ |
89
+ | {3} | {分类} | {标题} | {文件} | ⚠️ |
90
+
91
+ ---
92
+
93
+ ## 本验证周期发现的重构变化
94
+
95
+ | 变化 | 旧文件 | 新文件 |
96
+ |------|--------|--------|
97
+ | {变化描述} | `{旧文件}` | `{新文件}` |
98
+
99
+ ---
100
+
101
+ ## 修复优先级
102
+
103
+ | 优先级 | 问题 | 说明 |
104
+ |--------|------|------|
105
+ | ~~P0~~ | ~~{已修复的 P0 问题}~~ | ~~已修复~~ |
106
+ | P1 | {仍存在的 P1 问题} | {当前状态说明} |
107
+ | P2 | {仍存在的 P2 问题} | {当前状态说明} |
108
+ | P3 | {仍存在的 P3 问题} | {当前状态说明} |
109
+
110
+ ---
111
+
112
+ ## 修复趋势
113
+
114
+ | 维度 | 上次 | 本次 | 变化 |
115
+ |------|:----:|:----:|:----:|
116
+ | 安全 | {n} | {n} | {+n/-n} |
117
+ | 架构 | {n} | {n} | {+n/-n} |
118
+ | 健壮性 | {n} | {n} | {+n/-n} |
119
+ | 整洁 | {n} | {n} | {+n/-n} |
120
+ | 运维 | {n} | {n} | {+n/-n} |
121
+ | **合计** | **{n}** | **{n}** | **{+n/-n}** |
122
+
123
+ ---
124
+
125
+ ## 运行时验证
126
+
127
+ > 以下 Issue 已通过 Runtime Report 子系统进行运行时验证。
128
+
129
+ | Issue | 运行时来源 | 验证结果 |
130
+ |-------|-----------|:--------:|
131
+ | {RPT-{id}} | `{{projectName}}-runtime-report/{subsystem}.md` | ✅ 未复现 |
132
+ | {RPT-{id}} | `{{projectName}}-runtime-report/{subsystem}.md` | ❌ 仍断裂 |
@@ -0,0 +1,54 @@
1
+ {
2
+ "template": "fix-verification-template.md",
3
+ "sections": [
4
+ {
5
+ "id": "overview",
6
+ "heading": "## 总览",
7
+ "required": true
8
+ },
9
+ {
10
+ "id": "details",
11
+ "heading": "## 逐条对照",
12
+ "required": true
13
+ },
14
+ {
15
+ "id": "summary",
16
+ "heading": "## 状态汇总表",
17
+ "required": true
18
+ },
19
+ {
20
+ "id": "refactor",
21
+ "heading": "## 本验证周期发现的重构变化",
22
+ "required": false
23
+ },
24
+ {
25
+ "id": "priority",
26
+ "heading": "## 修复优先级",
27
+ "required": true
28
+ },
29
+ {
30
+ "id": "trend",
31
+ "heading": "## 修复趋势",
32
+ "required": false
33
+ },
34
+ {
35
+ "id": "runtime",
36
+ "heading": "## 运行时验证",
37
+ "required": false
38
+ }
39
+ ],
40
+ "placeholders": [
41
+ "{项目名}",
42
+ "{YYYY-MM-DD}",
43
+ "{N}",
44
+ "{n}",
45
+ "{p}",
46
+ "{combined-report.md}",
47
+ "{issue编号}",
48
+ "{问题标题}"
49
+ ],
50
+ "forbidden_terms": [ "Phase",
51
+ "阶段",
52
+ "步骤"
53
+ ]
54
+ }
@@ -0,0 +1,295 @@
1
+ # {项目名} — {Round 数} 轮原子事务交接手册
2
+
3
+ > **适用场景**:多轮原子事务变更,每轮独立收敛。如 7 轮管线演进、多 Round架构重构。
4
+ >
5
+ > **用途**:每个新对话开始时,把对应Round章节粘贴给 LLM。它需要明确自己正在执行哪个原子工程事务、上游事务已经提交了什么、当前事务的文件边界是什么、验证标准是什么、完成后记录哪些 ADD-7 审计。
6
+
7
+ ---
8
+
9
+ ## 全局元信息
10
+
11
+ - **父 Plan**: [{plan文件名}](./{plan文件名}.md)
12
+ - **原子事务拓扑**: [{execution文件名}](./{execution文件名}.md)
13
+ - **目标仓库**: `{仓库绝对路径}`
14
+ - **总文件数**: 约 {N} 个独立文件
15
+ - **Round数**: {N} 轮局部闭包
16
+ - **拆分原则**: 以业务原子闭包为主,以对话上下文容量为辅
17
+
18
+ ```text
19
+ {拓扑依赖图 — ASCII 图,│ ├ ▼ 表达并行/串行关系,每行只有一个人工可读的Round缩写}
20
+
21
+ 第1轮 ── {Round简短描述}
22
+
23
+
24
+ 第2轮 ── {Round简短描述}
25
+
26
+ ├──────────────┐
27
+ ▼ ▼
28
+ 第3轮 ── {描述} 第4轮 ── {描述}
29
+ │ │
30
+ └──────┬───────┘
31
+
32
+ 第5轮 ── {描述}
33
+ ```
34
+
35
+ ---
36
+
37
+ ## 原子事务边界说明
38
+
39
+ 本手册中的"轮"按轮次级闭包划分(ADD 范式 §0.7):
40
+
41
+ - **轮次级闭包**:一轮内的文件集合形成独立边界——该轮修改的文件不会被其他轮次回头修改,该轮的验证不依赖"下一轮补齐"。轮次之间是生产者-消费者关系,不是互相修补。
42
+ - **独立验证**:每轮完成后可通过 `tsc --noEmit` + `eslint` + checklist [T] 项独立验证。
43
+
44
+ 因此:
45
+
46
+ - {解释为什么某两轮虽然依赖同一上游但拆成不同轮——因为文件边界独立,互不跨轮修改}
47
+ - {解释为什么某两轮虽然有关联但必须拆成不同轮——因为涉及不同的文件集合,合并会导致文件归属混乱}
48
+ - 每一轮完成后必须能够独立证明收敛,不能依赖"下一轮再补齐"才能成立。
49
+ - {最后一轮}不是前{N-1}轮的补丁,而是前{N-1}轮收敛后的验证合流;前{N-1}轮禁止提前实现 {最后一轮的核心内容}。
50
+
51
+ ### 交接手册与 spec 的优先级
52
+
53
+ - 本 handoff 是新对话的入口索引,负责说明Round位置、上下游依赖、文件边界、高风险误区、恢复关键词和审计闭环。
54
+ - 具体实现细节以对应 `.qoder/specs/{spec-name}/spec.md`、`tasks.md`、`checklist.md` 为准。
55
+ - 如果 handoff 摘要与 spec/tasks/checklist 存在颗粒度差异,以 spec/tasks/checklist 为准,不允许按 handoff 的简写自行简化实现。
56
+ - 每轮完成后的 ADD-7 不只写入 `record_dev_operation`,还必须用 `query_audit_logs` 按 action/targetId/keyword 回查确认落库。
57
+
58
+ ---
59
+
60
+ ## <第N轮> {Round简短描述}
61
+
62
+ ### 你当前的位置
63
+
64
+ 你是第 {N} 轮。上游{第 {X} 轮已完成 {上游能力描述}},{第 {Y} 轮已完成 {上游能力描述}}。
65
+
66
+ ### 上游已完成
67
+
68
+ - {上游本轮依赖的能力/文件/状态,不允许靠记忆,必须写清楚}
69
+ - {每一项是可验证的具体交付物,如 "Evidence 接口已在 src/types/evidence.ts 中唯一定义"}
70
+ - {如果上游有多个Round,逐轮列出可验证交付物}
71
+
72
+ ### 恢复上下文审计查询(新 AI Session 首次启动必读)
73
+
74
+ > **给后续 AI 助手的说明**:以下每个 `query_audit_logs(...)` 都是 MCP 工具调用,AI 助手在自己的对话中**直接复制粘贴这些参数调用工具即可**,不需要写 SQL。共 {N} 条审计记录可恢复本轮完整开发上下文。
75
+
76
+ #### 第一步:搜索代码文件的改动记录(查看 beforeState/afterState)
77
+
78
+ 文件改了什么、改前改后的合约差异,都在这些记录的 `beforeState` 和 `afterState` 字段里:
79
+
80
+ ```text
81
+ query_audit_logs({ targetId: "{文件路径1}" })
82
+ ```
83
+ → 返回 {N} 条:{ACTION_1}。beforeState {描述},afterState {描述}。
84
+
85
+ ```text
86
+ query_audit_logs({ targetId: "{文件路径2}" })
87
+ ```
88
+ → 返回 {N} 条:{ACTION_2}。beforeState {描述},afterState {描述}。
89
+
90
+ #### 第二步:搜索文档变更记录(恢复 spec 和契约决策)
91
+
92
+ ```text
93
+ query_audit_logs({ keyword: "DOC_UPDATED" })
94
+ ```
95
+ → 返回 {N} 条 spec 文档更新:spec.md / tasks.md / checklist.md。read 这些文件即可理解本轮的设计决策和边界约束。
96
+
97
+ #### 第三步:按行动词搜索(快速定位特定改动)
98
+
99
+ ```text
100
+ query_audit_logs({ keyword: "{ACTION_1}" })
101
+ ```
102
+ → 返回 {N} 条:{文件1} 的 {操作类型} 记录。
103
+
104
+ ```text
105
+ query_audit_logs({ keyword: "{ACTION_2}" })
106
+ ```
107
+ → 返回 {N} 条:{文件2} 的 {操作类型} 记录。
108
+
109
+ #### 恢复顺序建议
110
+
111
+ 新 AI Session 启动后,按以下顺序恢复上下文最快:
112
+
113
+ ```
114
+ 1. session-init SKILL(强制前置)
115
+ 2. query_audit_logs({}) → 查看最近所有操作
116
+ 3. query_audit_logs({ keyword: "{汇总关键词}" }) → 看本轮所有记录(应该返回 {N} 条)
117
+ 4. read ".qoder/specs/{spec-name}/spec.md"
118
+ 5. read ".qoder/specs/{spec-name}/tasks.md"
119
+ 6. read ".qoder/specs/{spec-name}/checklist.md"
120
+ ```
121
+
122
+ Step 3 搜索 `"{汇总关键词}"` 可以一次性拉取全部本轮审计记录,是最快的一键恢复方式。
123
+
124
+ ### 原子事务目标
125
+
126
+ 覆盖 `{父 Plan 文件名}` 的 Step {X}。{一句话概括本轮目标}。
127
+
128
+ ### spec 文件
129
+
130
+ - `.qoder/specs/{spec-name}/spec.md`
131
+ - `.qoder/specs/{spec-name}/tasks.md`
132
+ - `.qoder/specs/{spec-name}/checklist.md`
133
+
134
+ ### 架构文档
135
+
136
+ - `docs/{项目名}/knowledge/01-架构/{架构说明书}.md` — {章节号}:{章节标题}
137
+ - `docs/{项目名}/knowledge/01-架构/{管线说明书}.md` — {相关章节}
138
+
139
+ ### 你要改的文件({N} 个:{新建数} 新建 + {修改数} 修改)
140
+
141
+ | 文件 | 操作 | 改什么 |
142
+ |------|------|--------|
143
+ | `{文件路径1}` | 新建 | {一句话描述} |
144
+ | `{文件路径2}` | 修改 | {一句话描述} |
145
+
146
+ ### 核心设计(视Round复杂度可选)
147
+
148
+ ```text
149
+ {本轮最关键的架构/设计要点,不超过 10 行}
150
+ ```
151
+
152
+ ### 关键契约细化(视Round复杂度可选)
153
+
154
+ - `{文件路径}` {必须遵守的契约约束,如"禁止改 Schema"、"必须浅合并 metadata"}。
155
+ - {每条以文件路径开头}
156
+
157
+ ### 高风险误区
158
+
159
+ - 禁止 {最常见的错误做法1}。
160
+ - 禁止 {最常见的错误做法2}。
161
+ - **禁止提前实现下一轮 {下一轮的某个核心内容}**。
162
+
163
+ ### ADD-7 审计记录
164
+
165
+ | action | targetType | targetId | 说明 | 状态 |
166
+ |--------|-----------|----------|------|:--:|
167
+ | `{ACTION_1}` | {COMPONENT/API_ROUTE/...} | `{文件路径1}` | {说明} | 待记录 |
168
+ | `{ACTION_2}` | {COMPONENT/API_ROUTE/...} | `{文件路径2}` | {说明} | 待记录 |
169
+
170
+ **恢复关键词**:
171
+ ```text
172
+ query_audit_logs({ keyword: "{汇总关键词}" })
173
+ → 返回全部 {N} 条本轮 ADD-7 审计记录
174
+ ```
175
+
176
+ ### 验证标准
177
+
178
+ #### 已完成验证
179
+
180
+ - {验证项1}:{验证证据(代码行号/终端输出/测试结果)}
181
+ - {验证项2}:{验证证据}
182
+ - `npx tsc --noEmit` + `eslint` 通过
183
+ - checklist.md 全部由 `[ ]` 更新为 `[x]`(依据代码证据逐项验证后勾选)
184
+ - tasks.md 全部 Task 子项由 `[ ]` 更新为 `[x]`(依据代码证据逐项验证后勾选)
185
+
186
+ #### 未执行的端到端验证(保留给运行时复测)
187
+
188
+ - [ ] {端到端验证项1}(原因:{为什么本轮无法执行})
189
+ - [ ] {端到端验证项2}(原因:{为什么本轮无法执行})
190
+
191
+ ### 完成后记录 ADD-7 审计
192
+
193
+ 每改完一个文件,调用 `record_dev_operation`。参考 audit action:
194
+
195
+ | 文件 | action |
196
+ |------|--------|
197
+ | `{文件路径1}` | `{ACTION_1}` |
198
+ | `{文件路径2}` | `{ACTION_2}` |
199
+
200
+ 完成后一键验证:
201
+ ```text
202
+ query_audit_logs({ keyword: "{汇总关键词}" })
203
+ → 确认 {N} 条全部落库
204
+ ```
205
+
206
+ ---
207
+
208
+ {追加更多Round小节,每轮遵循上述 13 个标准化子章节}
209
+
210
+ ---
211
+
212
+ ## 每轮收敛判定补充规则
213
+
214
+ > 以下规则与 `add-paradigm` SKILL Step 8 收敛条件并列,是每轮原子事务完成的强制性前置条件。
215
+
216
+ ### checklist 证据要求
217
+
218
+ 每轮结束时,`checklist.md` 必须满足以下条件才算收敛:
219
+
220
+ - [ ] **全部项已勾选**(不得有空勾选、不得有"推测通过")
221
+ - [ ] **每项勾选有可验证证据**:
222
+ - 编译/类型项:附 `npx tsc --noEmit` 输出或错误数
223
+ - 运行项:附终端输出、截图或日志摘要
224
+ - 代码项:附文件路径 + 行号引用
225
+ - 跨轮依赖项:附 `query_audit_logs` 查询结果(如"确认第1轮已完成")
226
+ - [ ] **未执行项诚实保留**:无法在当前Round验证的项(如运行时端到端验收),保留为未勾选 `- [ ]`,并在旁注明"待后续运行时验证"
227
+ - [ ] **证据可直接获取**:后续 AI Session 通过 `query_audit_logs` 按 targetId/keyword 可查到 checklist 对应的验证证据
228
+
229
+ ### tasks 证据要求
230
+
231
+ - [ ] **全部任务已完成**(tasks.md 中全部 `- [x]`)
232
+ - [ ] **每个任务有对应的 checklist 项覆盖**(不允许 task 完成但无 checklist 验证记录)
233
+ - [ ] **task 完成状态与 ADD-7 审计记录一致**:每完成一个 task 的代码修改,必须有对应的 `record_dev_operation` 记录
234
+
235
+ ### 收敛声明规则
236
+
237
+ 当前Round AI 不得自行声明"本轮已收敛"并直接进入下一轮。收敛声明只能由以下角色做出:
238
+
239
+ 1. **开发者确认** — 开发者审核 checklist/tasks 证据后宣布收敛
240
+ 2. **Review AI 确认** — 独立的 review AI Session 通过 `query_audit_logs` 验证后宣布收敛
241
+
242
+ 执行 AI 的职责是完成 checklist/tasks 并附证据,而非自我判定收敛。
243
+
244
+ ---
245
+
246
+ ## 附录:每轮启动模板
247
+
248
+ 新对话开始时,直接把下面内容 + 对应Round章节粘贴给 LLM:
249
+
250
+ ```text
251
+ ## 上下文
252
+
253
+ 你在执行 {项目名} 改进的 [第N轮]。
254
+ 上游 [第1轮~第N-1轮] 已完成。
255
+ 先读 {handoff 文件路径} 的 <第N轮> 章节。
256
+
257
+ ## 启动操作(按顺序)
258
+
259
+ 1. 执行 session-init SKILL
260
+ 2. 执行 add-paradigm SKILL(含 Step 0 文档先行)
261
+ 3. 读本轮对应 .qoder/specs/{spec-name}/spec.md(含其中的「文档先行三步闭环」章节,按 spec 的指示更新架构文档)
262
+ 4. 读本轮对应 .qoder/specs/{spec-name}/tasks.md
263
+ 5. 读本轮对应 .qoder/specs/{spec-name}/checklist.md
264
+ 6. 按 tasks.md 顺序执行代码修改
265
+ 7. 每完成一个 Task:读 checklist.md → 逐项验证 → **附可验证证据** → 勾选
266
+ 8. 每完成一个文件修改:record_dev_operation 写入 ADD-7 审计
267
+ 9. 写入审计后:query_audit_logs 按 action/targetId/keyword 回查确认落库
268
+ 10. 全部代码完成后:按本轮 handoff 的 ADD-7 恢复关键词逐项回查,确认当前Round可被下一轮恢复
269
+ 11. 收敛后:回到 add-paradigm SKILL Step 0.6,验收后回看架构文档,标记偏差点,通知开发者决策
270
+
271
+ ## 关键提醒
272
+
273
+ - 当前执行的是 [第N轮]/{总轮数}
274
+ - 当前Round是一个原子工程事务,不允许拆到下一轮补齐
275
+ - handoff 是入口索引;具体实现以 spec/tasks/checklist 为准
276
+ - 架构文档同步:代码执行前(Step 0)更新架构文档 → 代码执行后(Step 0.6)回看架构文档确认一致性
277
+ - checklist 证据要求:每项勾选必须有可验证证据,不得空勾选或"推测通过"。未执行项必须诚实保留为未勾选状态
278
+ - tasks 证据要求:全部任务完成后,每个 task 必须有对应的 checklist 验证记录
279
+ - 禁止自行声明收敛:收敛声明只能由开发者或 Review AI 做出,执行 AI 不得自我判定"本轮已收敛"
280
+ - 禁止简化代码实现
281
+ - 禁止跳过 MCP 回查;只写 record_dev_operation 不算审计闭环完成
282
+ - 保持与上游文件修改兼容,特别注意 handoff 中标记的历史修改文件
283
+ ```
284
+
285
+ ---
286
+
287
+ ### 脱敏要求
288
+
289
+ Handoff 文档中 **禁止出现** 以下类型的硬编码值:
290
+ - 数据库密码(`POSTGRES_PASSWORD`)
291
+ - Chroma auth token(`CHROMA_AUTH_TOKEN`)
292
+ - JWT 密钥(`JWT_SECRET`)
293
+ - API Key(`OPENAI_API_KEY_*`)
294
+
295
+ 所有凭据值应通过 `${ENV_VAR}` 引用,并标注"值见 `.env.development` / `.env.production`"。
@@ -0,0 +1,48 @@
1
+ {
2
+ "template": "handoff-multi-round-template.md",
3
+ "sections": [
4
+ {
5
+ "id": "meta",
6
+ "heading": "## 全局元信息",
7
+ "required": true
8
+ },
9
+ {
10
+ "id": "boundary",
11
+ "heading": "## 原子事务边界说明",
12
+ "required": true
13
+ },
14
+ {
15
+ "id": "round",
16
+ "heading": "## <第N轮>",
17
+ "required": true
18
+ },
19
+ {
20
+ "id": "convergence",
21
+ "heading": "## 每轮收敛判定补充规则",
22
+ "required": true
23
+ },
24
+ {
25
+ "id": "appendix",
26
+ "heading": "## 附录:每轮启动模板",
27
+ "required": true
28
+ },
29
+ {
30
+ "id": "desensitize",
31
+ "heading": "### 脱敏要求",
32
+ "required": true
33
+ }
34
+ ],
35
+ "placeholders": [
36
+ "{项目名}",
37
+ "{轮次数}",
38
+ "{plan文件名}",
39
+ "{execution文件名}",
40
+ "{仓库绝对路径}",
41
+ "{N}"
42
+ ],
43
+ "forbidden_terms": [
44
+ "Phase",
45
+ "阶段",
46
+ "步骤"
47
+ ]
48
+ }