エージェントとの連携

エージェントは、あなたと同じボードで作業します。Hookから進行表を受け取り、タスクを選んで進捗を報告します。ユーザーの判断が必要になったら質問し、回答を待ちます。このページでは、連携の設定方法と作業の流れを説明します。クイックスタートでは、同じ流れをコマンドで体験できます。

エージェントをつなぐ

連携には、次の三つをそれぞれ手動で設定します。

1. 共有フォルダを準備する。 エージェントがそこへ書けるよう、agboard setupを一度実行します。CodexとClaude Codeのユーザー設定にデータフォルダを加えるだけで、Hookもスキルもインストールしません。共有フォルダをセットアップするを参照してください。
2. Hookを登録する。 エージェントに進行表を渡すHookです。
3. エージェントのスキルを入れる。 ボードを使った作業手順を定めるagent-boardスキルです。

Hookの設定テンプレートはリポジトリのintegrations/フォルダにあります。設定の詳細は、Claude CodeとCodexの連携ガイドに従ってください。

• Claude Code。 integrations/claude-code/settings.jsonをプロジェクトの.claude/settings.jsonに統合し、/hooksで確認します。
• Codex CLIとCodex App。 integrations/codex/hooks.jsonをプロジェクトの.codex/hooks.jsonに統合し、/hooksで確認します。

Hookがどのプロジェクトのものか分かるよう、プロジェクトのフォルダをagboard project createかagboard project bindで登録します。

HookとエージェントのスキルはPATHのagboardを実行するので、開発中のビルドではなく、インストールした版を使います。インストールと起動を参照してください。

Hookが行うこと

• フォルダの解決。 Hookのコマンドは固定のagboard hook --agent claudeで、プロジェクト名もセッションIDもありません。入力のcwdを読み、最も近い登録済みの祖先フォルダを使います。明示した--project NAMEは紐付けより優先されます。紐付けがない、または壊れているときはAGBOARD_ERRORを返し、Hookが別のプロジェクトを推測することはありません。
• 進行表。 Hookは、agboard progressと同じ簡潔な表を渡します。完了・アーカイブ済み・待機中のタスクは、Hookのコマンドに--include-pendingや--include-done COUNTを付けない限り含みません（エピックと進行表を参照）。表が256 KiBを超える、または読めないときは、エージェントにAGBOARD_ERRORが渡され、ボードに依存する変更をしてはいけません。

エージェントが編集してよいもの

• エージェントが編集してよいのは、プロジェクトのREADME.mdが許す範囲で、下書きでないタスクのTASK.mdと、エピックのEPIC.mdだけです。
• task.jsonはメタデータを持ち、CLIで変更します。TASK.mdは本文・受入条件・履歴を持ちます。
• タスクの操作は履歴を自動で追加します。エージェントは意味のある進捗をhistory addで記録し、計画と簡潔な検証結果は本文に置きます。
• エージェントは、epic.jsonやproject.jsonを編集せず、タスクやエピックのフォルダを削除せず、共有ファイルにマシン固有の絶対パスを書きません。

形式はMarkdownファイルの形式にあります。

AIは履歴をタスク本文と同じ言語で記録します。ブラウザー操作で自動生成する履歴は、選択した画面言語を使います。CLI操作と自動完了では、本文に日本語の文字があれば日本語、それ以外は英語にし、本文が空か標準テンプレートならタイトルを使います。保存済みの履歴や入力した理由は変わりません。

作業の流れ

1. 選ぶ。 agboard progress --jsonを読み、エピックに保存されたタスクの順序に従って、進められるAI担当のタスクを選びます。選んだエピックのEPIC.mdとタスクのTASK.mdだけを読み、履歴や未回答の質問が必要なときはshowを使います。
2. 始める。 タスクを理由つきで進行中に移し、稼働中を報告します。ユーザー担当のタスクは、作業に関わるときだけ確認します。
3. 作業して記録する。 実際の作業と検証に基づく簡潔な理由で、意味のある進捗をhistory addで記録します。計画と簡潔な結果は本文に置き、見た目の確認が有用な場合は画像を添付します。移動や状態の変更はすでに履歴を追加するので、重複させません。
4. 詰まったら尋ねる。 判断が必要なときは、待機中で質問します（判断依頼を参照）。
5. 再開する。 回答のあと、タスクと履歴を読み、計画を考え直して、理由つきで再開します。
6. 終える。 受入条件は、検証が済んでから達成にします。条件がすべて達成になると、対象のAI担当タスクは自動で完了に移ります。
7. 待つ。 進められる作業がないときは、変更を待ちます（下を参照）。

進行表はエピックと進行表を参照してください。

AIは編集できるAI担当タスクを読んだあと、タイトルが分かりにくければ、着手前に対象と変更内容が伝わる短いタイトルへ整理します。元の依頼文と添付画像は保持し、すでに分かりやすいタイトルは変えません。組手を含むAIセッション内の動作で、フォームでの登録時には依頼の最初の空でない行をタイトルにします。完了済みのタスクをAIが改名することはありません。

エージェントは、確認・希望・承認など作業に関する質問をボード上でのみ行います。選択肢を付け、既定で回答を待ちます。質問を登録してすぐに戻るよう明示された場合にだけ--no-waitを使います。チャットでは、ボードに質問があることだけを案内します。ボードに接続できないときは問題を報告し、質問できるようになるまで待ちます。

変更を待つ

agboard --project "My project" snapshot --json
agboard --project "My project" wait --after "<cursor>" --json

cursorの形式はf1:<project-id>:<version>です。snapshotが返す値を使い、自分で組み立てないでください。

• waitは、同じデータ領域で動いているagboard serveを必要とし、ポーリングせずに変更を待ちます。
• 名前変更をまたいで同じプロジェクトを追うので、以後のコマンドとHookでは新しい名前を使います。ほかのプロジェクトの変更では終わりません。プロジェクトが削除されると、project_not_foundで失敗します。
• wait_timeout・board_unavailable・cursor_invalid・project_not_foundはエラーで、回答ではありません。
• waitが返ったら、スナップショットと履歴をすべて読み、ユーザーの理由を考慮して、再開するか、追加の質問をします。

次のタスクを待つ

起動済みのCodexまたはClaude Codeのセッションを一つ使い、同じプロジェクトのAI担当タスクを順番に進められます。同じデータ領域でagboard serveを起動してから、明示的にリッスンを始め、対象がない状態が何秒続いたらコマンドを終えるか指定します。

agboard --project "My project" wait --until task --idle-timeout 300 --json

待機秒数は必須で、1〜86,400秒を指定します。既定値はありません。Todoにある起票済みタスクに加え、agentStatusがidleのままDoingにあるAIタスクも対象です。リッスンの開始・再開時にAIタスクのagentStatusを確認し、runningまたはpendingがあれば、その作業を先に解決します。レーンがDoingであることだけではリッスンを止めません。一回の呼び出しで取得するのは一件です。そのタスクの作業を終えるか中断したあと、同じセッションでwaitをもう一度呼び出して次へ進みます。対象の順序は進行表と同じで、エピックID順に、各エピックの保存済み優先順とタスクID、最後に未所属タスクのID順です。AI担当・TodoまたはDoing・Idle・下書きでない・アーカイブされていないタスクだけが対象です。タスクの取得は内容変更や占有を行いません。作業が承認され、開始できることを判断する前に、エピックのEPIC.md（ある場合）・本文・添付・最新状態を確認してください。従来どおり手動でタスクを作成でき、作成したタスクも後から取得されます。

Pendingへの判断依頼を含む全体の手順と、中断後の復帰方法はagent-boardスキルのリッスン手順を参照してください。Pendingのタスクは回答が届くまで同じセッションで待ち、別のタスクへ飛びません。Pending中の時間は対象なし時間に含まれません。回答後は内容を読み、そのタスクを再開してから次のタスクを待ちます。

idle_timeoutは終了コード0の正常終了です。指定した時間に対象タスクがなかったことだけを示します。サーバー切断、不正なボードデータ、プロジェクト削除、引数の誤りはエラーであり、対象なしとして報告してはいけません。出力とエラーコードはCLIリファレンスを参照してください。

下書きとエラー

下書き（isDraft: true）はエージェントから読み取り専用です。edit・mv・stateはtask_is_draftで失敗します。ユーザーが確定するまで、ほかのタスクを進めます。

AGBOARD_ERRORが出た場合や、プロジェクトが見つからない・接続できない・ボードを読み込めない場合は、その問題を報告します。有効な進行表を取得できるまで、ボードの情報に依存する変更は行いません。待機が時間切れになったり中断されたりしても、質問は未回答のまま残ります。原因と対処はトラブルシューティングを参照してください。

次に読む

• CLIリファレンス: エージェントが使うすべてのコマンド。
• 判断依頼: エージェントの尋ね方と、あなたの答え方。