# Harness Diagnose And Improve

> Harness Diagnose And Improve

- Skill: `konglong87/harness-diagnose-and-improve` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-diagnose-and-improve`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-diagnose-and-improve/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: konglong87 (https://skillmd.com/u/konglong87)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/konglong87/harness-diagnose-and-improve

---


# harness-diagnose-and-improve 错误诊断与改进技能

## 核心能力
1. 检查前置条件（harness-enable-circuit-breaker）
2. 读取错误追踪文件（ERROR_TRACE.md）
3. 分析错误根因（5 Why分析法）
4. 生成修复建议
5. 反哺规则到ERROR_HANDBOOK.md
6. 更新.learnings/ERRORS.md
7. 记录诊断事件
8. 更新全局状态

## 前置条件
- harness-init 已完成
- harness-enable-circuit-breaker 已完成
- ERROR_TRACE.md 文件存在（或可创建）

## 执行步骤

### Step 1: 检查前置条件

使用 Read 工具读取：`.EnjoyHarness/SKILL_REGISTRY.md`

检查条件：
- harness-enable-circuit-breaker 已标记为完成

如果未完成：
```
❌ 错误: 熔断机制未执行
💡 请先运行: harness-enable-circuit-breaker
```

### Step 2: 读取错误追踪文件

使用 Read 工具读取：`.trace/ERROR_TRACE.md`

如果文件不存在，使用 Write 工具创建：

```markdown
---
created_at: {当前时间}
total_errors: 0
---

# EnjoyHarness 错误追踪

## 错误记录格式
时间 | 任务ID | 技能 | 错误类型 | 错误详情 | 根因分析 | 修复方案

## 错误列表
（暂无错误记录）
```

### Step 3: 提取最近的错误

使用 Bash 工具查询：

```bash
# 获取最近的错误记录（最近5条）
RECENT_ERRORS=$(tail -5 .trace/ERROR_TRACE.md | grep "^20")

echo "最近的错误："
echo "$RECENT_ERRORS"
```

或者从GLOBAL_STATE.md中获取：

```bash
# 读取当前任务的错误信息
CURRENT_TASK=$(grep -A 20 "current_task" .EnjoyHarness/GLOBAL_STATE.md | grep "task_id" | awk '{print $2}')
ERROR_COUNT=$(grep -A 20 "current_task" .EnjoyHarness/GLOBAL_STATE.md | grep "error_count" | awk '{print $2}')

if [ "$ERROR_COUNT" -gt 0 ]; then
  echo "当前任务: $CURRENT_TASK"
  echo "错误计数: $ERROR_COUNT"
fi
```

### Step 4: 分析错误根因（5 Why分析法）

对每个错误执行：

```markdown
### 错误分析示例

**错误描述**: API调用超时

**5 Why分析**:
1. 为什么API调用超时？ → 网络请求耗时超过30秒
2. 为什么耗时超过30秒？ → 服务器响应慢
3. 为什么服务器响应慢？ → 数据库查询未优化
4. 为什么查询未优化？ → 缺少索引
5. 为什么缺少索引？ → 开发时未考虑性能

**根因**: 开发流程缺少性能审查环节

**修复方案**:
- 短期: 添加数据库索引
- 中期: 优化查询语句
- 长期: 增加性能审查流程
```

使用 Bash 工具生成分析：

```bash
ERROR_DESC="{错误描述}"

echo "=== 错误分析 ==="
echo "错误: $ERROR_DESC"
echo ""
echo "5 Why分析:"
echo "1. 为什么出现这个错误？"
read WHY1
echo "2. 为什么$WHY1？"
read WHY2
echo "3. 为什么$WHY2？"
read WHY3
echo "4. 为什么$WHY3？"
read WHY4
echo "5. 为什么$WHY4？"
read WHY5

echo ""
echo "根因: $WHY5"
echo ""
echo "修复方案:"
echo "短期: {快速修复}"
echo "中期: {流程改进}"
echo "长期: {架构优化}"
```

### Step 5: 生成修复建议

根据错误类型生成建议：

#### 类型1: 代码错误

```markdown
**错误类型**: 代码错误
**错误详情**: {具体错误}
**根因分析**: {5 Why分析结果}
**修复建议**:
1. 立即修复: {具体代码修改}
2. 代码审查: {审查重点}
3. 测试验证: {测试用例}
```

#### 类型2: 架构错误

```markdown
**错误类型**: 架构错误
**错误详情**: {架构违规}
**根因分析**: {5 Why分析结果}
**修复建议**:
1. 重构方案: {架构调整}
2. 迁移路径: {重构步骤}
3. 防止复发: {架构护栏规则}
```

#### 类型3: 流程错误

```markdown
**错误类型**: 流程错误
**错误详情**: {流程问题}
**根因分析**: {5 Why分析结果}
**修复建议**:
1. 流程优化: {改进方案}
2. 规则更新: {新增规则}
3. 自动化: {自动化检查}
```

### Step 6: 反哺规则到ERROR_HANDBOOK.md

使用 Read 工具读取：`.EnjoyHarness/ERROR_HANDBOOK.md`

如果文件不存在，使用 Write 工具创建基础结构：

```markdown
---
created_at: {当前时间}
version: v1.0.0
total_rules: 0
---

# EnjoyHarness 错误手册

## 错误分类

### 1. 代码错误
{代码错误规则列表}

### 2. 架构错误
{架构错误规则列表}

### 3. 流程错误
{流程错误规则列表}

## 错误处理规则

### 规则格式
```yaml
错误ID: {ERROR-XXX}
错误类型: {类型}
错误描述: {描述}
根因: {根本原因}
修复方案: {解决方案}
预防措施: {如何防止}
示例: {实际案例}
```

## 规则列表
（待添加）
```

使用 Edit 工具追加新规则：

```markdown
### {ERROR-001}: {错误名称}

**错误类型**: {类型}
**错误描述**: {详细描述}
**根因**: {根本原因}
**触发条件**: {何时发生}
**修复方案**:
- 立即修复: {快速方案}
- 根本修复: {彻底方案}
**预防措施**:
- 开发阶段: {如何预防}
- 测试阶段: {如何检测}
- 上线阶段: {如何监控}
**示例**:
```
{代码示例或场景描述}
```
**反哺日期**: {当前时间}
**来源任务**: {任务ID}
```

### Step 7: 更新.learnings/ERRORS.md

使用 Read 工具读取：`.learnings/ERRORS.md`

如果文件不存在，使用 Write 工具创建：

```markdown
---
created_at: {当前时间}
total_learnings: 0
---

# EnjoyHarness 错误学习记录

## 学习记录格式
日期 | 错误类型 | 关键教训 | 改进措施

## 学习列表
（暂无学习记录）
```

使用 Edit 工具追加学习记录：

```markdown
{当前时间} | {错误类型} | {关键教训} | {改进措施}
```

### Step 8: 生成诊断报告

使用 Write 工具创建文件：`.EnjoyHarness/DIAGNOSIS_REPORT.md`

```markdown
---
generated_at: {当前时间}
task_id: {任务ID}
error_count: {错误数量}
analyzed_count: {已分析数量}
---

# 错误诊断报告

## 诊断概况
- 诊断时间: {当前时间}
- 任务ID: {任务ID}
- 错误总数: {错误数量}
- 已分析数: {已分析数量}

## 错误分析

### 错误 1: {错误名称}
**错误描述**: {详细描述}
**错误类型**: {类型}
**发生时间**: {时间}
**发生技能**: {技能名称}

**5 Why分析**:
1. {Why 1}
2. {Why 2}
3. {Why 3}
4. {Why 4}
5. {Why 5}

**根因**: {根本原因}

**修复建议**:
- ✅ 立即修复: {方案}
- ✅ 中期改进: {方案}
- ✅ 长期优化: {方案}

**预防措施**: {如何防止复发}

---

## 错误统计

### 按类型统计
- 代码错误: {数量}次
- 架构错误: {数量}次
- 流程错误: {数量}次

### 按技能统计
- harness-validate-output: {数量}次
- harness-spawn-subharness-agent: {数量}次
- {其他技能}: {数量}次

## 反馈改进

### 已反哺规则
- {ERROR-XXX}: {规则名称}
- {ERROR-XXX}: {规则名称}

### 已更新文档
- ERROR_HANDBOOK.md: 新增{数量}条规则
- .learnings/ERRORS.md: 新增{数量}条学习记录

## 下一步行动

### 立即行动
- [ ] 修复错误（优先级: P0）
- [ ] 更新相关代码
- [ ] 执行测试验证

### 中期行动
- [ ] 更新开发流程
- [ ] 增加自动化检查
- [ ] 培训团队成员

### 长期行动
- [ ] 架构优化
- [ ] 重构遗留代码
- [ ] 持续监控指标
```

### Step 9: 记录诊断事件

使用 Edit 工具追加内容到：`.EnjoyHarness/EVENT_LOG.md`

```markdown
{当前时间} | ERROR_DIAGNOSIS | harness-diagnose-and-improve | 诊断错误: {数量}个 | SUCCESS
{当前时间} | RULE_FEEDBACK | harness-diagnose-and-improve | 反哺规则: {规则ID} | SUCCESS
```

### Step 10: 更新全局状态

使用 Edit 工具更新：`.EnjoyHarness/GLOBAL_STATE.md`

```yaml
last_diagnosis: {当前时间}
diagnosis_status: COMPLETED
errors_analyzed: {数量}
rules_added: {数量}
```

### Step 11: 更新事件计数

使用 Edit 工具更新：`.EnjoyHarness/EVENT_LOG.md`

old_string: `total_events: N`
new_string: `total_events: N+2`

### Step 12: 更新技能注册表

使用 Edit 工具更新：`.EnjoyHarness/SKILL_REGISTRY.md`

old_string: `- [ ] harness-diagnose-and-improve - 错误诊断技能`
new_string: `- [x] harness-diagnose-and-improve - 错误诊断技能 ✅`

### Step 13: 输出完成信息

使用 Bash 工具输出：

```bash
echo ""
echo "✅ harness-diagnose-and-improve 完成!"
echo ""
echo "🔍 诊断结果:"
echo " - 分析错误数: {数量}"
echo " - 反哺规则数: {数量}"
echo " - 更新文档数: {数量}"
echo ""
echo "📋 报告:"
echo " - 诊断报告: .EnjoyHarness/DIAGNOSIS_REPORT.md"
echo " - 错误手册: .EnjoyHarness/ERROR_HANDBOOK.md"
echo " - 学习记录: .learnings/ERRORS.md"
echo ""
echo "🎯 下一步:"
echo " - 执行修复建议"
echo " - 或触发 harness-evolve（自我进化）"
echo ""
```

## 成功标准
- [ ] 读取错误追踪文件
- [ ] 分析错误根因（5 Why）
- [ ] 生成修复建议
- [ ] 反哺规则到ERROR_HANDBOOK.md
- [ ] 更新.learnings/ERRORS.md
- [ ] 生成诊断报告
- [ ] 记录诊断事件
- [ ] 更新全局状态
- [ ] 更新事件日志
- [ ] 技能注册表已更新

## 失败兜底
- harness-enable-circuit-breaker 未完成 → 终止执行，提示运行前置技能
- 无错误记录 → 输出"暂无错误需要诊断"

## 联动关系
- 前置: harness-enable-circuit-breaker
- 自动触发: harness-evolve（自我进化）

## 迭代计数
本技能执行预计迭代次数: 约 12 次（Read 3次 + Write 2次 + Edit 5次 + Bash 2次）

## 测试用例

### 测试 1: 前置条件检查
**输入**: 在熔断机制未执行时运行
**期望输出**: 错误提示"熔断机制未执行"
**验证方式**: 删除熔断相关文件后运行

### 测试 2: 错误根因分析
**输入**: 提供一个具体的错误
**期望输出**: 完整的5 Why分析
**验证方式**: 手动提供错误，检查分析结果

### 测试 3: 反哺规则
**输入**: 分析错误后
**期望输出**: ERROR_HANDBOOK.md新增规则
**验证方式**: `grep "{ERROR-XXX}" .EnjoyHarness/ERROR_HANDBOOK.md`

### 测试 4: 学习记录更新
**输入**: 执行诊断后
**期望输出**: .learnings/ERRORS.md新增记录
**验证方式**: `tail -1 .learnings/ERRORS.md`

### 测试 5: 诊断报告生成
**输入**: 执行诊断
**期望输出**: 生成 DIAGNOSIS_REPORT.md
**验证方式**: `ls .EnjoyHarness/DIAGNOSIS_REPORT.md`

### 测试 6: 全局状态更新
**输入**: 读取 GLOBAL_STATE.md
**期望输出**: diagnosis_status 为 COMPLETED
**验证方式**: `grep "diagnosis_status" .EnjoyHarness/GLOBAL_STATE.md`

### 测试 7: 事件日志记录
**输入**: 读取 EVENT_LOG.md
**期望输出**: 包含 ERROR_DIAGNOSIS 事件
**验证方式**: `grep "ERROR_DIAGNOSIS" .EnjoyHarness/EVENT_LOG.md`

### 测试 8: 无错误情况
**输入**: 无错误记录时运行
**期望输出**: 输出"暂无错误需要诊断"
**验证方式**: 清空ERROR_TRACE.md后运行

## 5 Why分析法详解

### 方法论
```yaml
目的: 找到错误的根本原因，而不是表面现象
步骤:
  1. 描述问题
  2. 问"为什么"第1次
  3. 问"为什么"第2次
  4. 问"为什么"第3次
  5. 问"为什么"第4次
  6. 问"为什么"第5次
  7. 找到根因
  8. 制定修复方案

原则:
  - 不满足于表面答案
  - 每次问"为什么"都要深入一层
  - 根因通常是流程或系统问题，而非人为错误
```

### 示例分析

#### 示例 1: API调用失败
```yaml
问题: API调用返回500错误

Why 1: 服务器内部错误
Why 2: 数据库连接超时
Why 3: 数据库查询耗时过长
Why 4: 缺少必要索引
Why 5: 开发时未进行性能测试

根因: 开发流程缺少性能测试环节

修复方案:
  - 立即修复: 添加数据库索引
  - 中期改进: 优化查询语句
  - 长期优化: 增加性能测试流程
```

#### 示例 2: 代码编译失败
```yaml
问题: 编译报错"undefined variable"

Why 1: 变量未定义
Why 2: 变量名拼写错误
Why 3: 手动输入，未使用IDE自动补全
Why 4: 开发者不熟悉IDE功能
Why 5: 缺少IDE使用培训

根因: 开发培训不充分

修复方案:
  - 立即修复: 修正变量名
  - 中期改进: 使用IDE代码检查
  - 长期优化: 增加开发培训
```

## 错误分类体系

### 1. 代码错误
```yaml
类型:
  - 语法错误: 编译失败
  - 逻辑错误: 功能异常
  - 性能错误: 响应慢、资源占用高
  - 安全错误: 注入、XSS等

处理方式:
  - 立即修复代码
  - 增加单元测试
  - 代码审查
```

### 2. 架构错误
```yaml
类型:
  - 分层违规: 跨层调用
  - 循环依赖: 模块间循环引用
  - 设计缺陷: 架构设计不合理
  - 扩展性差: 难以扩展新功能

处理方式:
  - 重构架构
  - 增加架构护栏
  - 更新架构文档
```

### 3. 流程错误
```yaml
类型:
  - 需求误解: 需求理解偏差
  - 沟通不畅: 信息传递错误
  - 流程缺失: 缺少必要步骤
  - 自动化不足: 手动操作过多

处理方式:
  - 优化流程
  - 增加检查点
  - 自动化改进
```

## 反哺规则机制

### 反哺流程
```
[错误发生] → [错误记录] → [错误诊断]
↓
[根因分析] → [规则提取] → [规则验证]
↓
[反哺到ERROR_HANDBOOK.md]
↓
[后续开发使用规则预防]
```

### 规则模板
```yaml
错误ID: ERROR-{序号}
错误类型: {类型}
错误描述: {详细描述}
触发条件: {何时发生}
根因分析: {根本原因}
修复方案:
  立即修复: {方案}
  中期改进: {方案}
  长期优化: {方案}
预防措施:
  开发阶段: {措施}
  测试阶段: {措施}
  上线阶段: {措施}
示例: {实际案例}
反哺日期: {日期}
来源任务: {任务ID}
```

## 使用示例

### 示例 1: 诊断单个错误
```yaml
错误: API调用超时
分析: 5 Why → 根因: 缺少性能测试
反哺: ERROR-001 → "性能测试规则"
修复: 添加索引 + 性能测试流程
结果: 错误修复，规则反哺
```

### 示例 2: 批量诊断多个错误
```yaml
错误列表: 3个错误
- 错误1: 代码错误 → 根因: 缺少代码审查
- 错误2: 架构错误 → 根因: 架构规则不明确
- 错误3: 流程错误 → 根因: 需求文档不清晰

反哺规则: 3条
- ERROR-001: 代码审查规则
- ERROR-002: 架构设计规则
- ERROR-003: 需求文档规则

结果: 批量反哺，系统改进
```

## 与其他技能的协作

### 协作流程
```
harness-enable-circuit-breaker（检测错误）
↓
harness-diagnose-and-improve（诊断根因）
↓
harness-evolve（自我进化）
```

### 协作示例
```yaml
场景: 任务执行失败

阶段1: 错误检测
- harness-enable-circuit-breaker → 检测到错误

阶段2: 错误诊断
- harness-diagnose-and-improve → 分析根因
  ├─ 5 Why分析
  ├─ 生成修复建议
  └─ 反哺规则

阶段3: 自我进化
- harness-evolve → 应用规则
  ├─ 更新ERROR_HANDBOOK.md
  ├─ 清理技术债
  └─ 持续改进
```