agentflow

AgentFlow

概要

AgentFlow は、既存のカンバンボードを完全自律型の AI 開発パイプラインに変えます。独自のオーケストレーション基盤を構築する代わりに、プロジェクト管理ツール（Asana、GitHub Projects、Linear）を分散状態機械として扱います。タスクは各ステージを移動し、AI エージェントはコメントを介して状態を読み書きし、人間はすでに使い慣れた同じ UI から介入できます。

その結果、スマートフォンからパイプライン全体を可視化でき、タスクの状態を復元でき（状態はメモリではなくプロジェクト管理ツールに保存されます）、カードをドラッグすればいつでも人間が上書きできます。

このスキルを使うタイミング

• 開発ライフサイクル全体（ビルド、レビュー、テスト、統合）を通じて、複数の Claude Code ワーカーをオーケストレーションする必要がある場合
• AI 生成コードに対する AI レビューの前に、決定論的な品質ゲート（tsc/eslint/tests）を設けたい場合
• カンバンボードまたはスマートフォンから、パイプライン全体を可視化したい場合
• コストを追跡しながら自律的にタスクをディスパッチする必要がある個人またはチームのプロジェクトを実行する場合
• セッション再起動後に復旧できるよう設計されたオーケストレーションが必要な場合

主な概念

7 段階のカンバンパイプライン

タスクは、バックログ、調査、ビルド、レビュー、テスト、統合、完了の順に進みます。各ステージには固有のゲートがあります。カンバンボード自体がオーケストレーション層であり、別のデータベース、メッセージキュー、独自の基盤は必要ありません。

ステートレスオーケストレーター

crontab によって駆動される単発のスイープが、15 分ごとに実行されます。デーモンもセッションへの依存もありません。クラッシュしても、すべての状態がプロジェクト管理ツールに保存されているため、次のスイープで中断したところから再開できます。

確率的な処理の前に決定論的な処理を実施

ハードゲート（tsc + eslint + tests）は、AI レビューの前に実行され、よりコストのかかるレビューに進む前に検出可能なエラーを捕捉します。カバレッジとコストは測定する必要があります。その後、第二層として AI レビューを実施します。

敵対的レビュー

独立したレビューでは、裏付けのある指摘と不完全なカバレッジのみを報告してください。ゲートを通過させるために、任意の数の欠陥を要求したり、問題をでっち上げたりしてはいけません。

推移的優先度によるディスパッチ

後続作業のブロックを最も多く解除するタスクを先にビルドし、クリティカルパスを自動的に計算します。

前提条件と認可

この AAS ツリーに含まれるのはガイドのみです。以下に記載されているスラッシュコマンド、cron スクリプト、ワーカーランタイム、ボード連携、テンプレートは、別途レビューされた上流のインストールに属します。これらがローカルに存在するとは主張しないでください。まず、固定された上流リビジョン、ライセンス、スキーマ、セットアップを確認してください。ボードタスクやコメントの作成、ワーカーの起動、スケジュールの設定、有料モデルの呼び出し、マージ、公開には、それぞれユーザーに適用される認可が必要です。既存のホストファイルを保持し、現在のリポジトリメンテナーのゲートを使用してください。

並行ワーカーを使う場合は、アトミックなタスクの取得またはリース、書き込み所有権の分離、同時実行数の上限、アーティファクト SHA の検証を必須にしてください。ハートビートが古いからといって、ワーカーが停止したとは限りません。再割り当てする前に、有料ジョブや書き込みの重複を防いでください。

スキル／コマンド

/spec-to-board

SPEC.md を依存関係付きのアトミックなタスクに分解し、カンバンボードに作成します。

/sdlc-orchestrate

推移的な優先度と競合検出に基づいて、タスクをワーカーにディスパッチします。crontab のスイープとして実行されます。

/sdlc-worker --slot <N>

タスクを取得し、コードをビルドして PR を作成するワーカーを、ターミナルスロットで実行します。3～4 個のワーカーを並行して実行してください。

/sdlc-health

各タスクの現在のステージ、割り当てられたエージェント、再試行回数、累積コストを表示する、リアルタイムのパイプライン状況ダッシュボードです。

/sdlc-stop

正常にシャットダウンします。アクティブなワーカーは現在のタスクを完了し、未着手のタスクはバックログに戻ります。

ステップごとのガイド

1. 仕様を作成する

構築したいものを記述した SPEC.md をプロジェクト用に作成します。

2. タスクに分解する

claude -p "/spec-to-board"

SPEC.md を読み込み、アトミックなタスクに分解し、依存関係を割り当てて、カンバンボードに作成します。

3. ワーカーを起動する

ターミナルウィンドウを3～4個開き、それぞれをワーカースロットとして使用します。

# Terminal 2 — Builder
claude -p "/sdlc-worker --slot T2"

# Terminal 3 — Builder
claude -p "/sdlc-worker --slot T3"

# Terminal 4 — Reviewer
claude -p "/sdlc-worker --slot T4"

# Terminal 5 — Tester
claude -p "/sdlc-worker --slot T5"

4. オーケストレーターを起動する

# Add to crontab (runs every 15 minutes)
crontab -e
# Add: */15 * * * * ~/.claude/sdlc/agentflow-cron.sh >> /path/to/private/agentflow-orchestrate.log 2>&1

5. 監視して介入する

スマートフォンでカンバンボードを開きます。タスクがパイプラインを進む様子を確認してください。介入するには、カードを「Needs Human」にドラッグします。ターミナルダッシュボードを表示するには、/sdlc-health を実行します。

6. パイプラインを停止する

claude -p "/sdlc-stop"

品質ゲート

各ステージでは、次のステージに進む前に特定のゲートを適用します。

• ビルドからレビューへ：tsc、eslint、npm test がすべて成功する必要があります（決定論的）。
• レビューからテストへ：エビデンスに基づくレビューでブロッキング指摘を解決し、カバレッジを記録します。
• テストから統合へ：新規ファイルでカバレッジ80％以上が必要です。
• 統合から完了へ：必須の保護されたマージチェックとマージ後の検証を行います。範囲を限定したロールバックはリポジトリのワークフローに従います。

コストの追跡

以下のコストは過去の参考例であり、現在の価格や実装済みの保証を示すものではありません。プロバイダー、モデル、ツールの料金を確認し、ディスパッチ前に合意した通貨で予算を確保して、再試行や並列実行のコストを追跡し、実際の請求額と照合してください。

ステージごとの上限額を設定したタスク単位のコスト追跡（デフォルトはSonnet）：

• 調査：約$0.10
• ビルド：約$0.40
• レビュー：約$0.10
• テスト：約$0.05
• 統合：約$0.03

自動ガードレール：$3／$8で警告、$10／$20（Sonnet／Opus）で強制停止し、人間にエスカレーションします。

安全性と復旧

• 自動リバート：統合の失敗時には、範囲を限定したロールバックを検証したうえで実行する必要があります。リバートではデータベースの変更や外部への影響を元に戻せない場合があります。
• ブロックされたタスク：2回試行して失敗した後、タスクは人間によるレビューにエスカレーションされます。
• 停止したエージェントの検出：5分ごとにハートビートを確認し、10分のタイムアウト後に再割り当てします。
• 安全なシャットダウン：/sdlc-stop はワーカーの処理を完了させ、未着手のタスクをバックログに戻します。
• スコープクリープの検出：PRの差分ファイルを、予測されたファイルの一覧と比較します。
• 仕様のずれの検出：SHA-256ハッシュの比較により、スプリント中の要件変更を検出します。

インストール

# Clone the repo
git clone https://github.com/UrRhb/agentflow.git

# Copy skills and prompts to your Claude Code config
# Inspect the fixed checkout, license and host-supported setup.
# Copy only explicitly selected files to the authorized host location, preserving existing files.

または、Claude Code プラグインとしてインストールします。

/plugin marketplace add UrRhb/agentflow
/plugin install agentflow

ベストプラクティス

• 推奨：/spec-to-board を実行する前に、明確な SPEC.md を作成します。
• 推奨：一般的なプロジェクトでは、3～4人のワーカーから始めます。
• 推奨：カンバンボードで監視し、必要に応じてカードを「Needs Human」にドラッグします。
• 推奨：定期的に LEARNINGS.md を確認します。よくある失敗パターンが記録されています。
• 非推奨：決定論的な品質ゲートを省略しないでください。低コストで大半の問題を検出できます。
• 非推奨：main への強制プッシュは避けてください。AgentFlow は復旧に、保護された範囲限定のロールバックを使用します。
• 非推奨：プロジェクトが並列処理できる数を超えてワーカーを実行しないでください。

トラブルシューティング

問題：ワーカーが停止した、または応答しなくなったように見える

症状： タスクカードが15分以上移動せず、新しいコメントもありません
解決方法： オーケストレーターはハートビートで停止したエージェントを検出し、10分後に再割り当てします。問題が続く場合は、/sdlc-health を実行して状態を確認し、カードを手動でバックログに戻してください。

問題：コストガードレールが作動した

症状： タスクがCOST:CRITICALタグ付きで「Needs Human」に移動しました
解決方法： タスクのコメントスレッドを確認し、蓄積されたコンテキストを確認してください。予算を増やす、タスクを簡素化する、または小さな単位に分割するかを判断します。

問題：マージ後に統合テストが失敗した

症状： タスクがmainから自動的にリバートされました
解決方法： 検証済みのリバートによってソースの動作を復元できる場合がありますが、それだけでデータが復元されるわけではなく、安定性が保証されるわけでもありません。コメント内のタスクの再試行コンテキストを確認してください。そこには、試した内容と失敗した内容が記載されています。次に割り当てられたワーカーは、このコンテキストを使用します。

関連スキル

• @brainstorming - AgentFlow を使う前に SPEC.md の設計に使用します。
• @writing-plans - タスク分解のための仕様書作成を補完します。
• @test-driven-development - AgentFlow の品質ゲートと相性よく使えます。
• @subagent-driven-development - マルチエージェント調整のための別のアプローチです。

追加リソース

• AgentFlow リポジトリ
• アーキテクチャのドキュメント
• ギャップレジストリ（45 の失敗モード）
• はじめに

制限事項

• タスクが上記の説明された範囲に明確に該当する場合に限り、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。