证据基础验证技能

版本： 1.0.0 类型： 质量保证 自动激活： 代码审查，任务完成，生产部署

概览

这个技能教导代理如何在标记任务完成前收集和验证证据。受生产级开发实践的启发，它确保所有声明都有可执行的证据支持：测试结果、覆盖率指标、构建成功和部署验证。

关键原则： 展示，不要只是告诉。没有可验证的证据，任务就不算完成。

何时使用此技能

自动激活触发器

完成代码实现
完成代码审查
在小队模式中标记任务完成
代理交接前
生产部署验证

手动激活

当用户请求“验证这是否有效”时
创建拉取请求前
在质量保证审查期间
故障排除失败时

核心概念

1. 证据类型

测试证据

退出代码（必须为0表示成功）
测试套件结果（通过/失败/跳过）
覆盖率百分比（如果可用）
测试持续时间

构建证据

构建退出代码（0 = 成功）
编译错误/警告
创建的构建工件
构建持续时间

部署证据

部署状态（成功/失败）
部署到的环境
健康检查结果
验证回滚能力

代码质量证据

静态代码分析结果（错误/警告）
类型检查器结果
安全扫描结果
可访问性审计结果

2. 证据收集协议

## 证据收集步骤

1. **确定验证点**
   - 需要证明什么？
   - 可能出错的地方是什么？
   - “完成”意味着什么？

2. **执行验证**
   - 运行测试
   - 运行构建
   - 运行静态代码分析
   - 检查部署

3. **捕获结果**
   - 记录退出代码
   - 保存输出片段
   - 记录时间戳
   - 记录环境

4. **存储证据**
   - 添加到共享上下文
   - 在任务完成中引用
   - 链接到工件

3. 验证标准

最低证据要求：

✅ 至少执行一种验证类型
✅ 捕获退出代码（0 = 通过，非零 = 失败）
✅ 记录时间戳
✅ 在上下文中存储证据

生产级要求：

✅ 测试通过（退出代码0）
✅ 覆盖率 >70%（或项目标准）
✅ 构建成功（退出代码0）
✅ 无关键静态代码分析错误
✅ 安全扫描通过

证据收集模板

模板 1: 测试证据

使用此模板运行测试时：

## 测试证据

**命令：** `npm test`（或等效命令）
**退出代码：** 0 ✅ / 非零 ❌
**持续时间：** X 秒
**结果：**
- 通过测试：X
- 失败测试：X
- 跳过测试：X
- 覆盖率：X%

**输出片段：**

[测试输出的前10行]


**时间戳：** YYYY-MM-DD HH:MM:SS
**环境：** Node vX.X.X, OS 等。

模板 2: 构建证据

使用此模板构建时：

## 构建证据

**命令：** `npm run build`（或等效命令）
**退出代码：** 0 ✅ / 非零 ❌
**持续时间：** X 秒
**创建的工件：**
- dist/bundle.js (XXX KB)
- dist/styles.css (XXX KB)

**错误：** X
**警告：** X

**输出片段：**

[构建输出的前10行]


**时间戳：** YYYY-MM-DD HH:MM:SS

模板 3: 代码质量证据

使用此模板进行静态代码分析和类型检查时：

## 代码质量证据

**静态代码分析工具：** ESLint / Ruff / 等。
**命令：** `npm run lint`
**退出代码：** 0 ✅ / 非零 ❌
**错误：** X
**警告：** X

**类型检查器：** TypeScript / mypy / 等。
**命令：** `npm run typecheck`
**退出代码：** 0 ✅ / 非零 ❌
**类型错误：** X

**时间戳：** YYYY-MM-DD HH:MM:SS

模板 4: 综合证据报告

使用此全面模板完成任务：

## 任务完成证据

### 任务：[任务描述]
### 代理：[代理名称]
### 完成：YYYY-MM-DD HH:MM:SS

### 验证结果

| 检查 | 命令 | 退出代码 | 结果 |
|-------|---------|-----------|--------|
| 测试 | `npm test` | 0 | ✅ 45 通过，0 失败 |
| 构建 | `npm run build` | 0 | ✅ 打包创建（234 KB） |
| 静态代码分析 | `npm run lint` | 0 | ✅ 无错误，2 警告 |
| 类型 | `npm run typecheck` | 0 | ✅ 无类型错误 |

### 覆盖率
- 语句：87%
- 分支：82%
- 函数：90%
- 行：86%

### 证据文件
- 测试输出：`.claude/quality-gates/evidence/tests-2025-XX-XX.log`
- 构建输出：`.claude/quality-gates/evidence/build-2025-XX-XX.log`

### 结论
所有验证检查通过。任务准备审查。

逐步工作流程

工作流程 1: 代码实现验证

何时： 编写功能或修复bug的代码后

步骤：

保存所有文件 - 确保更改被写入
运行测试
```
npm test
# 或：pytest, cargo test, go test, 等。
```
- 捕获退出代码
- 记录通过/失败计数
- 如果可用，记录覆盖率
运行构建（如果适用）
```
npm run build
# 或：cargo build, go build, 等。
```
- 捕获退出代码
- 记录任何错误/警告
- 验证创建的工件

运行静态代码分析

npm run lint
# 或：ruff check, cargo clippy, golangci-lint run

捕获退出代码
记录错误/警告

运行类型检查器（如果适用）
```
npm run typecheck
# 或：mypy, tsc --noEmit
```
- 捕获退出代码
- 记录类型错误
记录证据
- 使用模板 4（综合证据报告）
- 添加到共享上下文 quality_evidence
- 在任务完成消息中引用
标记任务完成（只有当所有证据通过时）

工作流程 2: 代码审查验证

何时： 审查另一个代理的代码或用户的PR

步骤：

阅读代码更改
验证测试存在
- 新功能有测试吗？
- 测试覆盖边缘情况吗？
- 更新了现有测试吗？
运行测试
- 执行测试套件
- 验证退出代码0
- 检查覆盖率没有下降
检查构建
- 确保项目仍然可以构建
- 没有新的构建错误
验证代码质量
- 运行静态代码分析
- 运行类型检查器
- 检查安全问题
记录审查证据
- 使用模板 3（代码质量证据）
- 记录任何发现的问题
- 添加到上下文
批准或请求更改
- 只有当所有证据通过时才批准
- 如果发现问题，用证据记录

工作流程 3: 生产部署验证

何时： 部署到生产或暂存

步骤：

预部署检查
- 所有测试通过（退出代码0）
- 构建成功
- 无关键静态代码分析错误
- 安全扫描通过
执行部署
- 运行部署命令
- 捕获输出
部署后检查
- 健康检查端点响应
- 应用程序成功启动
- 日志中没有立即错误
- 烟雾测试通过

记录部署证据

## 部署证据

**环境：** 生产
**时间戳：** YYYY-MM-DD HH:MM:SS
**版本：** vX.X.X

**预部署：**
- 测试：✅ 退出0
- 构建：✅ 退出0
- 安全：✅ 无关键问题

**部署：**
- 命令：`kubectl apply -f deployment.yaml`
- 退出代码：0 ✅

**部署后：**
- 健康检查：✅ 200 OK
- 烟雾测试：✅ 全部通过
- 错误率：<0.1%

验证回滚能力
- 确保可以恢复到以前的版本
- 记录回滚程序

证据存储

存储证据的位置

共享上下文（主要）

{
  "quality_evidence": {
    "tests_run": true,
    "test_exit_code": 0,
    "coverage_percent": 87,
    "build_success": true,
    "build_exit_code": 0,
    "linter_errors": 0,
    "linter_warnings": 2,
    "timestamp": "2025-11-02T10:30:00Z"
  }
}

证据文件（次要）

.claude/quality-gates/evidence/ 目录
每次验证运行一个文件
格式：{type}-{timestamp}.log
示例：tests-2025-11-02-103000.log

任务完成消息

包括证据摘要
链接到详细证据文件
示例：“任务完成。测试通过（退出0，87%覆盖率），构建成功。”

质量标准

可接受的最低标准

✅ 测试执行 并捕获退出代码 ✅ 记录时间戳 ✅ 在上下文中存储证据

生产级

✅ 测试通过（退出代码0） ✅ 覆盖率 ≥70%（或项目标准） ✅ 构建成功（退出代码0） ✅ 无关键静态代码分析错误 ✅ 类型检查器通过 ✅ 安全扫描 显示无关键问题

金标准

✅ 所有生产级要求 ✅ 覆盖率 ≥80% ✅ 无静态代码分析警告 ✅ 性能基准 在阈值内 ✅ 可访问性审计 通过（WCAG 2.1 AA） ✅ 集成测试 通过 ✅ 部署验证 完成

常见陷阱

❌ 不要跳过证据收集

坏：

"我已经实现了登录功能。它应该可以正确工作。"

好：

"我已经实现了登录功能。证据：
- 测试：退出代码 0，12 测试通过，0 失败
- 构建：退出代码 0，无错误
- 覆盖率：89%
任务完成并经过验证。"

❌ 不要伪造证据

坏：

"测试通过"（实际上没有运行）

好：

"测试通过。退出代码：0
命令：npm test
输出：测试套件：3 通过，3 总共
时间戳：2025-11-02 10:30:15"

❌ 不要忽略失败的证据

坏：

"构建失败，退出代码1，但代码看起来是正确的，所以标记为完成。"

好：

"构建失败，退出代码1。错误：
- TypeError: Cannot read property 'id' of undefined (line 42)
修复错误后再标记为完成。"

❌ 不要只收集一次证据

坏：

"测试昨天通过了，所以代码仍然没问题。"

好：

"在今天的更改后重新运行测试。
新证据：退出代码 0，45 测试通过，覆盖率 87%"

与其他系统的集成

上下文系统集成

证据自动跟踪在共享上下文中：

// 上下文结构包括：
{
  quality_evidence?: {
    tests_run: boolean;
    test_exit_code?: number;
    coverage_percent?: number;
    build_success?: boolean;
    linter_errors?: number;
    timestamp: string;
  }
}

质量门集成

证据收集输入质量门：

质量门检查证据是否存在
如果缺少证据则阻止任务完成
如果证据显示失败则升级

小队模式集成

在并行执行中：

每个代理独立收集证据
工作室教练在同步前验证证据
被阻止的任务不会浪费并行周期

快速参考

证据收集清单

在标记任务完成前：

- [ ] 测试执行
- [ ] 捕获测试退出代码（0 = 通过）
- [ ] 执行构建（如果适用）
- [ ] 捕获构建退出代码（0 = 通过）
- [ ] 运行代码质量检查（静态代码分析，类型）
- [ ] 用时间戳记录证据
- [ ] 在共享上下文中添加证据
- [ ] 在完成消息中添加证据摘要

按语言/框架的常见命令

JavaScript/TypeScript：

npm test                 # 运行测试
npm run build           # 构建项目
npm run lint            # 运行 ESLint
npm run typecheck       # 运行 TypeScript 编译器

Python：

pytest                  # 运行测试
pytest --cov           # 带覆盖率运行测试
ruff check .           # 运行静态代码分析
mypy .                 # 运行类型检查器

Rust：

cargo test             # 运行测试
cargo build            # 构建项目
cargo clippy           # 运行静态代码分析

Go：

go test ./...          # 运行测试
go build               # 构建项目
golangci-lint run      # 运行静态代码分析

示例

查看 /skills/evidence-verification/examples/ 了解：

样本证据报告
现实世界的验证场景
集成示例

版本历史

v1.0.0 - 初始发布

核心证据收集模板
验证工作流程
质量标准
与上下文系统集成

记住： 证据优先开发可以防止幻觉，确保生产质量，并建立信心。如果有疑问，收集更多证据，而不是更少。