Markdownファイルの形式

タスクの内容はTASK.md、エピックの詳細はEPIC.mdに保存します。エージェントも人も直接編集でき、ボードは変更に追従します。このページでは、各ファイルの構造と編集時のルールを説明します。ファイルの探し方は、ファイルを直接編集するを参照してください。

ファイル	保存する内容	直接編集
TASK.md	タスクの本文・受入条件・履歴。	はい。ただし下書きのタスクは除く。
EPIC.md	エピックの詳細と、タスクの順序。	はい。
task.json・epic.json・project.json	状態とメタデータ。	いいえ。CLIを使う。

TASK.md

TASK.mdは、2本の---の間にYAMLのfrontmatterがあり、そのあとに自由なMarkdownの本文が続きます。

---
acceptance:
  - id: AC-1
    text: The setup guide covers the supported installation steps.
    done: false
  - id: AC-2
    text: Deleting a task asks for confirmation.
    done: true
history: []
---

## Background

Any headings and text you need.

• 本文: 本文には、タスクの計画、各受入条件の確認結果、成果物への参照を書きます。決まった見出しはありません。時系列のログは本文に書かず、履歴をfrontmatterに記録します。画面の見た目を確認できる画像は添付できます。
• 新しいタスク: タスクを作るときは、historyを省略するか空にでき、最初の履歴の項目はAgent Boardが加えます。保存済みのTASK.mdには、acceptanceが空でも、有効なトップレベルのhistoryリストが必要です。

受入条件

acceptanceはリストです。各項目は、3つのキーだけを持ちます。

キー	規則
id	AC-に、先頭に0を付けない正の数が続く形。ファイル内で一意。
text	前後の空白を除いて1〜2,000文字。確認できるように書く。
done	trueかfalse。

条件を足すときは、次の空き番号を使い、振り直しません。frontmatterのほかのキーは、ボードがファイルを書くときも保持されます。

履歴

historyは、起きたことを古い順に並べます。各項目は、ちょうど二つのキーを持ちます。

history:
  - at: "2026-10-15T01:30:00Z"
    reason: "Verified the setup guide links and recorded the result in the task body."

• atは、厳密にYYYY-MM-DDTHH:MM:SSZの形のUTC文字列で、秒は整数、Zは大文字です。時差表記（+00:00を含む）と小数秒は拒否します。
• reasonは内容で、10,000文字までです。
• 保存済みのファイルでは、リストが空でもかまいません。APIとCLIも、同じat/reasonの形で履歴を返します。

タスクの移動、状態変更、質問と回答、アーカイブと復元、自動完了は、Agent Boardが履歴に記録します。ブラウザの理由欄は任意で、空や空白の理由は、現在の状態から生成します。履歴タブ・show・snapshotは、同じ履歴を読みます。

エージェントは、意味のある進捗をhistory addで、そのたびに承認を求めずに加えます。列の移動や状態変更は自動で記録されるため、同じ操作を重複して追記しません。コマンドが時刻を付け、原子的に追記し、AIの書き込み権限を適用します。AIは、下書き・アーカイブ済み・完了のタスクに追記できません。直接編集では、atとreasonだけの項目を追記でき、既存の履歴・本文・条件・ほかのメタデータを保たなければなりません。履歴を追記するためだけにファイル全体を書き直さないでください。本文や条件の通常の編集は最新の履歴を保ち、edit --desc-fileは入力の履歴を無視します。

条件を達成にして終える

条件は、検証が済んでからdone: trueにします。簡潔な結果を本文に残し、最後の未達成条件を達成済みにして保存する前に、検証を履歴に記録します。

agboard serveが動いている間、次のタスクは自動で完了に移ります。

• AI担当で、下書きでなく、アーカイブされておらず、未着手か進行中にある。
• 有効な条件が一つ以上あり、すべての条件がdone: trueである。

サーバーは、起動時にも既存のタスクを確認します。待機中のタスクは、回答されるまで待ちます。ユーザー担当のタスク、下書き、条件が不正なタスク、条件のないタスクは、自動では完了しません。完了したタスクはエージェントから読み取り専用で、自動で再開することはありません。条件のチェックを外さずに再開すると、もう一度完了することがあります。

EPIC.md

EPIC.mdは、エピックの詳細を自由なMarkdownで書いたものです。以前のバージョンではこのファイルをPLAN.mdと呼んでおり、プロジェクトを初めて読み込むとEPIC.mdへ名前が変わります（データとバックアップを参照）。エピックの参考となる完了条件は、本文に通常のMarkdownとして直接書きます。受入条件のデータとしては解析されず、エピックに履歴はありません。

frontmatterには、重複しない正のタスクIDのpriorityリストを置けます。エピックの進行表とCLIの進行表の順序を、ボードの列とは独立に決めます。

priority: [3, 1, 2]

frontmatterのないEPIC.mdは、全体が本文です。順序は、epic edit --priority、進行表のパネル、ファイルの編集のどれでも保存できます。EPIC.mdの古いacceptanceキーは、未解釈のメタデータとして保持し、変換しません。

ファイルに不備があるとき

frontmatterを読めないとき（不正なYAML、キーの欠落、IDの重複、空のtext）、ボードはファイル・項目・理由を問題として報告します。タスクは進捗を表示せず、全文を本文として表示します。ボードがファイルを書き換えて直すことはありません。手で直せば、次の読み込みで通常どおり表示されます。

すべてのJSONファイルはformatVersion: 1を宣言します。ほかの版のファイルは未対応で、ボードは報告してファイルを変更せず、移行・フォールバック・削除・初期化も行いません。

次に読む

• トラブルシューティング: ボードにタスクがない、ファイルの警告が出る。
• CLIリファレンス: ファイルの更新に使えるコマンド。