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 工具查找设计文档：

# 查找最新的设计文档
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

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

# [功能名称] 实施计划

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

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

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

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

---

## 实施阶段概览

[阶段划分和任务列表]

---

任务结构模板：

### 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: 编写最小实现

def function(input):
    return expected

Step 4: 运行测试验证通过

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

Step 5: 提交代码

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 工具输出：

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 工具执行：

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

事件内容：

{TIMESTAMP} | SKILL_COMPLETE | harness-plan | 实施计划完成 - {feature} | SUCCESS
{TIMESTAMP} | TRIGGER_DOWNSTREAM | executing-plans | 触发计划执行 | PENDING

Step 10: 输出完成信息

使用 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. 完整代码

在计划中提供完整代码，不是模糊描述：

• ✅ 正确：

  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任务一个提交
• ❌ 错误：一次性提交所有实现

任务分解示例

示例：用户认证功能

错误的任务分解（太笼统）

### Task 1: 实现用户模型
创建User结构体，包含ID、邮箱、密码字段。

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

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

正确的任务分解（bite-sized）

### 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模型

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接口

package auth

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

Step 2: 提交Repository接口

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: 编写失败测试

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: 运行测试验证失败

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

Task 4: 实现AuthService登录方法

Files:

• Create: internal/auth/service.go

Step 1: 实现Login方法

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: 运行测试验证通过

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

Step 3: 提交AuthService

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