# Harness Plan

> 计划编写技能，将设计文档拆分为bite-sized任务，生成详细实施计划

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

---


# harness-plan 计划编写技能

## 核心能力
1. 检查前置条件（harness-brainstorm已完成）
2. 读取设计文档
3. 分解为bite-sized任务（每个任务2-5分钟）
4. 编写详细实施计划
5. 应用自动执行策略（默认优先推荐选项）
6. 触发实施执行

## 前置条件
- harness-init 已完成
- harness-brainstorm 已完成
- 设计文档已存在（`docs/plans/*.md`）
- `.EnjoyHarness/EXECUTION_CONTRACT.md` 已标记 `requirements_confirmed: true`

## 执行步骤

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

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

检查条件：
- harness-brainstorm 已标记为完成
- `mode: autonomous_after_confirmation`
- `requirements_confirmed: true`

如果未完成：
```
❌ 错误: 未完成头脑风暴
💡 请先运行: harness-brainstorm
```

如果需求尚未最终确认：
```
❌ 错误: 需求尚未冻结
💡 请先在 harness-brainstorm 完成最终需求确认并冻结 EXECUTION_CONTRACT.md
```

### Step 2: 读取设计文档

使用 Bash 工具查找设计文档：

```bash
# 查找最新的设计文档
ls -t docs/plans/*-design.md | head -1

# 或者使用用户指定的设计文档
# 如果用户指定了设计文档，使用指定文档
```

使用 Read 工具读取：设计文档路径（例如 `docs/plans/2026-03-28-user-auth-design.md`）

### Step 3: 分析设计文档

分析内容：
- 功能目标
- 架构设计
- 核心组件
- 数据模型
- API设计
- 错误处理
- 测试策略

### Step 4: 分解为bite-sized任务

**任务粒度原则**：
每个任务是一个动作（2-5分钟）：
- "编写失败的测试" - 一个任务
- "运行测试验证失败" - 一个任务
- "实现最小代码使测试通过" - 一个任务
- "运行测试验证通过" - 一个任务
- "提交代码" - 一个任务

**任务分类**：
1. 环境准备（创建目录、配置文件）
2. 数据模型实现（结构体定义）
3. 接口实现（Handler/Service/Repository）
4. 业务逻辑实现（核心算法）
5. 错误处理实现
6. 测试编写
7. 文档更新
8. Git提交

### Step 5: 编写实施计划

使用 Write 工具创建文件：`docs/plans/{YYYY-MM-DD}-{feature}-implementation-plan.md`

**计划文档头部（必须包含）**：

```markdown
# [功能名称] 实施计划

> **For Claude:** REQUIRED SUB-SKILL: Use harness-executing-plans to implement this plan task-by-task.

**Goal:** [一句话描述构建什么]

**Architecture:** [2-3句话描述方法]

**Tech Stack:** [关键技术/库]

---

## 实施阶段概览

[阶段划分和任务列表]

---
```

**任务结构模板**：

```markdown
### Task N: [组件名称]

**Files:**
- Create: `确切路径/文件名.py`
- Modify: `确切路径/现有文件.py:123-145`
- Test: `tests/确切路径/测试文件.py`

**Step 1: 编写失败的测试**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: 运行测试验证失败**

运行：`pytest tests/path/test.py::test_name -v`
预期：FAIL，提示 "function not defined"

**Step 3: 编写最小实现**

```python
def function(input):
    return expected
```

**Step 4: 运行测试验证通过**

运行：`pytest tests/path/test.py::test_name -v`
预期：PASS

**Step 5: 提交代码**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```
```

### Step 6: 确保计划质量

**质量检查清单**：
- [ ] 每个任务包含确切的文件路径
- [ ] 每个任务包含完整代码（不是"添加验证"这种模糊描述）
- [ ] 每个任务包含确切的命令和预期输出
- [ ] 引用相关技能（harness-executing-plans）
- [ ] 遵循DRY、YAGNI、TDD原则
- [ ] 每个任务频繁提交

### Step 7: 应用自动执行策略

默认使用“自动策略模式”，不在此阶段等待用户选择。

**默认策略**：
- `execution_mode: parallel_session`
- `execution_mode_reason: 推荐模式，最适合长任务自动交接`
- `resume_policy: auto_continue`
- `retry_policy: retry_3_then_recover`
- `checkpoint_policy: task_level`

**策略说明**：
- 默认优先选择 `Parallel Session`，因为它最适合和 tmux 自动交接结合。
- 默认由新会话使用 `harness-executing-plans`，减少当前会话上下文膨胀。
- 如果用户在需求确认阶段已经显式指定其他模式，再覆盖默认策略。
- 需求确认之后不得再次向用户询问执行策略。

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

追加或更新以下字段：

```markdown
execution_mode: parallel_session
resume_policy: auto_continue
retry_policy: retry_3_then_recover
checkpoint_policy: task_level
```

使用 Bash 工具输出：

```bash
echo ""
echo "✅ 计划完成并保存到: docs/plans/{feature}-implementation-plan.md"
echo ""
echo "🤖 自动执行策略已应用:"
echo " - 执行模式: Parallel Session（推荐，已自动选择）"
echo " - 恢复策略: auto_continue"
echo " - 重试策略: retry_3_then_recover"
echo " - 检查点策略: task_level"
echo ""
echo "🎯 下一步: 自动触发 harness-executing-plans"
```

### Step 8: 提交计划文档

使用 Bash 工具执行：

```bash
git add docs/plans/{YYYY-MM-DD}-{feature}-implementation-plan.md
git commit -m "docs: add {feature} implementation plan

- Add detailed implementation plan for {feature name}
- Break down into bite-sized tasks (2-5 min each)
- Include exact file paths and complete code
- Follow TDD approach (test first, implementation second)
- Reference design document: {design-doc-name}
- Generated by harness-plan"
```

### Step 9: 更新事件日志

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

事件内容：
```markdown
{TIMESTAMP} | SKILL_COMPLETE | harness-plan | 实施计划完成 - {feature} | SUCCESS
{TIMESTAMP} | TRIGGER_DOWNSTREAM | executing-plans | 触发计划执行 | PENDING
```

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

使用 Bash 工具输出：

```bash
echo ""
echo "✅ harness-plan 完成!"
echo ""
echo "📋 实施计划:"
echo " - 文件: docs/plans/{YYYY-MM-DD}-{feature}-implementation-plan.md"
echo " - 任务数: {N}个任务"
echo " - 状态: 已提交"
echo ""
echo "🎯 下一步:"
echo " - 已自动选择推荐执行方式: Parallel Session"
echo " - 自动触发 harness-executing-plans"
echo ""
```

## 成功标准
- [ ] 实施计划已创建
- [ ] 任务分解为bite-sized（2-5分钟）
- [ ] 每个任务包含确切文件路径
- [ ] 每个任务包含完整代码
- [ ] 每个任务包含测试步骤
- [ ] 实施计划已提交到Git
- [ ] 事件已记录到EVENT_LOG.md
- [ ] 已应用自动执行策略

## 失败兜底
- 设计文档不存在 → 提示运行 harness-brainstorm
- 设计文档不完整 → 返回 harness-brainstorm 补充设计
- 任务分解粒度过大 → 重新分解为更小任务
- 技术实现不可行 → 返回 harness-brainstorm 重新设计

## 联动关系
- 触发时机：harness-brainstorm 完成，进入自动执行阶段
- 上游技能：harness-brainstorm（必须先有设计）
- 下游技能：executing-plans（执行实施计划）
- 并行技能：无（计划编写需要串行）

## 关键原则

### 1. Bite-Sized任务粒度
每个任务一个动作，2-5分钟完成：
- ✅ 正确：编写失败测试 → 运行验证失败 → 编写最小实现 → 运行验证通过 → 提交
- ❌ 错误：实现用户认证功能（太笼统）

### 2. 确切文件路径
总是使用确切的文件路径：
- ✅ 正确：`src/auth/service.go:45-60`
- ❌ 错误：在认证服务中添加方法

### 3. 完整代码
在计划中提供完整代码，不是模糊描述：
- ✅ 正确：
  ```go
  func (s *AuthService) Login(email, password string) (*Token, error) {
      user, err := s.repo.FindByEmail(email)
      if err != nil {
          return nil, ErrUserNotFound
      }
      if !s.verifyPassword(password, user.PasswordHash) {
          return nil, ErrInvalidPassword
      }
      return s.generateToken(user)
  }
  ```
- ❌ 错误：添加登录方法，验证邮箱和密码，返回token

### 4. DRY、YAGNI、TDD
- **DRY（Don't Repeat Yourself）**：避免重复代码
- **YAGNI（You Aren't Gonna Need It）**：不添加不需要的功能
- **TDD（Test-Driven Development）**：测试先行，实现后行

### 5. 频繁提交
每个任务完成后立即提交，避免大提交：
- ✅ 正确：每个bite-sized任务一个提交
- ❌ 错误：一次性提交所有实现

## 任务分解示例

### 示例：用户认证功能

#### 错误的任务分解（太笼统）
```markdown
### Task 1: 实现用户模型
创建User结构体，包含ID、邮箱、密码字段。

### Task 2: 实现认证服务
实现登录、注册、登出方法。

### Task 3: 实现认证控制器
实现HTTP处理器。
```

#### 正确的任务分解（bite-sized）
```markdown
### Task 1: 定义User模型

**Files:**
- Create: `internal/models/user.go`

**Step 1: 编写User结构体**

```go
package models

type User struct {
    ID           string `json:"id" db:"id"`
    Email        string `json:"email" db:"email"`
    PasswordHash string `json:"-" db:"password_hash"`
    CreatedAt    time.Time `json:"created_at" db:"created_at"`
    UpdatedAt    time.Time `json:"updated_at" db:"updated_at"`
}
```

**Step 2: 提交User模型**

```bash
git add internal/models/user.go
git commit -m "feat: add User model definition"
```

---

### Task 2: 编写UserRepository接口

**Files:**
- Create: `internal/auth/repository.go`

**Step 1: 编写Repository接口**

```go
package auth

type UserRepository interface {
    FindByEmail(email string) (*models.User, error)
    Create(user *models.User) error
    Update(user *models.User) error
}
```

**Step 2: 提交Repository接口**

```bash
git add internal/auth/repository.go
git commit -m "feat: add UserRepository interface"
```

---

### Task 3: 编写AuthService登录方法测试

**Files:**
- Create: `internal/auth/service_test.go`

**Step 1: 编写失败测试**

```go
package auth

import (
    "testing"
    "github.com/stretchr/testify/assert"
)

func TestAuthService_Login_Success(t *testing.T) {
    // 准备
    mockRepo := &MockUserRepository{
        Users: map[string]*models.User{
            "test@example.com": {
                ID:           "user-123",
                Email:        "test@example.com",
                PasswordHash: "$2a$10$...", // bcrypt hash
            },
        },
    }
    service := NewAuthService(mockRepo)

    // 执行
    token, err := service.Login("test@example.com", "password")

    // 断言
    assert.NoError(t, err)
    assert.NotNil(t, token)
}
```

**Step 2: 运行测试验证失败**

```bash
go test ./internal/auth -v
# 预期：FAIL，AuthService未实现
```

---

### Task 4: 实现AuthService登录方法

**Files:**
- Create: `internal/auth/service.go`

**Step 1: 实现Login方法**

```go
package auth

type AuthService struct {
    repo UserRepository
}

func NewAuthService(repo UserRepository) *AuthService {
    return &AuthService{repo: repo}
}

func (s *AuthService) Login(email, password string) (*Token, error) {
    user, err := s.repo.FindByEmail(email)
    if err != nil {
        return nil, ErrUserNotFound
    }

    if !verifyPassword(password, user.PasswordHash) {
        return nil, ErrInvalidPassword
    }

    return generateToken(user)
}
```

**Step 2: 运行测试验证通过**

```bash
go test ./internal/auth -v
# 预期：PASS
```

**Step 3: 提交AuthService**

```bash
git add internal/auth/service.go internal/auth/service_test.go
git commit -m "feat: implement AuthService.Login method with tests"
```
```

## 计划模板

```markdown
# {功能名称} 实施计划

> **For Claude:** REQUIRED SUB-SKILL: Use harness-executing-plans to implement this plan task-by-task.

**Goal:** {一句话描述构建什么}

**Architecture:** {2-3句话描述方法}

**Tech Stack:** {关键技术/库}

---

## 实施阶段概览

```
阶段1: {阶段名称}（{N}个任务）
- Task 1.1: {任务名称}
- Task 1.2: {任务名称}

阶段2: {阶段名称}（{N}个任务）
- Task 2.1: {任务名称}
- Task 2.2: {任务名称}

总计: {M}个任务，预计{X-Y}小时
```

---

## 阶段1: {阶段名称}

### Task 1.1: {任务名称}

**Files:**
- Create: `{确切路径}`
- Test: `{确切路径}`

**Step 1: {步骤名称}**

{详细说明}

**Step 2: {步骤名称}**

{详细说明}

（继续所有步骤...）

---

（继续所有任务...）
```

## 迭代计数

本技能执行预计迭代次数：约 20-30 次
- Read 设计文档：1次
- 分析设计：1次
- Write 实施计划：1次
- Edit EVENT_LOG：2次
- Git提交：2次
- 其他Bash命令：10-20次

## 参考

- EnjoyHarness设计文档 - `docs/plans/2026-03-28-enjoyharness-design-v3.md`