Task Harness

Task Harness — 结构化任务管理系统

将任意需求拆解为结构化任务清单，为长时运行的 Agent 建立可靠的任务追踪系统。

基于 Effective harnesses for long-running agents 方法论。

何时使用

• 大型需求需要拆解为多个子任务
• 项目需要跨多个 Agent 会话持续开发
• 需要跟踪功能完成进度（已完成 / 未完成）
• 用户说"拆解任务"、"任务管理"、"项目规划"、"创建任务清单"

核心流程

Step 1: 分析代码库

探索项目结构，理解：

• 技术栈（语言、框架、构建工具）
• 目录结构和架构模式
• 现有配置（package.json、go.mod 等）
• 关键入口文件

Step 2: 设计任务列表

根据用户需求，将工作拆解为具体的功能点（features）。每个功能点需要：

• 唯一的 id（如 feat-01、v2-05）
• category 分类（foundation、layout、components 等）
• priority 优先级（数字越小越优先）
• description 一句话描述
• file 主要涉及的文件路径（可为 null）
• steps 具体操作步骤数组（每步一个字符串）
• passes 布尔值（初始为 false）
• verification 验证条件

Step 3: 生成 4 个 Harness 文件

在项目根目录生成以下文件：

feature_list.json — 任务清单（唯一真相来源）

{
  "project": "项目名称",
  "description": "项目描述",
  "features": [
    {
      "id": "feat-01",
      "category": "foundation",
      "priority": 1,
      "description": "一句话描述要做什么",
      "file": "path/to/main/file.js",
      "steps": [
        "具体步骤 1",
        "具体步骤 2"
      ],
      "passes": false,
      "verification": "如何验证这个功能已完成"
    }
  ]
}

完整模板见 references/templates/feature_list.json

为什么用 JSON 而不是 Markdown？ 模型倾向于自由改写 Markdown 文件（改写措辞、重组结构、删除内容）。JSON 文件被模型更谨慎对待——更可能只修改特定字段。这对维护任务完整性至关重要。

progress.txt — 叙事性进度日志

记录每个会话的详细工作内容，供后续会话理解上下文。

完整模板见 references/templates/progress.txt

init.sh — 环境初始化脚本

每个新会话开始时运行，5 秒内恢复全部上下文。

完整模板见 references/templates/init.sh

task.json — 项目总览

记录里程碑、规则、文件清单等项目级信息。

完整模板见 references/templates/task.json

Step 4: 配置 AGENTS.md 规则

在项目的 AGENTS.md 文件中添加 Task Management System 章节，确保所有 Agent 会话遵循工作流。参考当前项目的 AGENTS.md 中的对应章节。

Step 5: 首次验证

运行 bash init.sh，确认：

• 脚本可正常执行
• feature_list.json 解析正确
• 进度统计准确显示

Step 6: 输出下一步指引

告诉用户：

• 已创建的文件列表
• 如何开始第一个任务
• 如何在新会话中恢复工作

Agent 工作流（每个会话）

1. bash init.sh                    ← 5 秒上下文恢复
2. Read progress.txt               ← 理解之前做了什么、为什么
3. Read feature_list.json          ← 找到优先级最高的未完成功能
4. Pick 1~2 features               ← 不要贪多，增量推进是关键
5. Execute the feature's steps     ← 严格按步骤执行
6. Verify                          ← 必须实际验证，不要假设
7. Update feature_list.json        ← 只改 passes: false → true
8. git commit                      ← 一个功能一个 commit
9. git push                        ← 同步到远程
10. Append progress.txt            ← 记录本次会话的工作

严格规则

• 只修改 `passes` 字段：在 feature_list.json 中，只将 passes 从 false 改为 true。永远不要删除功能、编辑描述、修改优先级或重组 JSON。
• 一次一个功能：除非功能非常小（例如改一个常量），否则每个会话只做一个功能。
• 必须 commit + push：每个功能完成后必须 git commit 和 push，确保进度永不丢失且可独立回滚。
• 必须验证后再标记完成：阅读代码、运行 dev server 或检查输出。不要信任假设。
• 必须更新 progress.txt：会话结束时更新进度日志，让下一个会话有完整上下文。
• 遇到阻塞时停止：在 progress.txt 中记录阻塞原因并停止。不要默默绕过问题。

文件间关系

init.sh ──读取──→ feature_list.json (任务状态)
    │
    └──提示──→ progress.txt (历史上下文)

task.json ────→ 项目总览（里程碑、规则、文件清单）

AGENTS.md ────→ Agent 行为规范（引用 harness 规则）

引用

• 方法论详解 — 为什么用 harness、常见问题、最佳实践
• 模板文件 — 所有 harness 文件的空白模板

Task Harness 方法论

为什么需要 Harness？

Agent 的核心限制是无状态——每次会话都从零开始，没有之前会话的记忆。没有结构的 Agent 会以可预测的方式失败：

Harness 就是解决这些问题的外部记忆系统。

为什么用 JSON 做任务清单？

这是方法论中最关键的洞察：

模型倾向于自由改写 Markdown 文件——改写措辞、重组结构、删减内容。这种"过度编辑"倾向会导致任务清单逐渐失真：步骤被简化、验证条件被弱化、优先级被悄悄调整。

JSON 文件被模型更谨慎对待。模型更可能只修改特定字段（如 passes），而保留其余结构不变。这种差异对维护任务完整性至关重要。

核心设计原则

1. 单一真相来源（Single Source of Truth）

feature_list.json 是唯一的项目状态文件。所有判断都基于它：

• 什么还没做？→ passes: false 的功能
• 做了什么？→ passes: true 的功能
• 总进度？→ passed / total

不要在其他文件中维护重复的任务列表。

2. 叙事性日志（Narrative Log）

progress.txt 用自然语言记录"做了什么"和"为什么"。JSON 精确但不解释原因。当 Agent 需要理解某个设计决策的背景时，叙事日志比 JSON 中的步骤列表更有用。

3. 快速上下文恢复（Fast Context Restore）

init.sh 在 5 秒内提供全部关键信息：git 状态、完成进度、剩余任务。Agent 不需要花 30 秒读文件就能知道该做什么。

4. 增量推进（Incremental Progress）

每个会话只做 1-2 个功能。这看起来慢，但实际更快：

• 更少的回滚风险
• 更可靠的验证
• 更清晰的 git 历史
• 更容易恢复中断的工作

常见问题

Q: 任务拆得太细，会不会效率低？

不会。 Agent 在大任务上的失败率远高于小任务。一个 10 步任务被中断后，很难判断哪一步完成了、哪一步是半成品。拆成 10 个独立功能后，每个都能被独立验证和提交。

Q: 为什么要强制 commit + push？

防止进度丢失。 Agent 会话可能因超时、错误、网络中断等原因终止。如果工作只在本地，就会丢失。Push 到远程后，即使本地出问题也能从远程恢复。

另外，每个功能一个 commit 使得：

• 可以用 git revert 独立回滚某个功能
• 可以用 git log 追踪每个功能的变化
• 多人协作时可以清楚看到每个功能的改动

Q: feature_list.json 太大了怎么办？

如果功能超过 50 个，考虑分阶段创建：

• 先创建当前阶段的 20-30 个功能
• 当前阶段完成后，再创建下一阶段的功能

这样保持文件大小可控，Agent 读取更快。

Q: Agent 不遵守规则怎么办？

在 AGENTS.md 中以明确的规则形式写好约束。AGENTS.md 会在每次会话开始时被加载到 Agent 的上下文中，比普通文件更有约束力。

关键规则要放在 AGENTS.md 的 Rules 部分，而不是 ## Notes 或 ## Tips 中。

Q: steps 数组中的步骤应该多详细？

越具体越好。 好的步骤应该能让 Agent 无需猜测就执行：

// 差：太模糊
"修改样式"

// 好：足够具体
"在 web/src/index.css 的 :root 块中添加 --semi-color-primary: #DC2626"

具体的步骤还能防止 Agent "过度发挥"——在不该改的地方做改动。

最佳实践

1. 功能 ID 命名

使用有意义的 ID，一眼就能看出属于哪个版本/阶段：

v1-01, v1-02, ...    # 第一版功能
v2-01, v2-02, ...    # 第二版功能
fix-01, fix-02       # 修复类
infra-01             # 基础设施类

2. 分类（category）

按代码层级分类，帮助 Agent 理解功能间的关系：

foundation    # 基础设施（字体、颜色、配置）
layout        # 布局结构（页面框架、导航）
components    # 组件（按钮、卡片、表单）
pages         # 具体页面
api           # 后端接口
database      # 数据库相关
verification  # 验证和测试

3. 验证条件（verification）

每个功能必须有可执行的验证条件：

// 差：主观描述
"看起来更好"

// 好：可执行的检查
"bun run build 成功无错误"
"登录页桌面端显示左右分屏，移动端只有表单区"
"表头 font-weight: 600，font-size: 12px"

4. progress.txt 格式

使用统一的日志格式，让后续会话容易解析：

----------------------------------------
会话 #N - 功能ID: 功能描述
----------------------------------------
时间: YYYY-MM-DD

完成工作:
  [x] 具体做了什么
    - 文件: path/to/file (line XX)
    - 改动: 具体变更

提交:
  - commit: abc1234 feat(scope): 描述
  - push: origin main

进度:
  - 已完成: N/M
  - 下一个: feature-id (描述)

5. 处理阻塞

当 Agent 遇到无法解决的问题时：

⚠️ 阻塞: 描述遇到的问题
原因: 为什么无法继续
尝试: 已经尝试过的解决方案
建议: 可能的解决方向

不要让 Agent 绕过阻塞继续做其他功能——这可能导致后续功能也失败。

参考

• Effective harnesses for long-running agents — Anthropic 官方方法论文章
• task-harness SKILL.md — 技能主入口
• templates/ — Harness 文件模板