质量门技能

版本： 1.0.0 类型： 质量保证与风险管理 自动激活： 任务计划、复杂性评估、需求收集、任务执行前

概览

这个技能教会代理如何评估任务复杂性，执行质量门，并防止在不完整或定义不当的任务上浪费工作。受生产级开发实践的启发，质量门确保代理在继续之前有足够的上下文，并在遇到阻碍或阻塞时自动升级。

关键原则： 在继续之前停下来澄清。提问比在错误的解决方案上浪费周期更好。

何时使用此技能

自动激活触发器

接收到新的任务分配
开始复杂的功能实现
在团队模式下分配工作前
当需求看起来不清晰或不完整时
在同一个任务上失败3次后
当被依赖关系阻塞时

手动激活

用户要求复杂性评估
规划多步骤项目
在承诺时间线前
当对需求不确定时

核心概念

1. 复杂性评分（1-5分制）

评估每个任务在1-5的复杂性分制上：

1级：简单

单个文件更改
简单变量重命名
文档更新
CSS样式调整
< 50行代码
< 30分钟估计
无依赖
无未知数

2级：简单

1-3个文件更改
基本函数实现
简单的API端点（CRUD）
直接的组件
50-200行代码
30分钟 - 2小时估计
0-1个依赖
最小未知数

3级：中等

3-10个文件更改
多个组件协调
带验证和错误处理的API
状态管理集成
数据库模式更改
200-500行代码
2-8小时估计
2-3个依赖
一些需要研究的未知数

4级：复杂

10-25个文件更改
跨领域关注点
认证/授权
实时特性（WebSockets）
支付集成
带数据的数据库迁移
500-1500行代码
8-24小时（1-3天）估计
4-6个依赖
显著的未知数
多个决策点

5级：非常复杂

25+个文件更改
架构更改
新服务/微服务
完整的功能子系统
第三方API集成
性能优化
1500+行代码
24+小时（3+天）估计
7+个依赖
许多未知数
需要研究和原型制作
范围蔓延的高风险

2. 质量门阈值

阻塞条件（必须在继续之前解决）：

不完整的需求（>3个关键问题）
- 如果你有超过3个未回答的关键问题，停止
- 关键问题的例子：
  - “当X失败时应该发生什么？”
  - “我应该使用什么数据结构？”
  - “对于边缘情况Y的预期行为是什么？”
  - “我应该调用哪个API？”
  - “什么认证方法？”
缺少依赖（被另一个任务阻塞）
- 任务依赖于不完整的工作
- 所需的API端点不存在
- 数据库模式未准备好
- 外部服务未配置
卡住检测（同一个任务尝试3次）
- 尝试了3种不同的方法，都失败了
- 持续遇到相同的错误
- 找不到必要的信息
- 解决方案不断破坏其他事情
证据失败（测试/构建失败）
- 测试失败后2次修复尝试
- 更改后构建中断
- 类型错误持续存在
- 集成测试失败
复杂性溢出（未分解的4-5级任务）
- 复杂任务未分解为子任务
- 没有清晰的实施计划
- 太多未知数
- 范围不清晰

警告条件（可以谨慎继续）：

中等复杂性（3级）
- 可以继续但应首先验证方法
- 记录假设
- 计划检查点
1-2个未回答问题
- 记录假设
- 用最佳猜测继续
- 稍后审查备注
1-2次失败尝试
- 尝试替代方法
- 记录为什么不工作
- 考虑寻求帮助

3. 门验证过程

## 质量门检查

**任务：** [任务描述]
**复杂性：** [1-5分制]
**依赖：** [列出依赖]

### 关键问题（在继续之前必须回答）
1. [问题1] - ✅ 已回答 / ❌ 未知
2. [问题2] - ✅ 已回答 / ❌ 未知
3. [问题3] - ✅ 已回答 / ❌ 未知

**未回答的关键问题：** [计数]

### 依赖检查
- [ ] 所有所需API存在
- [ ] 数据库模式准备就绪
- [ ] 所需服务正在运行
- [ ] 外部API可访问
- [ ] 认证配置

**阻塞依赖：** [列出]

### 尝试历史
- 尝试1：[尝试了什么，结果]
- 尝试2：[尝试了什么，结果]
- 尝试3：[尝试了什么，结果]

**失败尝试：** [计数]

### 门状态
- ✅ **通过** - 可以继续
- ⚠️ **警告** - 谨慎继续
- ❌ **阻塞** - 必须在继续之前解决

### 阻塞原因（如果阻塞）
- [ ] >3个关键问题未回答
- [ ] 缺少依赖
- [ ] 3+失败尝试（卡住）
- [ ] 证据显示失败
- [ ] 复杂性太高没有计划

### 所需行动
[列出需要解除阻塞的行动]

质量门工作流程

工作流程1：任务前门验证

何时： 在开始任何任务（尤其是3-5级）之前

步骤：

评估复杂性

阅读任务描述
计算需要更改的文件数量
估计代码行数
识别依赖
计算未知数
→ 分配复杂性分数（1-5）

识别关键问题

我必须知道什么才能完成这个？
- 数据结构？
- 预期行为？
- 边缘情况？
- 错误处理？
- API合同？

→ 列出所有关键问题
→ 计算未回答的问题

检查依赖

这个任务依赖于什么？
- 其他任务？
- 外部服务？
- 数据库更改？
- 配置？

→ 验证依赖准备就绪
→ 列出阻塞器

门决策

if (unansweredQuestions > 3) → 阻塞
if (missingDependencies > 0) → 阻塞
if (complexity >= 4 && !hasPlan) → 阻塞
if (complexity == 3) → 警告
else → 通过

在上下文中记录

context.tasks_pending.push({
  id: 'task-' + Date.now(),
  task: "任务描述",
  complexity_score: 3,
  gate_status: 'pass',
  critical_questions: [...],
  dependencies: [...],
  timestamp: new Date().toISOString()
});

工作流程2：卡住检测与升级

何时： 在多次尝试同一任务后

步骤：

跟踪尝试

// 在上下文中跟踪尝试
if (!context.attempt_tracking) {
  context.attempt_tracking = {};
}

if (!context.attempt_tracking[taskId]) {
  context.attempt_tracking[taskId] = {
    attempts: [],
    first_attempt: new Date().toISOString()
  };
}

context.attempt_tracking[taskId].attempts.push({
  timestamp: new Date().toISOString(),
  approach: "描述尝试的内容",
  outcome: "失败因为X",
  error_message: "错误详情"
});

检查阈值

const attemptCount = context.attempt_tracking[taskId].attempts.length;

if (attemptCount >= 3) {
  // 升级 - 卡住
  return {
    status: 'blocked',
    reason: 'stuck_after_3_attempts',
    escalate_to: 'user',
    attempts_history: context.attempt_tracking[taskId].attempts
  };
}

升级消息

## 🚨 升级：任务卡住

**任务：** [任务描述]
**尝试：** 3
**状态：** 阻塞 - 需要人类指导

### 尝试了什么
1. **尝试1：** [方法] → 失败：[原因]
2. **尝试2：** [方法] → 失败：[原因]
3. **尝试3：** [方法] → 失败：[原因]

### 当前阻塞者
[持续问题的详细描述]

### 需要指导
- [需要人类输入的具体问题1]
- [需要人类输入的具体问题2]

**建议：** 需要人类审查以解除阻塞

工作流程3：复杂性分解（4-5级）

何时： 被分配一个4或5级复杂性任务时

步骤：

分解为子任务

## 任务分解：[主要任务]
**整体复杂性：** 4级

### 子任务
1. **子任务1：** [描述]
   - 复杂性：2级
   - 依赖：无
   - 估计：2小时

2. **子任务2：** [描述]
   - 复杂性：3级
   - 依赖：子任务1
   - 估计：4小时

3. **子任务3：** [描述]
   - 复杂性：2级
   - 依赖：子任务2
   - 估计：2小时

**总估计：** 8小时
**复杂性检查：** 所有子任务 ≤ 3级 ✅

验证分解

检查：
- [ ] 所有子任务都是1-3级
- [ ] 依赖清晰映射
- [ ] 每个子任务都有清晰的接受标准
- [ ] 总估计合理
- [ ] 没有重叠工作

创建执行计划

## 执行计划

**阶段1：** 子任务1
- 开始：在需求确认后
- 门检查：通过
- 证据：测试通过，构建成功

**阶段2：** 子任务2
- 开始：子任务1完成后
- 门检查：验证子任务1的证据
- 证据：集成测试通过

**阶段3：** 子任务3
- 开始：子任务2完成后
- 门检查：端到端验证
- 证据：全功能测试通过

工作流程4：需求完整性检查

何时： 开始一个新功能或重要任务时

步骤：

功能需求检查

## 功能需求

- [ ] **定义了快乐路径：** 一切正常时应该发生什么？
- [ ] **定义了错误案例：** 事情失败时应该发生什么？
- [ ] **识别了边缘案例：** 边界条件是什么？
- [ ] **输入验证：** 哪些输入是有效的/无效的？
- [ ] **输出格式：** 输出应该是什么样子？
- [ ] **成功标准：** 我们怎么知道它有效？

技术需求检查

## 技术需求

- [ ] **API合同：** 端点、方法、模式定义了吗？
- [ ] **数据结构：** 模型、类型、接口指定了吗？
- [ ] **数据库更改：** 需要模式迁移吗？
- [ ] **认证：** 谁可以访问这个？
- [ ] **性能：** 有任何延迟/吞吐量要求吗？
- [ ] **安全：** 有任何特别的安全考虑吗？

计算关键未知数

const criticalUnknowns = [
  !functionalRequirements.happyPath,
  !functionalRequirements.errorCases,
  !technicalRequirements.apiContracts,
  !technicalRequirements.dataStructures
].filter(unknown => unknown).length;

if (criticalUnknowns > 3) {
  return {
    gate_status: 'blocked',
    reason: 'incomplete_requirements',
    critical_unknowns: criticalUnknowns,
    action: 'clarify_requirements'
  };
}

质量门模板

模板1：任务前门检查

# 质量门：[任务名称]

**日期：** [YYYY-MM-DD]
**代理：** [代理名称]

## 复杂性评估

**估计代码行数：** [X]
**估计持续时间：** [X小时]
**文件更改：** [X文件]
**依赖：** [X依赖]
**未知数：** [X未知数]

**复杂性分数：** 级别[1-5]

## 关键问题

1. [问题1] - ✅ 已回答 / ❌ 未知
2. [问题2] - ✅ 已回答 / ❌ 未知
3. [问题3] - ✅ 已回答 / ❌ 未知

**未回答：** [计数]

## 依赖检查

**所需：**
- [ ] [依赖1] - 准备就绪 / 阻塞
- [ ] [依赖2] - 准备就绪 / 阻塞

**阻塞者：** [列出]

## 门决策

**状态：** ✅ 通过 / ⚠️ 警告 / ❌ 阻塞

**理由：** [为什么这个决定]

**所需行动：** [如果阻塞或警告]

**可以继续：** 是 / 否

模板2：卡住升级

# 升级：任务卡住

**任务：** [任务描述]
**代理：** [代理名称]
**日期：** [YYYY-MM-DD]

## 尝试历史

**尝试1** ([时间戳])
- **方法：** [尝试了什么]
- **结果：** 失败
- **错误：** [错误消息或问题]

**尝试2** ([时间戳])
- **方法：** [尝试了什么]
- **结果：** 失败
- **错误：** [错误消息或问题]

**尝试3** ([时间戳])
- **方法：** [尝试了什么]
- **结果：** 失败
- **错误：** [错误消息或问题]

## 当前阻塞者

[持续问题的详细描述]

## 需要指导

1. [需要人类输入的具体问题1]
2. [需要人类输入的具体问题2]

## 建议

**升级到：** 用户 / 工作室教练 / 特定代理

**建议行动：** [可能会解除阻塞的内容]

模板3：复杂性分解

# 任务分解：[主要任务]

**原始复杂性：** 级别[4-5]
**目标：** 分解为1-3级子任务

## 子任务

### 子任务1：[名称]
- **复杂性：** 级别[X]
- **估计持续时间：** [X小时]
- **依赖：** [无 / 列出]
- **接受标准：**
  - [ ] [标准1]
  - [ ] [标准2]

### 子任务2：[名称]
- **复杂性：** 级别[X]
- **估计持续时间：** [X小时]
- **依赖：** [列出]
- **接受标准：**
  - [ ] [标准1]
  - [ ] [标准2]

### 子任务3：[名称]
- **复杂性：** 级别[X]
- **估计持续时间：** [X小时]
- **依赖：** [列出]
- **接受标准：**
  - [ ] [标准1]
  - [ ] [标准2]

## 验证

- [ ] 所有子任务 ≤ 3级
- [ ] 依赖清晰映射
- [ ] 没有循环依赖
- [ ] 接受标准清晰
- [ ] 总估计合理

**可以继续：** 是 / 否

与上下文系统集成

质量门与上下文系统集成以跟踪：

// 添加门检查到上下文
context.quality_gates = context.quality_gates || [];
context.quality_gates.push({
  task_id: taskId,
  timestamp: new Date().toISOString(),
  complexity_score: 3,
  gate_status: 'pass', // 通过，警告，阻塞
  critical_questions_count: 1,
  unanswered_questions: 1,
  dependencies_blocked: 0,
  attempt_count: 0,
  can_proceed: true
});

与证据系统集成

质量门在允许完成之前检查证据：

// 在标记任务完成前
const evidence = context.quality_evidence;
const hasPassingEvidence = (
  evidence?.tests?.exit_code === 0 ||
  evidence?.build?.exit_code === 0
);

if (!hasPassingEvidence) {
  return {
    gate_status: 'blocked',
    reason: 'no_passing_evidence',
    action: 'collect_evidence_first'
  };
}

最佳实践

1. 始终在开始前运行门检查

// ❌ 坏的：立即开始
function startTask(task) {
  implementTask(task);
}

// ✅ 好的：首先门检查
function startTask(task) {
  const gateCheck = runQualityGate(task);

  if (gateCheck.status === 'blocked') {
    escalate(gateCheck.reason);
    return;
  }

  if (gateCheck.status === 'warning') {
    documentAssumptions(gateCheck.warnings);
  }

  implementTask(task);
}

2. 记录所有假设

当继续警告时，记录假设：

## 做出的假设
1. **假设：** API将返回JSON格式
   **风险：** 低 - 标准REST实践
   **缓解：** 添加解析的try-catch

2. **假设：** 用户认证已经实现
   **风险：** 中等 - 可能不存在
   **缓解：** 提前检查，如果缺失则升级

3. 跟踪尝试以检测卡住

// 跟踪每次尝试
function attemptTask(taskId, approach) {
  trackAttempt(taskId, approach);

  const attemptCount = getAttemptCount(taskId);
  if (attemptCount >= 3) {
    escalateToUser(taskId);
    return 'blocked';
  }

  return executeApproach(approach);
}

4. 主动分解复杂任务

// ❌ 坏的：直接处理5级任务
implementComplexFeature();

// ✅ 好的：首先分解
function handleComplexTask(task) {
  if (task.complexity >= 4) {
    const subtasks = breakDownIntoSubtasks(task);

    subtasks.forEach(subtask => {
      runQualityGate(subtask);
      implementSubtask(subtask);
    });
  } else {
    implementTask(task);
  }
}

常见陷阱

❌ 陷阱1：跳过"简单"任务的门检查

**问题：** 假设任务简单，跳过门检查，后来卡住
**解决方案：** 始终运行门检查，即使是1-2级任务（快速检查）

❌ 陷阱2：忽略警告状态

**问题：** 继续警告而不记录假设
**解决方案：** 当继续警告时记录每个假设

❌ 陷阱3：不跟踪尝试

**问题：** 反复尝试相同的方法，浪费周期
**解决方案：** 跟踪每次尝试，3次后升级

❌ 陷阱4：在阻塞时继续

**问题：** 门说阻塞但还是继续"为了取得进展"
**解决方案：** 永远不要绕过阻塞门 - 先解决阻塞者

快速参考

复杂性快速检查

1-3个文件，<200行，<2小时 → 级别1-2
3-10个文件，200-500行，2-8小时 → 级别3
10-25个文件，500-1500行，8-24小时 → 级别4
25+个文件，1500+行，24+小时 → 级别5

阻塞阈值快速检查

3个关键问题未回答 → 阻塞
缺少依赖 → 阻塞
3+失败尝试 → 阻塞 & 升级
未分解的4-5级 → 阻塞

门决策快速流程

1. 评估复杂性（1-5）
2. 计算未回答的关键问题
3. 检查被阻塞的依赖
4. 检查尝试次数

if (问题 > 3 || 依赖被阻塞 || 尝试次数 >= 3) → 阻塞
else if (复杂性 >= 4 && 无计划) → 阻塞
else if (复杂性 == 3 || 问题 1-2) → 警告
else → 通过

版本历史

v1.0.0 - 初始发布

复杂性评分（1-5分制）
阻塞阈值
卡住检测和升级
需求完整性检查
上下文集成
模板和工作流程

记住： 质量门防止浪费工作。最好提前提问，而不是构建错误的解决方案。如果有疑问，阻塞并升级。