task-harness

Task Harness — 構造化タスク管理システム

あらゆる要件を構造化されたタスクリストに分解し、長時間稼働するエージェントのための信頼性の高いタスク追跡システムを構築します。

長時間稼働するエージェントのための効果的なハーネス の方法論に基づいています。

使用するタイミング

• 大規模な要件を複数のサブタスクに分解する必要がある
• プロジェクトを複数のエージェントセッションにまたがって継続的に開発する必要がある
• 機能の完了状況（完了／未完了）を追跡する必要がある
• ユーザーが「タスクを分解」「タスク管理」「プロジェクト計画」「タスクリストを作成」と言った

コアワークフロー

Step 1: コードベースを分析する

プロジェクトの構造を調査し、以下を把握します。

• 技術スタック（言語、フレームワーク、ビルドツール）
• ディレクトリ構造とアーキテクチャパターン
• 既存の設定（package.json、go.mod など）
• 主要なエントリーファイル

Step 2: タスクリストを設計する

ユーザーの要件に基づいて、作業を具体的な機能（features）に分解します。各機能には、以下が必要です。

• 一意の id（例：feat-01、v2-05）
• category 分類（foundation、layout、components など）
• priority 優先度（数値が小さいほど優先度が高い）
• description 1 文での説明
• file 主に関連するファイルパス（null でも可）
• steps 具体的な操作手順の配列（各手順は 1 つの文字列）
• 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 を参照してください。

Markdown ではなく JSON を使う理由は？ モデルは 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 の章を追加し、すべてのエージェントセッションがワークフローに従うようにします。現在のプロジェクトの AGENTS.md にある該当の章を参考にしてください。

Step 5: 初回検証

bash init.sh を実行し、以下を確認します。

• スクリプトが正常に実行できる
• feature_list.json が正しく解析される
• 進捗の統計が正確に表示される

Step 6: 次の手順を案内する

ユーザーに以下を伝えます。

• 作成したファイルの一覧
• 最初のタスクを開始する方法
• 新しいセッションで作業を再開する方法

エージェントのワークフロー（各セッション）

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 の再構成は絶対に行わないでください。
• 一度に 1 つの機能に取り組む：機能が非常に小さい場合（例：定数を 1 つ変更する）を除き、各セッションで扱う機能は 1 つだけにします。
• 必ず 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 ファイルの空のテンプレート