# Harness Check Clean State

> Harness Check Clean State

- Skill: `konglong87/harness-check-clean-state` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add konglong87/harness-check-clean-state`
- Raw SKILL.md: https://api.skillmd.com/api/skills/konglong87/harness-check-clean-state/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-check-clean-state

---


# harness-check-clean-state

## Core Capabilities

执行清洁状态检查清单，验证系统是否达到"清洁状态"（会话结束时，代码应达到可合并到主分支的状态）。

**核心职责**：
1. 检查代码质量（编译、测试、Linter）
2. 检查 Git 状态（未提交更改、提交信息格式）
3. 检查功能完成度（feature_list.json 标记）
4. 检查文档更新（EVENT_LOG.md、GLOBAL_STATE.md）
5. 检查可合并性（无冲突、无 TODO/FIXME）
6. 返回检查结果（CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES）

## Execution Steps

### Step 1: 读取清洁状态检查清单

```yaml
工具: Read
文件: .EnjoyHarness/CLEAN_STATE_CHECKLIST.md
Token 消耗: ~1000 tokens
```

### Step 2: 检查代码质量

#### 2.1 检查编译

```yaml
工具: Bash
命令: make build（或项目特定编译命令）
Token 消耗: ~500 tokens
失败处理:
  - 返回 CRITICAL_ISSUES
  - 记录错误到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
  - 退出检查（不继续后续步骤）
```

#### 2.2 检查测试

```yaml
工具: Bash
命令: make test（或项目特定测试命令）
Token 消耗: ~1000 tokens
失败处理:
  - 返回 MODERATE_ISSUES
  - 记录错误到 EVENT_LOG.md（MODERATE_ISSUES | TEST_FAILED）
  - 继续检查其他项（收集完整问题列表）
```

#### 2.3 检查 Linter

```yaml
工具: Bash
命令: make lint（或项目特定 Linter 命令）
Token 消耗: ~500 tokens
失败处理:
  - 记录 MINOR_ISSUES
  - 记录警告到 EVENT_LOG.md（MINOR_ISSUES | LINTER_WARNING）
  - 继续检查其他项
```

### Step 3: 检查 Git 状态

```yaml
工具: Bash
命令: git status --porcelain
验证: 输出为空（无未提交更改）
Token 消耗: ~100 tokens
失败处理:
  - 如果输出非空 → 记录 MINOR_ISSUES
  - 检查未跟踪文件（git status --short | grep "^??"）
```

### Step 4: 检查功能完成度

```yaml
工具: Read
文件: .EnjoyHarness/feature_list.json
Token 消耗: ~800 tokens

验证逻辑:
  1. 读取当前功能ID（从 GLOBAL_STATE.md）
  2. 在 feature_list.json 中查找该功能
  3. 验证 passes 字段是否为 true

失败处理:
  - 如果 passes: false → 记录 MODERATE_ISSUES
  - 记录到 EVENT_LOG.md（MODERATE_ISSUES | FEATURE_NOT_COMPLETED）
```

### Step 5: 检查文档更新

#### 5.1 检查 EVENT_LOG.md

```yaml
工具: Bash
命令: grep "SESSION_END" .EnjoyHarness/EVENT_LOG.md
Token 消耗: ~200 tokens
失败处理:
  - 如果未找到 → 记录 MINOR_ISSUES
```

#### 5.2 检查 GLOBAL_STATE.md

```yaml
工具: Read
文件: .EnjoyHarness/GLOBAL_STATE.md
Token 消耗: ~200 tokens
验证: 任务状态是否为 completed
失败处理:
  - 如果不是 → 记录 MINOR_ISSUES
```

### Step 6: 检查可合并性

#### 6.1 检查 Git 合并状态

```yaml
工具: Bash
命令: git merge-base --is-ancestor HEAD main
Token 消耗: ~100 tokens
失败处理:
  - 如果失败 → 记录 MODERATE_ISSUES
```

#### 6.2 检查 TODO/FIXME

```yaml
工具: Bash
命令: grep -r "TODO\|FIXME" --include="*.py" --include="*.go" --include="*.js" || true
Token 消耗: ~200 tokens
验证: 输出为空（无未处理的 TODO/FIXME）
失败处理:
  - 如果找到 → 记录 MINOR_ISSUES
```

### Step 7: 输出检查结果

```yaml
结果类型:
  CLEAN: 所有检查通过
  MINOR_ISSUES: 轻微问题（Linter 警告、Git 未提交、文档未更新）
  MODERATE_ISSUES: 中等问题（测试失败、架构违规、功能未完成）
  CRITICAL_ISSUES: 严重问题（编译失败、文件损坏）

输出格式:
  检查结果: CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
  检查项总数: 15
  通过项数: X
  失败项数: Y
  失败项列表:
    - [ ] 代码编译
    - [ ] 测试通过
    - [x] Linter 无警告
    ...

Token 消耗: ~200 tokens
```

### Step 8: 记录到 EVENT_LOG.md

```yaml
工具: Edit
文件: .EnjoyHarness/EVENT_LOG.md
追加内容:
  - 时间戳：2026-03-28T12:30:00
  - 事件类型：CLEAN_STATE_CHECK
  - 检查结果：CLEAN/MINOR_ISSUES/MODERATE_ISSUES/CRITICAL_ISSUES
  - 检查项详情
Token 消耗: ~100 tokens
```

## Prerequisites

**必须满足**：
- ✅ 已执行 `harness-validate-output`（架构验证通过）
- ✅ 功能开发完成（工作流最后一个节点执行完成）

**如果前置条件不满足**：
- 提示用户先完成功能开发和验证
- 拒绝继续执行

## Success Criteria

**成功标准**：
1. ✅ 成功执行所有检查项（15 项）
2. ✅ 正确识别问题级别（CLEAN/MINOR/MODERATE/CRITICAL）
3. ✅ 输出详细的检查结果（通过项、失败项列表）
4. ✅ 记录检查事件到 `EVENT_LOG.md`

**失败情况**：
- ❌ 检查脚本执行失败 → 记录错误，返回 CRITICAL_ISSUES
- ❌ 文件读取失败 → 记录错误，返回 MODERATE_ISSUES

## Failure Recovery

### 错误场景 1: 编译失败（CRITICAL_ISSUES）

```yaml
处理:
  1. 返回 CRITICAL_ISSUES
  2. 记录到 EVENT_LOG.md（CRITICAL_ISSUES | BUILD_FAILED）
  3. 触发 harness-recover-clean-state（自动回滚）
  4. 退出检查
```

### 错误场景 2: 测试失败（MODERATE_ISSUES）

```yaml
处理:
  1. 记录 MODERATE_ISSUES
  2. 继续检查其他项（收集完整问题列表）
  3. 检查完成后触发 harness-recover-clean-state
```

### 错误场景 3: Linter 警告（MINOR_ISSUES）

```yaml
处理:
  1. 记录 MINOR_ISSUES
  2. 继续检查其他项
  3. 检查完成后触发 harness-recover-clean-state
```

### 错误场景 4: Git 状态不清洁（MINOR_ISSUES）

```yaml
处理:
  1. 记录 MINOR_ISSUES
  2. 继续检查其他项
  3. 检查完成后触发 harness-recover-clean-state
```

## Relationships

### Triggers (触发下游)

```yaml
如果检查结果 == CLEAN:
  - 触发 harness-track-feature-progress（标记功能完成）

如果检查结果 != CLEAN:
  - 触发 harness-recover-clean-state（自动修复或回滚）
```

### Triggered By (被谁触发)

```yaml
触发时机:
  - harness-validate-output 验证通过后
  - 子代理开发完成后
  - 用户显式调用："清洁状态检查"
```

### Dependencies (前置依赖)

```yaml
必须依赖:
  - harness-validate-output（架构验证）
```

## Token 消耗分析

```yaml
完整检查流程:
  - 读取检查清单: ~1000 tokens
  - 代码质量检查: ~2000 tokens
  - Git 状态检查: ~100 tokens
  - 功能完成度检查: ~800 tokens
  - 文档更新检查: ~400 tokens
  - 可合并性检查: ~300 tokens
  - 输出检查结果: ~200 tokens
  - 记录 EVENT_LOG: ~100 tokens
  总计: ~4900 tokens

优化方案:
  - 仅检查必要项（跳过手动检查项）
  - Token 消耗降低至 ~3400 tokens
```

## Examples

### 示例 1: 所有检查通过（CLEAN）

```yaml
输入:
  - make build: 成功
  - make test: 成功
  - make lint: 成功
  - git status: 空输出
  - feature_list.json: passes: true
  - EVENT_LOG.md: 包含 SESSION_END

处理:
  1. 执行所有检查项（15 项）
  2. 所有检查通过
  3. 返回 CLEAN

输出:
  ✅ 检查结果: CLEAN
  检查项总数: 15
  通过项数: 15
  失败项数: 0

  所有检查项:
  - [x] 代码编译通过
  - [x] 测试通过
  - [x] Linter 无警告
  - [x] Git 状态清洁
  - [x] 功能标记完成
  - [x] 文档已更新

  下一步：触发 harness-track-feature-progress（标记功能完成）
```

### 示例 2: 测试失败（MODERATE_ISSUES）

```yaml
输入:
  - make build: 成功
  - make test: 失败（2 个测试用例失败）
  - make lint: 成功
  - git status: 空输出

处理:
  1. 执行所有检查项
  2. 发现测试失败
  3. 记录 MODERATE_ISSUES
  4. 继续检查其他项（收集完整问题列表）

输出:
  ⚠️ 检查结果: MODERATE_ISSUES
  检查项总数: 15
  通过项数: 14
  失败项数: 1

  失败项列表:
  - [ ] 测试通过（2 个测试用例失败）

  下一步：触发 harness-recover-clean-state（自动修复）
```

### 示例 3: 编译失败（CRITICAL_ISSUES）

```yaml
输入:
  - make build: 失败（语法错误）

处理:
  1. 执行编译检查
  2. 发现编译失败
  3. 返回 CRITICAL_ISSUES
  4. 退出检查（不继续后续步骤）

输出:
  🔴 检查结果: CRITICAL_ISSUES
  检查项总数: 15
  通过项数: 0
  失败项数: 1

  失败项列表:
  - [ ] 代码编译（语法错误）

  下一步：触发 harness-recover-clean-state（立即回滚）
```

### 示例 4: Git 状态不清洁（MINOR_ISSUES）

```yaml
输入:
  - make build: 成功
  - make test: 成功
  - git status: 有未提交更改（2 个文件）

处理:
  1. 执行所有检查项
  2. 发现 Git 状态不清洁
  3. 记录 MINOR_ISSUES
  4. 继续检查其他项

输出:
  ⚠️ 检查结果: MINOR_ISSUES
  检查项总数: 15
  通过项数: 14
  失败项数: 1

  失败项列表:
  - [ ] Git 状态清洁（2 个文件未提交）

  下一步：触发 harness-recover-clean-state（自动提交）
```

## Implementation Notes

### 关键设计决策

1. **分级错误处理**
   - CLEAN: 无问题，可继续
   - MINOR_ISSUES: 轻微问题，自动修复
   - MODERATE_ISSUES: 中等问题，尝试修复，失败则回滚
   - CRITICAL_ISSUES: 严重问题，立即回滚

2. **检查顺序**
   - 编译优先（CRITICAL_ISSUES 立即退出）
   - 测试其次（MODERATE_ISSUES 继续收集问题）
   - Linter 和 Git 最后（MINOR_ISSUES 继续检查）

3. **问题收集**
   - 编译失败立即退出（不继续检查）
   - 其他问题继续检查（收集完整问题列表）
   - 便于一次性修复所有问题

### 性能优化

```yaml
并行检查:
  - 代码质量检查（编译、测试、Linter）可并行
  - Git 状态检查和文档更新检查可并行
  - 预计检查时长：2-5 分钟

跳过手动检查:
  - 端到端验证（手动）
  - 下一位开发者可直接开始工作（手动）
  - Token 消耗降低 ~20%
```