kld-sdd 2.6.1 → 2.6.2

package/templates/skills/kld-sdd/opsx-tdd-core/reference.md

@@ -0,0 +1,146 @@
+---
+description: "opsx-tdd-core 详细参考 — 执行步骤、拆分示例、DAG 规则、telemetry 模板。仅在需要详细执行指引时读取。"
+---
+
+# opsx-tdd-core — 详细参考
+
+> 仅在需要详细执行指引时读取。日常流程见 `SKILL.md`。
+
+---
+
+## §1 RED 执行步骤
+
+1. 读取 spec.md 场景和 design.md 设计
+2. 编写测试代码：Given-When-Then 结构 + 真实断言
+3. ⛔ **只写当前 RED 对应的测试方法**：不提前编写后续 RED 的测试方法。若测试文件已有前序 RED 的测试方法，仅追加当前 RED 的方法
+4. 运行测试：`mvn test -Dtest=XxxTest#testMethodName`（或项目对应命令）
+5. 确认测试失败：失败原因必须是"功能未实现"（如 NullPointerException、AssertionError）
+6. 如果测试通过：说明测试无效或功能已存在，重新编写测试
+7. 记录失败原因到任务状态
+8. ⛔ **执行中断声明**：`🔴 RED-N 确认失败，原因：[具体原因]。现在进入 GREEN-N，仅实现让此测试通过的最少代码。`
+
+**RED 测试质量标准（Mock 边界，不 Mock 行为）**：
+- 禁止 mock 被测行为本身（Given 应准备真实前置条件）
+- Mock 仅用于系统边界依赖（数据库 Mapper、HTTP 客户端等）
+- RED 测试的 Given 必须是真实输入
+- 判断标准：删掉被测类实现后测试是否仍因 mock 而通过？如果是→测试是假的
+
+## §2 GREEN 执行步骤
+
+1. 读取对应 RED 任务的失败原因
+2. ⛔ **执行 GREEN Scope 声明**（见 `opsx-tdd-rules/rules/green-scope-declaration.md`）：
+   - 列出当前 RED 测试的断言清单
+   - 列出 design.md 中本 DES 元素的完整流程步骤
+   - 标记步骤归属（✅ 属于当前 RED / ⛔ 属于后续 RED）
+   - 仅实现标记为 ✅ 的步骤
+3. ⛔ **逐条确认 YAGNI 围栏**：读取 tasks.md 中本 GREEN 任务的 YAGNI 围栏声明，逐条确认"未实现 [后续 RED 的行为]：✅"
+4. 编写最少代码让测试通过
+5. 不提前实现没有测试要求的功能（YAGNI）
+6. 禁止捆绑未测试的代码：
+   - RED 只测了 Service 方法 → GREEN 不得同时实现 Controller 接口
+   - RED 只测了一个行为点 → GREEN 不得同时实现其他行为点
+   - 需修改多个文件才能让测试通过 → 检查是否测试范围过大
+7. 运行测试确认通过
+8. 引入新功能但无对应测试 → 删除多余代码
+9. ⛔ **执行 GREEN Scope 门禁**：
+   - 检查生产代码中是否有未被当前 RED 断言覆盖的逻辑分支
+   - 若存在且属于后续 RED 的行为 → 删除越界代码
+   - 重新运行测试确认仍绿
+10. 自检：修改文件列表是否与 RED 测试覆盖范围一致？超出则报告 DONE_WITH_CONCERNS
+
+## §3 REFACTOR 执行步骤
+
+> 完整检查点见 `opsx-tdd-rules/rules/refactor-checklist.md`（7 项重构检查 + 跳过条件 + 量化标准）。
+
+1. 在所有测试通过的状态下开始
+2. 优化代码结构（提取方法、消除重复、改善命名）
+3. 运行全部测试：`mvn test`（或项目对应命令）
+4. 确认所有测试仍通过
+5. 任何测试失败 → 回退重构，重新尝试
+6. 执行 `opsx-tdd-rules/rules/refactor-checklist.md` 的 7 项检查
+
+## §4 TDD 拆分示例
+
+以认证模块为例，7 个场景拆为 7 对 RED+GREEN + 1 个 REFACTOR：
+
+| TASK-ID | 行为点 | 类型 | 依赖 | 验收标准 |
+|---------|--------|------|------|---------|
+| TASK-05-RED-1 | 登录成功返回 Token | 测试-RED | TASK-03,04 | 测试运行失败，失败原因：AuthService 未实现 |
+| TASK-05-GREEN-1 | 登录成功最小实现 | 实现-GREEN | RED-1 | RED-1 测试通过，未提前实现密码错误校验 |
+| TASK-05-RED-2 | 密码错误返回 2001 | 测试-RED | GREEN-1 | 测试运行失败，失败原因：未校验密码错误 |
+| TASK-05-GREEN-2 | 密码校验实现 | 实现-GREEN | RED-2 | RED-2 测试通过 |
+| ... | ... | ... | ... | ... |
+| TASK-05-REFACTOR | 认证模块重构 | 重构-REFACTOR | GREEN-6 | 全部 user-auth 测试仍绿，代码结构改善 |
+
+关键区别：
+- 每个 RED 任务带真实断言跑起来确实失败
+- 每个 GREEN 任务只写让当前测试通过的最少代码
+- 行为点粒度一次一个小步循环
+- 重构独立成任务在全部绿灯后进行
+
+## §5 Controller 策略示例
+
+**策略 A**（Controller 拆 RED→GREEN，使用 @WebMvcTest）：
+
+| TASK-ID | 行为点 | 类型 | 验收标准 |
+|---------|--------|------|---------|
+| TASK-CTRL-RED-1 | POST /api/v1/auth/login 返回 Token | 测试-RED | @WebMvcTest 测试运行失败 |
+| TASK-CTRL-GREEN-1 | AuthController 接线 | 实现-GREEN | RED 测试通过 |
+
+**策略 B**（Controller 作为非 TDD 任务）：
+
+| TASK-ID | 类型 | 验收标准 |
+|---------|------|---------|
+| TASK-CTRL | 接口层（非 TDD） | Controller 编译通过，调用对应 Service 方法，返回 Result |
+
+## §6 DAG 生成规则
+
+> 完整规则见 `opsx-tdd-rules/rules/dag-generation-rules.md`，此处仅保留快速参考。
+
+| test-strategy | DAG 规则 |
+|---------------|---------|
+| `tdd` | 每个行为点拆为 RED→GREEN 对，GREEN Depends-On RED；每 3-5 个行为点后可插入 REFACTOR（Depends-On 前一个 GREEN）；模块末尾可加 VERIFY（Depends-On 最后一个 GREEN/REFACTOR） |
+| `impl-first` | 实现任务在前，测试任务 Depends-On 实现任务 |
+| `none` | 不生成测试任务，仅编译检查 |
+
+## §7 非 TDD 模块规则
+
+> 完整规则见 `opsx-tdd-rules/rules/non-tdd-modules.md`，此处仅保留快速参考。
+
+以下模块不需要红绿循环，按常规任务处理：
+- 前端 UI 页面（Vue 组件）→ UI层任务
+- 项目脚手架/配置 → 配置任务
+- 数据库迁移脚本（SQL DDL）→ 数据层任务
+- 前端路由/状态管理/API 封装 → UI层任务
+- Controller 层（可选）→ 接口层任务（当选择策略 B 时）
+
+## §8 Telemetry 模板
+
+**TDD 测试骨架任务**（`task_kind:"test-skeleton"`）：
+
+```bash
+node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 测试骨架完成（TDD 红灯）" --details-json='{"task_kind":"test-skeleton","test_results":{"command":"<实际测试命令>","passed":0,"failed":<红灯数>,"skipped":0,"duration_ms":0}}'
+```
+
+**实现任务**（不带 `task_kind`）：
+
+```bash
+node skywalk-sdd/log.cjs record --type=task_update --command=apply --project=. --change=<变更名称> --capability=<capability-name> --task-id=<TASK-ID> --agent=<Agent类型> --source=opsx-command --session-id=<会话ID> --status=completed --result=success --summary="<TASK-ID> 完成" --details-json='{"files_changed":[],"test_results":{"command":"<实际测试命令>","passed":<通过数>,"failed":0,"skipped":0,"duration_ms":0}}'
+```
+
+## §9 单元测试真实执行
+
+当 `test-strategy` 为 `tdd` 或 `impl-first` 时：
+
+1. 在结束 apply 或执行收尾之前，必须真实运行单元测试命令
+2. 须留下可核验 telemetry 证据（任选其一）：
+   - `node skywalk-sdd/log.cjs record --type=test_result ...`（`test_results.command` 非空，且 `passed`/`failed`/`duration_ms` 有实际值）
+   - `task_update` 的 `details-json` 中 `test_results` 含真实执行数据
+   - 或单独运行 `/opsx-test` 并完成 `command=test` 的 `stage_end`
+3. `sdd-apply-test-gate.cjs` 会在 `log.cjs end`、`apply-worktree-finish`、会话 Stop 时自动校验，无证据则阻断
+
+| test-strategy | 行为 |
+|---------------|------|
+| `tdd` | 无测试证据不得结束 apply / 不得 finish worktree |
+| `impl-first` | 同上，实现后必须补跑并记录 |
+| `none` | 跳过 |

package/templates/skills/kld-sdd/opsx-tdd-metrics/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: opsx-tdd-metrics
+description: "度量分析层 — 测试质量量化度量：隔离评分、命名评分、测试异味检测、覆盖率缺口分析。当需要量化测试质量时引用本技能。"
+---
+
+# opsx-tdd-metrics — 度量分析层
+
+> **定位**：测试质量的量化度量，提供可计算的评分。
+> **参考来源**：tdd-guide `metrics_calculator.py`
+
+---
+
+## §1 隔离评分（0-100）
+
+> 初始分 100，按以下项扣分/加分，最低 0 分。详细计算见 `./checklist.md` §A。
+
+| 惩罚项 | 扣分 |
+|--------|------|
+| 全局状态使用 | -20 |
+| 不匹配的 setup/cleanup | -15 |
+| 测试间共享可变状态 | -15 |
+
+| 奖励项 | 加分（上限 100） |
+|--------|------|
+| 正确使用 mock | +10 |
+| 每个测试自包含 | +10 |
+
+## §2 命名质量评分（0-100）
+
+> 初始分 100，按以下项扣分，最低 0 分。详细计算见 `./checklist.md` §B。
+
+检查项：
+- 名称长度（太长或太短扣分）
+- 描述性词汇（should/when/given/returns/throws/handles）
+- 避免通用名称（test1、testCalc）
+- 符合 `{method}_{state}_{outcome}` 格式
+- 不暴露实现细节
+
+## §3 测试异味检测
+
+| 异味 | 检测条件 | 严重程度 |
+|------|---------|---------|
+| 断言轮盘赌 | 单测试 >5 个断言 | 中 |
+| 缺失断言 | 无 `assert`/`expect` | 高 |
+| sleep 使用 | `sleep`/`wait` | 高 |
+| 条件逻辑 | `if` 语句 | 中 |
+| 弱断言 | 只检查 truthy | 中 |
+
+## §4 慢测试检测
+
+>100ms 标记为慢测试。
+
+## §5 不稳定测试检测
+
+失败率 >10% 标记为 flaky。
+
+## §6 可测试性评分（0-100）
+
+> 基于被测代码的指标，详细计算见 `./checklist.md` §C。
+
+| 指标 | 计算方式 | 阈值 |
+|------|---------|------|
+| 圈复杂度 | if/for/while/case/catch/&&/|| 决策点数 | >10 扣 10 分/点 |
+| 依赖数量 | 构造器/setter 注入的依赖数 | >5 扣 5 分/个 |
+| 函数大小 | 最长方法的行数 | >50 扣 2 分/行 |
+
+## §7 覆盖率缺口分析
+
+| 优先级 | 覆盖率范围 | 说明 |
+|--------|-----------|------|
+| P0 | <40% | 关键路径，必须补充 |
+| P1 | 60-80% | 重要路径，建议补充 |
+| P2 | 80%+ | 一般路径，可选补充 |

package/templates/skills/kld-sdd/opsx-tdd-metrics/checklist.md

@@ -0,0 +1,60 @@
+---
+description: "opsx-tdd-metrics 自检清单 — 隔离评分、命名评分、可测试性评分的计算口径。仅在量化测试质量时读取。"
+---
+
+# opsx-tdd-metrics — 自检清单
+
+> 仅在量化测试质量时读取。日常流程见 `SKILL.md`。
+
+## §A 隔离评分（0-100）
+
+**初始分：100，按以下项扣分/加分，最低 0 分。**
+
+| 惩罚项 | 扣分 |
+|--------|------|
+| 全局状态使用 | -20 |
+| 不匹配的 setup/cleanup | -15 |
+| 测试间共享可变状态 | -15 |
+
+| 奖励项 | 加分（上限 100） |
+|--------|------|
+| 正确使用 mock（仅 Mock 系统边界） | +10 |
+| 每个测试自包含（无隐式依赖） | +10 |
+
+## §B 命名质量评分（0-100）
+
+**初始分：100，按以下项扣分，最低 0 分。**
+
+| 惩罚项 | 扣分 |
+|--------|------|
+| 名称长度 >60 字符 | -10 |
+| 名称长度 <10 字符 | -10 |
+| 缺少描述性词汇（should/when/given/returns/throws/handles） | -15 |
+| 使用通用名称（test1、testCalc） | -20 |
+| 不符合 `{method}_{state}_{outcome}` 格式 | -15 |
+| 暴露实现细节（如 usesStreamApi） | -10 |
+
+## §C 可测试性评分（0-100）
+
+**基于被测代码（非测试代码）的以下指标：**
+
+| 指标 | 计算方式 | 阈值 |
+|------|---------|------|
+| 圈复杂度 | if/for/while/case/catch/&&/|| 决策点数 | >10 扣 10 分/点 |
+| 依赖数量 | 构造器/setter 注入的依赖数 | >5 扣 5 分/个 |
+| 函数大小 | 最长方法的行数 | >50 扣 2 分/行 |
+
+## §D 覆盖率缺口分析
+
+| 优先级 | 覆盖率范围 | 说明 |
+|--------|-----------|------|
+| P0 | <40% | 关键路径，必须补充 |
+| P1 | 60-80% | 重要路径，建议补充 |
+| P2 | 80%+ | 一般路径，可选补充 |
+
+## §E 慢测试与不稳定测试
+
+| 指标 | 阈值 | 说明 |
+|------|------|------|
+| 慢测试 | >100ms | 标记为慢测试 |
+| 不稳定测试 | 失败率 >10% | 标记为 flaky |

package/templates/skills/kld-sdd/opsx-tdd-quality/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: opsx-tdd-quality
+description: "单测代码质量层 — Mock 边界矩阵、测试命名规范、Given-When-Then 结构、Java 测试规则等。当编写或审查测试代码时引用本技能。"
+---
+
+# opsx-tdd-quality — 单测代码质量层
+
+> **定位**：单元测试代码的质量标准，不涉及流程，只关注"写出来的测试代码本身是否高质量"。
+> **参考来源**：unit-tests-skills（14 通用规则 + 6 Java 规则）
+
+---
+
+## §1 好测试的四大品质（CCCR 框架）
+
+| 品质 | 说明 | 检查标准 |
+|------|------|---------|
+| **Clarity（清晰性）** | 一眼就能读懂 | 10 秒内能理解吗？ |
+| **Completeness（完整性）** | 包含理解测试所需的全部信息 | 所有相关数据在测试中可见，不依赖隐藏 setup |
+| **Conciseness（简洁性）** | 只包含与场景相关的信息 | 无关细节已隐藏（用 helper） |
+| **Resilience（韧性）** | 不因无关代码变更而失败 | 测试行为而非实现，使用公共 API |
+
+## §2 Mock 边界矩阵
+
+> 完整规则见 `rules/general/mock-boundary.md`，此处仅保留快速参考。
+
+| 应该 Mock | 用真实对象 | 绝不 Mock |
+|-----------|-----------|-----------|
+| Repository / DAO | DTO / 值对象 | 被测系统（SUT）本身 |
+| 外部服务客户端 | 领域实体（大多数情况） | |
+| 消息生产者 | 工具类 | |
+| 缓存服务 | Mapper（通常） | |
+| 任何 I/O 操作 | | |
+
+**判断标准**：删掉被测类实现后测试是否仍因 mock 而通过？如果是→测试是假的。
+
+## §3 测试命名规范
+
+> 完整规则见 `rules/general/naming-conventions.md`，此处仅保留快速参考。
+
+格式：`{method}_{state}_{outcome}`
+
+- ✅ `login_wrongPassword_returns2001`
+- ❌ `testCalculate()` — 太模糊
+
+## §4 Given-When-Then 结构
+
+> 完整规则见 `rules/general/given-when-then.md`，此处仅保留快速参考。
+
+每个测试必须有清晰的三段式结构，用注释标注。`@BeforeEach` 仅用于基础设施 setup。
+
+## §5 测试聚焦
+
+> 完整规则见 `rules/general/one-test-one-scenario.md`，此处仅保留快速参考。
+
+一测一场景。测试名包含 "and" 是反模式信号。
+
+## §6 测试中不要放逻辑
+
+> 完整规则见 `rules/general/no-logic-in-tests.md`，此处仅保留快速参考。
+
+**KISS > DRY**。禁止：循环、条件、字符串拼接、计算在断言中。
+
+## §7 规则索引
+
+通用规则（适用所有语言）：
+- `rules/general/naming-conventions.md` — 测试命名规范
+- `rules/general/given-when-then.md` — Given-When-Then 结构
+- `rules/general/test-behaviors-not-methods.md` — 测试行为而非方法
+- `rules/general/one-test-one-scenario.md` — 一测一场景
+- `rules/general/no-logic-in-tests.md` — 测试中不要放逻辑
+- `rules/general/prefer-public-apis.md` — 优先测试公共 API
+- `rules/general/clean-test-data.md` — 干净地创建测试数据
+- `rules/general/cause-effect-clarity.md` — 保持因果清晰
+- `rules/general/good-test-qualities.md` — 好测试的四大品质
+- `rules/general/mock-boundary.md` — Mock 边界矩阵
+- `rules/general/existing-test-awareness.md` — 已有测试感知
+- `rules/general/parameterized-testing.md` — 参数化测试指导
+
+Java 专用规则：
+- `rules/java/java-test-template.md` — Java 测试模板
+- `rules/java/argument-matching.md` — Mockito 参数匹配
+- `rules/java/json-serialization.md` — JSON 序列化
+- `rules/java/logging-rules.md` — 日志输出验证
+- `rules/java/domain-service-rules.md` — 领域/服务单元测试规则
+- `rules/java/controller-test-rules.md` — 控制器测试规则
+
+TypeScript 专用规则：
+- `rules/typescript/ts-test-template.md` — TypeScript 测试模板（Vitest/Jest）
+
+Python 专用规则：
+- `rules/python/py-test-template.md` — Python 测试模板（pytest）
+
+生成后验证：
+- `rules/post-generation/compilation-verification.md` — 编译验证
+- `rules/post-generation/execution-verification.md` — 执行验证

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/cause-effect-clarity.md

@@ -0,0 +1,19 @@
+# 保持因果清晰
+
+> 影响等级：HIGH
+
+## 核心规则
+
+效果应紧跟原因。避免依赖远处的 setup 代码。
+
+## 关键指南
+
+1. 如果 setup 与理解测试相关，就放在测试方法内
+2. `@BeforeEach` 只用于**基础设施 setup**（mock、容器），不用于测试数据
+3. 避免共享可变状态——每个测试设置自己的数据
+4. 保持测试自包含——读者不需要看别处
+
+## @BeforeEach 适用场景
+
+启动 MockWebServer、创建 SUT 实例等基础设施。
+测试特定数据（如 mock 返回值）应放在测试方法内。

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/clean-test-data.md

@@ -0,0 +1,33 @@
+# 干净地创建测试数据
+
+> 影响等级：HIGH
+
+## 三大要点
+
+1. **使用 Helper 函数**：隐藏无关细节，提高可读性
+2. **使用 Builder 模式**：当 helper 参数过多时
+3. **绝不依赖 Helper 的默认值**：如果测试依赖某个值，即使与 helper 默认值相同也要显式设置
+
+## 正例
+
+```java
+// Helper 返回带必要默认值的 builder
+newCompany().employeesCount(2).boardMembersCount(2).build()
+
+// 显式设置测试依赖的值
+newCompany().type(Type.PUBLIC).build()
+```
+
+## 反例
+
+```java
+// 设置了所有字段，但测试只关心 name
+new ShoppingCart(new DefaultRoundingStrategy(), "unused", NORMAL, false, false, TimeZone.getTimeZone("UTC"), null)
+```
+
+## Helper 指南
+
+1. 描述性命名——`createProductWithCategory("Office")` 而非 `createProduct()`
+2. 只暴露相关参数
+3. 保持简单——无业务逻辑
+4. 复杂对象考虑 builder

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/existing-test-awareness.md

@@ -0,0 +1,17 @@
+# 已有测试感知
+
+> 影响等级：HIGH
+
+## 生成前必做
+
+1. 搜索 `{ClassName}Test` 或 `{ClassName}Tests`
+2. 如果找到：**不要创建新类**，只添加缺失的测试方法，保留已有结构/导入/helper，遵循已有模式
+3. 如果没找到：扫描同包中 2-3 个邻近测试类学习项目规范
+
+## 需要匹配的方面
+
+- 断言库：Hamcrest vs AssertJ——不要混用
+- 测试数据模式：项目有 `TestDataFactory` 或 builder 就用它们
+- 基础测试类：继承 `BaseTest` 或 `AbstractIntegrationTest` 的模式
+- 静态导入风格
+- 注释风格：`// given / when / then` vs `// arrange / act / assert`

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/given-when-then.md

@@ -0,0 +1,44 @@
+# Given-When-Then 结构
+
+> 影响等级：HIGH
+
+## 核心规则
+
+每个测试必须有清晰的 setup/action/verification 三段式结构，用注释标注。
+
+## 正例
+
+```java
+@Test
+void create_validName_returnsId() {
+    // Given
+    when(publisherMapper.selectOne(any())).thenReturn(null);
+    doAnswer(invocation -> {
+        Publisher p = invocation.getArgument(0);
+        p.setId(1L);
+        return 1;
+    }).when(publisherMapper).insert(any(Publisher.class));
+
+    // When
+    Long result = publisherService.create("人民邮电出版社");
+
+    // Then
+    assertNotNull(result);
+}
+```
+
+## 反例
+
+```java
+@Test
+void testCreate() {
+    Long result = publisherService.create("test");
+    assertNotNull(result);
+    // 没有 Given-When-Then 结构，难以理解测试意图
+}
+```
+
+## @BeforeEach 使用规则
+
+`@BeforeEach` 仅用于**基础设施 setup**（mock、容器），不用于测试数据。
+测试特定数据（如 mock 返回值）应放在测试方法内。

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/good-test-qualities.md

@@ -0,0 +1,32 @@
+# 好测试的四大品质（CCCR 框架）
+
+> 影响等级：HIGH
+
+## 四大品质
+
+1. **Clarity（清晰性）**：一眼就能读懂
+   - 测试名描述场景
+   - Given-When-Then 结构明显
+   - 不需要看别处就能理解
+   - 检查标准：10 秒内能理解吗？
+
+2. **Completeness（完整性）**：包含理解测试所需的全部信息
+   - 反模式：依赖类级常量和 `@BeforeEach` 中的隐藏 setup
+   - 正确：所有相关数据在测试中可见
+
+3. **Conciseness（简洁性）**：只包含与场景相关的信息
+   - 隐藏无关细节（用 helper）
+   - 反模式：设置 user 的所有字段，但测试只关心 name
+
+4. **Resilience（韧性）**：不因无关代码变更而失败
+   - 测试行为而非实现
+   - 使用公共 API
+   - 不过度指定 mock 交互
+   - 不依赖字段顺序或格式
+
+## 检查清单
+
+- [ ] 清晰性：10 秒内能理解吗？
+- [ ] 完整性：所有相关信息都在测试中吗？
+- [ ] 简洁性：无关信息是否已隐藏？
+- [ ] 韧性：重构后测试还能存活吗？

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/mock-boundary.md

@@ -0,0 +1,44 @@
+# Mock 边界矩阵
+
+> 影响等级：HIGH
+
+## 核心原则
+
+测试必须验证真实行为，而非 mock 行为。Mock 是隔离的手段，不是被测试的对象。
+
+## Mock 边界矩阵
+
+| 应该 Mock | 用真实对象 | 绝不 Mock |
+|-----------|-----------|-----------|
+| Repository / DAO | DTO / 值对象 | 被测系统（SUT）本身 |
+| 外部服务客户端 | 领域实体（大多数情况） | |
+| 消息生产者 | 工具类 | |
+| 缓存服务 | Mapper（通常） | |
+| 任何 I/O 操作 | | |
+
+## 正例
+
+```java
+// ✅ Mock Mapper（DB 边界）
+@Mock
+private UserMapper userMapper;
+
+// ✅ 使用真实 JwtUtil + 真实 invalid token
+private JwtUtil jwtUtil = new JwtUtil("real-secret-key-at-least-256-bits-long", 7200, 604800);
+```
+
+## 反例
+
+```java
+// ❌ Mock JwtUtil.parseToken() — 被测行为的实现
+@Mock
+private JwtUtil jwtUtil;
+when(jwtUtil.parseToken("invalid")).thenThrow(...);
+
+// ❌ Mock PasswordEncoder 后只验证"密码不等于明文" — 弱断言
+```
+
+## 判断标准
+
+如果删掉被测类的实现（方法体清空），测试是否仍然因为 mock 而通过？
+如果是 → 测试是假的，必须重写。

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/naming-conventions.md

@@ -0,0 +1,37 @@
+# 测试命名规范
+
+> 影响等级：HIGH
+
+## 核心规则
+
+测试方法命名格式：`{testedMethod}_{givenState}_{expectedOutcome}`
+
+## 命名指南
+
+1. 状态要具体——"validProducts" 而非 "goodInput"
+2. 结果要具体——"returns401" 而非 "fails"
+3. 使用领域语言——"unauthorized" 而非 "noToken"
+4. 避免技术术语——描述行为而非实现
+
+## 正例
+
+```java
+@Test
+void login_wrongPassword_returns2001() { ... }
+
+@Test
+void create_duplicateName_returns2006() { ... }
+```
+
+## 反例
+
+```java
+@Test
+void testCalculate() { ... }              // 太模糊
+
+@Test
+void calculateTotal_validProducts() { ... }  // 没有描述结果
+
+@Test
+void calculateTotal_usesStreamApi_returnsSum() { ... }  // 暴露实现细节
+```

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/no-logic-in-tests.md

@@ -0,0 +1,30 @@
+# 测试中不要放逻辑
+
+> 影响等级：HIGH
+
+## 核心原则
+
+**KISS > DRY** — 在测试中，简单性比避免重复更重要。
+
+## 禁止的模式
+
+- 循环：`for (int i = 0; i < users.size(); i++) { assertThat(...) }`
+- 条件：`if (response.isSuccessful()) { assertThat(...) }`
+- 字符串拼接：`assertThat(result).isEqualTo("Hello, " + userName + "!")`
+- 计算：`assertThat(total).isEqualTo(price * quantity + tax)`
+
+## 正确做法
+
+- 使用字面值——`assertThat(result).isEqualTo("Hello, John!")`
+- 预计算的期望值——`int expectedTotal = 115;`
+- 用 `assertThat(users).extracting(User::isActive).containsOnly(true)` 代替循环
+
+## 逻辑隐藏 Bug 的经典案例
+
+```java
+// 错误：字符串拼接隐藏了 bug（结果为 "//u/0/photos"）
+assertThat(photosPageUrl).isEqualTo(baseUrl + "/u/0/photos");
+
+// 正确：字面值让 bug 显而易见
+assertThat(actualUrl).isEqualTo("http://photos.google.com/u/0/photos");
+```

package/templates/skills/kld-sdd/opsx-tdd-quality/rules/general/one-test-one-scenario.md

@@ -0,0 +1,23 @@
+# 一测一场景
+
+> 影响等级：HIGH
+
+## 核心规则
+
+每个测试只验证一个特定场景。多个场景混在一个测试中会导致失败难以诊断。
+
+## 反模式信号
+
+- 测试名包含 "and"（如 `testDepositAndWithdraw`）
+- 多个 "When" 或 "Act" 段
+- 断言之间有状态变化
+- 难以简洁命名
+- 测试超过 10-15 行
+
+## 多断言何时可以
+
+当验证**同一个行为**的多个属性时可以。例如验证用户创建行为时，同时断言 id 不为 null、email 正确、name 正确、createdAt 不为 null——这些都是验证"用户创建"这一个行为。
+
+## 拆分判断标准
+
+问自己"如果这个测试失败，我能确切知道哪个场景坏了吗？"如果不能，就拆分。