AAD - Autonomous Agent Development Orchestrator

TypeScript/Bun製マルチエージェント開発オーケストレーター。Claude CLIを活用し、TDDパイプラインによる並列タスク実行を自動化します。

主要機能

• マルチエージェント並列実行: 複数のClaudeエージェントが独立したタスクを並列処理
• TDDパイプライン: Red → Green → Verify → Review → Merge の自動化されたテスト駆動開発
• スマート実行最適化: テスト事前チェックで既に通過済みタスクを自動スキップ (v0.5.0)
• 実行メトリクス: スキップ/実行タスク数を完了時に表示、効率を可視化 (v0.5.0)
• インタラクティブモード: aad で対話型ウィザードを起動、認証・プロジェクト設定を簡単に (v0.3.6)
• セルフアップデート: aad update で最新版に自動更新 (v0.3.6)
• スマートブランチ命名: 要件ドキュメントから自動でconventional commit prefix付きブランチ名を生成 (v0.3.7)
• 適応的エフォート調整: タスク複雑度に応じてClaudeのeffort levelを自動調整
• マルチリポジトリ対応: 複数リポジトリにまたがるタスクの統合管理
• プラグインシステム: カスタムアダプター・パイプラインステップの拡張
• Git Workspace管理: タスクごとに独立したworktreeを自動作成・管理
• 依存関係解決: タスク間の依存関係を自動検出し、適切な順序で実行
• リアルタイム監視: TypeScript化されたWebダッシュボードで進捗・ログをリアルタイム表示 (v0.5.0)
• 構造化ログ: pinoによる構造化ログで詳細なトレーシングが可能
• メモリ安全機構: OOMを防止する自動メモリゲート・シーケンシャルフォールバック

🎉 v0.5.0の新機能

スマート実行最適化

既にテストが通過しているタスクを自動でスキップするpre-check機能を追加しました。これにより、再実行時や部分的な変更時の実行時間を大幅に短縮できます。

• デフォルトで有効: skipCompleted: true (設定で無効化可能)
• 従来の動作に戻す: --strict-tdd フラグで完全なTDDパイプラインを強制実行
• メトリクス表示: 実行完了時にスキップ/実行タスク数を表示

# スマート実行（デフォルト）- テスト通過済みタスクを自動スキップ
aad run requirements.md

# 完全TDD実行 - 全タスクで完全なパイプラインを実行
aad run requirements.md --strict-tdd

UX改善

• Dashboard URL自動表示: aad run/aad resume実行時にダッシュボードURLを自動表示
• Resume案内表示: Ctrl+C中断時にaad resume <run-id>コマンド例を表示
• TypeScript化Dashboard: React風コンポーネントでメンテナンス性向上

テストスイート強化

• 1037テスト全pass: 30個の失敗を解消し、全テストが通過
• E2Eテスト追加: cleanup, TDD pipeline, dashboardの包括的E2Eテスト
• CI強化: E2Eジョブ分離、build matrix (ubuntu + macos)

アーキテクチャ

AADは12個のモジュールで構成されたHexagonal-flavored Modular Monolithです:

cli (エントリポイント)
├── planning (要件→タスク分解) ★
├── task-queue (タスクライフサイクル管理)
├── task-execution (TDDパイプライン実行) ★
├── process-manager (ワーカープロセス管理)
├── git-workspace (worktree/branch管理)
├── claude-provider (SDK/CLI抽象化) ★
├── persistence (状態永続化) ★
├── logging (構造化ログ)
├── dashboard (Web UI)
├── multi-repo (マルチリポジトリ統合) ★
└── plugin (プラグインシステム) ★

★ = Ports & Adapters パターン適用

技術スタック

• 言語: TypeScript (strict mode)
• ランタイム: Bun v1.2+
• テストフレームワーク: bun:test (Jest互換API)
• Web Framework: Hono
• ロガー: pino v9
• バリデーション: Zod
• CLI: Commander.js

インストール

⚠️ Bun専用 — AADはBunランタイムが必要です。Node.jsでは動作しません。

前提条件

• Bun v1.2 以上
• Git
• Claude CLI (オプション: CLI adapter使用時)

インストール不要で実行 (推奨)

bunx @ronkovic/aad run requirements.md

グローバルインストール

bun install -g @ronkovic/aad
aad run requirements.md

スタンドアロンバイナリ

git clone https://github.com/ronkovic/aad.git
cd aad && bun install
bun run build    # → ./aad バイナリを生成
./aad --version

ローカル開発

git clone https://github.com/ronkovic/aad.git
cd aad
bun install
bun run dev

システム要件

| | RAM | 推奨ワーカー数 | |---|---|---| | 最小 | 8GB | 1（シングルワーカー） | | 推奨 | 16GB | 2（並列ワーカー） |

メモリ安全機能:

• 自動メモリゲート — 空きメモリが閾値を下回ると新規ワーカーの起動を抑制
• シーケンシャルフォールバック — メモリ不足時に並列実行から逐次実行へ自動切替
• グレースフルシャットダウン — メモリ圧迫時に安全にプロセスを終了
• ランタイム監視 — 実行中のメモリ使用量をリアルタイムで監視

macOS: メモリ監視は vm_stat ベースで実装されています。Linux環境では /proc/meminfo を使用します。

コマンドリファレンス

グローバルオプション

以下のオプションはすべてのコマンドで使用可能です:

| オプション | 説明 | デフォルト | |----------|------|----------| | -w, --workers <数> | 並列実行するワーカー数 | 2 | | --persist <モード> | 永続化モード: memory (インメモリ) または fs (ファイルシステム) | memory | | --debug | デバッグログを有効化 | false | | --no-dashboard | Webダッシュボードを無効化 | false (有効) | | --provider <タイプ> | デフォルトのClaudeプロバイダー: cli または sdk | sdk |

コマンド一覧

aad (引数なし)

インタラクティブモードを起動します。認証設定、プロジェクト設定、実行を対話的に行うウィザードです。

aad

フロー:

1. 認証設定: Claude API キーまたは OAuth トークンを設定
2. プロジェクト設定: 要件ファイルとプロジェクトディレクトリを選択
3. 実行: ワーカー数とプロバイダーを選択して実行

aad run <requirements>

要件ファイルを元にタスクを計画・実行します。

aad run requirements.md [オプション]

引数:

• <requirements>: 要件ファイルのパス（必須）

オプション:

| オプション | 説明 | デフォルト | |----------|------|----------| | -w, --workers <数> | 並列実行するワーカー数 | 2 | | --persist <モード> | 永続化モード: memory または fs | memory | | --debug | デバッグログを有効化 | false | | --no-dashboard | Webダッシュボードを無効化 | false | | --provider <タイプ> | Claudeプロバイダー: cli または sdk | sdk | | --repos <パス> | マルチリポジトリモード: カンマ区切りのリポジトリパス | - | | --strategy <戦略> | マルチリポジトリ戦略: independent (独立) または coordinated (協調) | independent | | --plugins <パス> | カスタムプラグインのパス（カンマ区切り） | - | | --keep-worktrees | 完了後にworktreeとブランチを自動削除しない | false (自動削除) | | --dry-run | タスク一覧のみ表示して実行しない（ドライラン） | false | | --strict-tdd | 事前チェックをスキップし、常に完全なTDDパイプラインを実行 | false (最適化有効) |

例:

# 基本的な実行
aad run requirements.md

# ワーカー数を指定
aad run requirements.md --workers 4

# CLIプロバイダーを使用
aad run requirements.md --provider cli

# ダッシュボードを無効化
aad run requirements.md --no-dashboard

# ドライラン（タスク一覧のみ表示）
aad run requirements.md --dry-run

# worktreeを残す（手動クリーンアップが必要）
aad run requirements.md --keep-worktrees

# デバッグモード
aad run requirements.md --debug

# 完全なTDDパイプライン（最適化無効）
aad run requirements.md --strict-tdd

# マルチリポジトリモード
aad run requirements.md --repos /path/to/repo1,/path/to/repo2 --strategy coordinated

aad resume <runId>

中断された実行を再開します。

aad resume <runId>

引数:

• <runId>: 再開する実行のID（必須）

例:

# 特定のrunを再開
aad resume abc-123-def-456

# runIdは `aad status` で確認可能
aad status
aad resume <表示されたrunId>

動作:

• running または failed 状態のタスクを pending にリセット
• ワーカーを再初期化してタスクを再実行
• 完了済みのタスクはスキップ

aad status [run-id]

実行の進捗とタスクステータスを表示します。

aad status [run-id]

引数:

• [run-id]: 確認する実行のID（省略時は最新の実行を表示）

例:

# 最新の実行を表示
aad status

# 特定のrunを表示
aad status abc-123-def-456

表示内容:

• 実行ID、親ブランチ、開始時刻
• タスク総数、pending/running/completed/failed の数
• 各タスクの詳細（タスクID、タイトル、ステータス、ワーカーID）

aad cleanup [run-id]

worktreeと孤立したブランチをクリーンアップします。

aad cleanup [run-id] [オプション]

引数:

• [run-id]: クリーンアップする実行のID（省略時はすべてのAAD worktreeを対象）

オプション:

| オプション | 説明 | デフォルト | |----------|------|----------| | -f, --force | 変更があるworktreeも強制削除、parentブランチも削除 | false |

例:

# すべてのAAD worktreeをクリーンアップ（parentは保護）
aad cleanup

# 特定のrunのみクリーンアップ
aad cleanup abc-123-def-456

# 強制削除（parentブランチも削除、変更も無視）
aad cleanup --force
aad cleanup abc-123-def-456 --force

動作:

• デフォルトではparentブランチとworktreeを保護（レビュー用）
• --force を指定すると parent を含むすべてのworktreeとブランチを削除
• 孤立したworktreeは自動的にprune

aad update

AADを最新バージョンに更新します。

aad update [オプション]

オプション:

| オプション | 説明 | デフォルト | |----------|------|----------| | --check | 更新の有無のみ確認（インストールしない） | false |

例:

# 最新版に更新
aad update

# 更新の有無のみ確認
aad update --check

動作:

• 現在のバージョンと最新バージョンをnpmレジストリから取得して比較
• bun使用時は bunx キャッシュをクリア（次回実行時に最新版を使用）
• npm使用時は npm install -g @ronkovic/aad@latest を実行

aad interactive

インタラクティブモードを明示的に起動します（aad のみと同じ）。

aad interactive

クイックスタート

1. 要件ファイルの作成

requirements.md を作成してタスクを記述:

# タスク一覧

## Task 1: ユーザー認証機能の実装
- ファイル: src/auth/login.ts
- テスト: src/auth/__tests__/login.test.ts
- 依存: なし

## Task 2: ダッシュボードUI作成
- ファイル: src/ui/dashboard.tsx
- テスト: src/ui/__tests__/dashboard.test.tsx
- 依存: Task 1

2. タスク実行

# 直接実行
aad run requirements.md

# ワーカー数を指定
aad run requirements.md --workers 4

# インタラクティブモード（対話型ウィザード）
aad

AADが自動的に:

1. 要件ドキュメントからfeature名を生成（例: feat/user-auth-impl）
2. タスクを分解・依存関係を解析
3. 親ブランチ + タスクブランチをworktreeで作成
4. ワーカーで並列実行 (TDD: テスト作成 → 実装 → 検証 → レビュー)
5. 親ブランチへのマージ

よく使うオプション:

• --workers <数>: 並列ワーカー数（デフォルト: 2）
• --provider cli: Claude CLIを使用（デフォルトは SDK）
• --dry-run: タスク一覧のみ表示（実行しない）
• --keep-worktrees: 完了後もworktreeを削除しない
• --debug: デバッグログを有効化

詳細は コマンドリファレンス をご覧ください。

3. 進捗確認・管理

# ステータス確認（最新の実行）
aad status

# 特定の実行のステータス確認
aad status <run_id>

# 中断された実行の再開
aad resume <run_id>

# worktreeのクリーンアップ（parentは保護）
aad cleanup

# 特定のrunのクリーンアップ
aad cleanup <run_id>

# 強制クリーンアップ（parentも削除）
aad cleanup --force

# バージョン確認・アップデート
aad update
aad update --check

すべてのコマンドとオプションの詳細は コマンドリファレンス をご覧ください。

4. Webダッシュボード

ダッシュボードはデフォルトで有効です。http://localhost:7333 でリアルタイムの進捗・ログ・依存グラフを確認できます。

ダッシュボード機能:

• タスク進捗のリアルタイム可視化
• ワーカーステータス監視
• タスク依存グラフ (DAG)
• 構造化ログのストリーミング表示
• タスクタイムライン (Gantt)

無効にする場合:

aad run requirements.md --no-dashboard

ポート変更: 設定ファイル .aad/config.json で dashboard.port を変更できます。

開発ガイド

環境セットアップ

# 依存関係のインストール
bun install

# 型チェック
bun run typecheck

# テスト実行
bun test

# ウォッチモード
bun test --watch

# Lint
bun run lint

ビルド & 配布

# 単一バイナリのビルド (self-contained実行ファイル)
bun build --compile ./src/main.ts --outfile aad

# 実行
./aad --version

モジュール境界ルール

各モジュールは index.ts でのみ公開APIをエクスポートします:

// ✅ Good
import { TaskQueue } from "@aad/task-queue";

// ❌ Bad: モジュール内部へのアクセス
import { Dispatcher } from "@aad/task-queue/dispatcher";

テストの書き方

import { describe, test, expect } from "bun:test";

describe("MyModule", () => {
  test("should do something", () => {
    expect(true).toBe(true);
  });
});

設定

.aad/config.json で動作をカスタマイズできます:

{
  "workers": {
    "num": 4,
    "max": 8
  },
  "models": {
    "default": "sonnet",
    "splitter": "sonnet",
    "tester": "sonnet",
    "implementer": "sonnet",
    "reviewer": "sonnet",
    "mergeResolver": "haiku"
  },
  "timeouts": {
    "claude": 1200,
    "test": 600
  },
  "dashboard": {
    "enabled": true,
    "port": 7333
  },
  "skipCompleted": true,
  "strictTdd": false
}

利用可能なモデル

models設定で指定できるモデル名:

| フルネーム | 短縮名 | 説明 | |-----------|--------|------| | claude-sonnet-4-5-20250929 | sonnet | Sonnet 4.5 - バランス型、推奨デフォルト | | claude-opus-4-6 | opus | Opus 4.6 - 最高性能、高コスト | | claude-haiku-4-5-20251001 | haiku | Haiku 4.5 - 高速・低コスト |

設定では短縮名(sonnet、opus、haiku)またはフルネームが使用できます。

ブランチフロー

AADは要件ドキュメントからconventional commit prefix付きのfeature名を自動生成し、以下のブランチ構造を作成します:

main (ソースブランチ)
  └─ feat/user-auth-impl/parent      ← 親ブランチ + worktree
       ├─ feat/user-auth-impl/task-001  ← タスクブランチ（parentから分岐）
       ├─ feat/user-auth-impl/task-002
       └─ feat/user-auth-impl/task-003

各タスクはparentブランチから分岐し、完了後にparentへマージされます。prefix（feat/, fix/, refactor/等）は要件の内容から自動判定されます。

Claude Provider: SDK vs CLI

AADはClaudeとの通信に2つのadapterを提供:

• SDK Adapter (claude-sdk.adapter.ts): Agent SDK経由、構造化出力に最適
• CLI Adapter (claude-cli.adapter.ts): Claude CLI経由、重いファイル操作に最適

サービスごとに使い分け可能:

デフォルトは sdk です。CLIに変更する場合:

aad run requirements.md --provider cli

サービスごとに使い分けも可能です（設定ファイルで指定）。

トラブルシューティング

ログの確認

# 構造化ログの確認
cat .aad/docs/<run_id>/logs/structured.jsonl | bunx pino-pretty

# デバッグモードで実行
aad run requirements.md --debug

Worktreeが残っている

# 全AAD worktreeをクリーンアップ（parentは保護）
aad cleanup

# 特定のrunのみ
aad cleanup <run_id>

# parentも含めて強制削除
aad cleanup --force

タスクがスタックした

# ステータス確認
aad status <run_id>

# 実行を再開
aad resume <run_id>

# 強制クリーンアップして最初からやり直し
aad cleanup <run_id> --force
aad run requirements.md

メモリ不足エラー

AADは自動的にメモリを監視し、不足時にワーカー数を削減します。手動でワーカー数を減らすこともできます:

# ワーカー数を1に減らす
aad run requirements.md --workers 1

コマンドオプションの詳細

すべてのコマンドとオプションの詳細は コマンドリファレンス をご覧ください。

ライセンス

MIT License

貢献

コントリビューションを歓迎します! 詳細は CONTRIBUTING.md をご覧ください。

開発の流れ

1. このリポジトリをfork
2. feature branchを作成 (git checkout -b feature/amazing-feature)
3. 変更をcommit (git commit -m 'feat: add amazing feature')
4. branchをpush (git push origin feature/amazing-feature)
5. Pull Requestを作成

リンク

• npm Package
• Project Guidelines
• Issue Tracker

Built with ❤️ using Bun and Claude