dex によるエージェント調整

コマンド実行

すべてのコマンドで dex を直接使用してください。PATH にない場合は、代わりに npx @zeeg/dex を使用してください。

command -v dex &>/dev/null && echo "use: dex" || echo "use: npx @zeeg/dex"

コア原則: Todo ではなく Ticket

Dex タスクはチケット - 包括的なコンテキストを備えた構造化された成果物です:

• Name: 1 行のサマリー (Issue のタイトル)
• Description: 完全な背景、要件、アプローチ (Issue の本文)
• Result: 実装の詳細、決定、結果 (PR の説明)

考え方: 「このタスクだけで、何を、なぜ、どのようにするのかが理解できるか?」

Dex タスクは一時的

外部の成果物 (コミット、PR、ドキュメント) で dex タスク ID を参照しないでください。abc123 のようなタスク ID はタスク完了後は意味をなくします。タスク自体について記述し、それを追跡したタスクについてではなく。

dex をいつ使うか

dex を使う場合:

• 複雑さをサブタスクに分解する
• 複数のセッションにまたがる作業
• ハンドオフのためにコンテキストが永続化される必要がある
• 将来の参照のための決定を記録する

dex をスキップする場合:

• 作業が単一のアトミックなアクション
• すべてが 1 つのセッションで適合し、フォローアップがない
• オーバーヘッドが価値を超える

dex とビルトイン タスク ツール

一部の AI エージェント (Claude Code など) にはビルトイン タスク ツールがあります。これらはセッション限定であり、dex と同じではありません。

	dex	ビルトイン タスク ツール
永続性	.dex/ 内のファイル	セッション限定
コンテキスト	リッチ (説明 + コンテキスト + 結果)	基本的
階層化	3 レベル (Epic → Task → Subtask)	フラット

永続的な作業には dex を使用してください。セッション内の一時的な追跡のみにはビルトイン タスク ツールを使用してください。

基本的なワークフロー

タスクを作成

dex create "Short name" --description "Full implementation context"

説明には、何をする必要があるか、なぜ必要か、実装アプローチ、受け入れ基準を含める必要があります。良い例と悪い例については、examples.md を参照してください。

タスクを一覧表示して表示

dex list                  # 保留中のタスク
dex list --ready          # ブロックされていないタスク
dex show <id>             # 完全な詳細

タスクを完了

dex complete <id> --result "What was accomplished" --commit <sha>

GitHub/Shortcut リンク済みタスクは --commit <sha> または --no-commit のいずれかが必要です:

• コード変更がある場合は --commit <sha> を使用 (マージ時に Issue を閉じる)
• 計画やデザイン等の非コード タスクの場合は --no-commit を使用 (Issue は開いたまま)

完了前に必ず検証してください。 結果には証拠を含める必要があります: テスト数、ビルド ステータス、手動テストの結果。完全なチェックリストについては、verification.md を参照してください。

編集と削除

dex edit <id> --description "Updated description"
dex delete <id>

ブロッカーを含む完全な CLI リファレンスについては、cli-reference.md を参照してください。

タスク フィールドについて

タスクには 2 つのテキスト フィールドがあります:

• Name: 簡潔な 1 行サマリー (dex list に表示)
• Description: 完全な詳細 - 要件、アプローチ、受け入れ基準 (--full で表示)

dex show <id> を実行すると、説明が切り詰められることがあります。CLI は内容がさらにある場合 --full を示唆します。

コンテキストを収集

タスクを取り上げるときは、すべての関連コンテキストを収集してください:

dex show <id> --full              # タスクの完全な詳細
dex show <parent-id> --full       # 親のコンテキスト (該当する場合)
dex show <blocker-id> --full      # ブロッカーが達成したこと

開始する前に、次の質問に答えられることを確認してください:

• 具体的に何を実装する必要があるか (What)
• これが必要な理由は何か (Why)
• どのように実装すべきか (How)
• 完了の定義は何か (受け入れ基準) (When)

いずれかの回答が不明な場合:

1. 親タスクまたは完了したブロッカーでさらに詳細を確認
2. 開始前に要件を詳細化するため計画モードに入ることを提案

完全なコンテキストなしで進める場合:

• タスクが自明/アトミック (例: ".gitignore エントリを追加")
• 会話がすでに不足しているコンテキストを提供している
• 説明自体が十分に詳細

タスク階層

3 つのレベル: Epic (大規模イニシアチブ) → Task (重要な作業) → Subtask (アトミックな手順)。

適切なレベルの選択:

• 小さな機能 (1-2 ファイル) → 単一タスク
• 中規模な機能 (3-7 ステップ) → サブタスク付きタスク
• 大規模なイニシアチブ (5 つ以上のタスク) → Epic とタスク

# 親の下にサブタスクを作成
dex create --parent <id> "Subtask name" --description "..."

詳細な階層化ガイダンスについては、hierarchies.md を参照してください。

結果を記録

実装および検証の直後にタスクを完了してください:

• 決定事項を新鮮なうちに記述
• 計画からの逸脱をメモ
• 実行した検証を文書化
• 技術的負債のためのフォローアップ タスクを作成

結果には明示的な検証証拠を含める必要があります。何をしたかを説明するだけではなく、動作することを証明してください。verification.md を参照してください。

GitHub Issues とのコミット メッセージ

タスクが GitHub Issue にリンクされている場合 (dex show の出力に表示)、コミット メッセージに Issue 参照を含めてください:

• ルート タスク (タスク自体に GitHub メタデータがある): Fixes #N を使用
  • これはマージ時に Issue を閉じます
• サブタスク (親/祖先に GitHub メタデータがある): Refs #N を使用
  • これは Issue をクローズせずにリンク

コミットする前に dex show <id> で GitHub Issue 情報を確認してください。"(via parent)" インジケータは Refs を使用することを意味し、直接メタデータは Fixes を使用することを意味します。

ベスト プラクティス

1. 適切なサイズのタスク: 1 つのフォーカスしたセッションで完了可能
2. 明確な完了基準: 説明は "完了" を定義すべき
3. 過度な分解をしない: 親あたり 3-7 個の子
4. アクション指向の説明: 動詞で始める ("Add", "Fix", "Update")
5. 完了前に検証: テスト成功、手動テスト完了

その他のリソース

• cli-reference.md - 完全な CLI ドキュメント
• examples.md - 良い/悪いコンテキストと結果の例
• verification.md - 検証チェックリストとプロセス
• hierarchies.md - Epic/Task/Subtask の編成