task-harness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

Task Harness — Structured Task Management System

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

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

Decompose any requirements into structured task lists and establish a reliable task tracking system for long-running Agents.

Based on the Effective harnesses for long-running agents methodology.

何时使用

When to Use

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

Large requirements need to be broken down into multiple subtasks
Projects require continuous development across multiple Agent sessions
Need to track feature completion progress (Completed / Incomplete)
Users say "task decomposition", "task management", "project planning", "create task list"

核心流程

Core Process

Step 1: 分析代码库

Step 1: Analyze Codebase

探索项目结构，理解：

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

Explore the project structure to understand:

Tech stack (languages, frameworks, build tools)
Directory structure and architectural patterns
Existing configurations (package.json, go.mod, etc.)
Key entry files

Step 2: 设计任务列表

Step 2: Design Task List

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

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

Based on user requirements, break down work into specific features. Each feature requires:

A unique
```
id
```
(e.g.,
```
feat-01
```
,
```
v2-05
```
)
```
category
```
classification (foundation, layout, components, etc.)
```
priority
```
(smaller numbers mean higher priority)
```
description
```
a one-sentence description
```
file
```
main involved file path (can be null)
```
steps
```
array of specific operation steps (one string per step)
```
passes
```
boolean value (initially false)
```
verification
```
verification conditions

Step 3: 生成 4 个 Harness 文件

Step 3: Generate 4 Harness Files

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

Generate the following files in the project root directory:

feature_list.json

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

feature_list.json

— Task List (Single Source of Truth)

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 文件被模型更谨慎对待——更可能只修改特定字段。这对维护任务完整性至关重要。

json

{
  "project": "Project Name",
  "description": "Project Description",
  "features": [
    {
      "id": "feat-01",
      "category": "foundation",
      "priority": 1,
      "description": "One-sentence description of what to do",
      "file": "path/to/main/file.js",
      "steps": [
        "Specific Step 1",
        "Specific Step 2"
      ],
      "passes": false,
      "verification": "How to verify this feature is completed"
    }
  ]
}

Complete template can be found at references/templates/feature_list.json

Why JSON instead of Markdown? Models tend to freely rewrite Markdown files (rephrasing, restructuring, deleting content). JSON files are treated more carefully by models — they're more likely to only modify specific fields. This is critical for maintaining task integrity.

progress.txt

— 叙事性进度日志

progress.txt

— Narrative Progress Log

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

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

Record detailed work content of each session for subsequent sessions to understand context.

Complete template can be found at references/templates/progress.txt

init.sh

— 环境初始化脚本

init.sh

— Environment Initialization Script

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

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

Run at the start of each new session to restore full context within 5 seconds.

Complete template can be found at references/templates/init.sh

task.json

— 项目总览

task.json

— Project Overview

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

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

Record project-level information such as milestones, rules, file lists, etc.

Complete template can be found at references/templates/task.json

Step 4: 配置 AGENTS.md 规则

Step 4: Configure AGENTS.md Rules

在项目的

AGENTS.md

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

AGENTS.md

中的对应章节。

Add a Task Management System section to the project's

AGENTS.md

file to ensure all Agent sessions follow the workflow. Refer to the corresponding section in the current project's

AGENTS.md

Step 5: 首次验证

Step 5: Initial Verification

运行

bash init.sh

，确认：

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

Run

bash init.sh

and confirm:

The script can execute normally
feature_list.json is parsed correctly
Progress statistics are displayed accurately

Step 6: 输出下一步指引

Step 6: Output Next Steps Guidance

告诉用户：

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

Tell the user:

List of created files
How to start the first task
How to resume work in a new session

Agent 工作流（每个会话）

Agent Workflow (Per Session)

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            ← 记录本次会话的工作

1. bash init.sh                    ← 5-second context restoration
2. Read progress.txt               ← Understand what was done before and why
3. Read feature_list.json          ← Find the highest priority incomplete feature
4. Pick 1~2 features               ← Don't bite off more than you can chew; incremental progress is key
5. Execute the feature's steps     ← Follow steps strictly
6. Verify                          ← Must actually verify, don't assume
7. Update feature_list.json        ← Only change passes: false → true
8. git commit                      ← One commit per feature
9. git push                        ← Sync to remote
10. Append progress.txt            ← Record work done in this session

严格规则

Strict Rules

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

Only modify the
passes
field: In feature_list.json, only change
```
passes
```
from
```
false
```
to
```
true
```
. Never delete features, edit descriptions, modify priorities, or restructure the JSON.
One feature at a time: Unless the feature is very small (e.g., changing a constant), only work on one feature per session.
Must commit + push: After completing each feature, must git commit and push to ensure progress is never lost and can be rolled back independently.
Must verify before marking as completed: Read code, run dev server, or check output. Don't trust assumptions.
Must update progress.txt: Update the progress log at the end of the session so the next session has complete context.
Stop when blocked: Record the reason for blocking in progress.txt and stop. Don't silently bypass issues.

文件间关系

Relationships Between Files

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

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

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

init.sh ──reads──→ feature_list.json (Task Status)
    │
    └──prompts──→ progress.txt (Historical Context)

task.json ────→ Project Overview (Milestones, Rules, File Lists)

AGENTS.md ────→ Agent Behavior Specifications (References harness rules)

引用

References

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

Methodology Details — Why use harnesses, common issues, best practices
Template Files — Blank templates for all harness files