🎼

takt 入門 - AI マルチエージェントオーケストレーションで開発ワークフローを自動化する

に公開
AI
Copilot
codereview
Claude Code
TAKT
tech

はじめに

AI コーディングエージェントを使った開発で、こんな課題を感じたことはないでしょうか。

単一モデルの限界

AI にコードを書かせて、同じ AI にレビューさせる。これは人間の開発で言えば「自分で書いたコードを自分でレビューする」のと同じです。以下のような問題が起きがちです。

  • 自己強化バイアス: 自分が生成したコードの問題を見つけにくい。同じモデルは同じ思考パターンで評価するため、実装時に見落とした問題はレビュー時にも見落とす傾向がある
  • モデル固有の癖: 各モデルには得意・不得意がある。あるモデルが好むパターン（過剰な抽象化、不要なコメント、存在しない API の使用等）は、同じモデルでレビューしても指摘されにくい
  • 多様な視点の欠如: 人間のチーム開発でペアプログラミングやコードレビューが有効なのは、異なる視点が入るから。AI でも同じことが言える。実際、Claude Code にセルフレビューさせても気づかなかった点に Copilot が気づくケースは経験的に多い

手動オーケストレーションの限界

複数の AI モデルを使い分けようとしても、実際には面倒です。

  • 「実装 → レビュー → 修正 → 再レビュー」のサイクルを毎回手動で回している
  • モデルを切り替えるたびにコンテキストを再共有する必要がある
  • 複数のエージェントに異なる役割を持たせたいが、プロンプトの管理が煩雑

takt は、これらの課題を YAML ベースのワークフロー定義で解決するマルチエージェントオーケストレーションツールです。

https://github.com/nrslib/takt

takt とは

takt（TAKT Agent Koordination Topology）は、AI コーディングエージェント向けのワークフロー自動化ツールです。

主な特徴:

  • YAML でワークフローを宣言的に定義
  • 複数の AI プロバイダを混在して使用可能
  • ペルソナ（役割）、ポリシー（方針）、ナレッジ（知識）を組み合わせてエージェントの振る舞いを制御
  • Git worktree による安全な並列作業
  • PR の自動作成

対応プロバイダ:

プロバイダ 説明
claude Claude Code CLI
claude-sdk Claude SDK 直接利用
copilot GitHub Copilot CLI
codex OpenAI Codex CLI
opencode OpenCode
cursor Cursor Agent

インストール

npm install -g takt

基本概念

takt のワークフローは以下の要素で構成されます。

ステップ（Steps）

ワークフローの各段階です。ステップごとに「誰が（persona）」「何の方針で（policy）」「何の知識を使って（knowledge）」「何をするか（instruction）」を定義します。

遷移ルール（Rules）

ステップの完了条件と次のステップを定義します。条件分岐で COMPLETE（完了）や ABORT（中止）も指定可能です。

ループ監視（Loop Monitors）

「レビュー → 修正 → 再レビュー」のサイクルが無限ループに陥るのを防ぎます。閾値（最大サイクル数）と、supervisor ペルソナによる健全性判定を組み合わせます。

ファセット（Faceted Prompting）

エージェントのプロンプトを構成する4つの要素です。各ファセットは Markdown ファイルで定義されます。

ファセット 説明 例
Persona エージェントの役割・人格・行動方針 planner, coder, supervisor
Policy 従うべき方針・基準 coding, testing, review
Knowledge 参照する知識ベース architecture, unit-testing
Instruction ステップごとの具体的な指示 plan, implement-after-tests

ビルトインファセットとカスタムファセット

takt は 日本語・英語のビルトインファセットを多数同梱しています。ワークフロー YAML で persona: planner と書くだけで、ビルトインの Planner ペルソナが適用されます。

ビルトインペルソナ一覧（日本語版、v0.35.4 時点）
ペルソナ 用途
planner タスク分析と設計計画
coder コーディングと実装（テスト含む）
supervisor 品質検証と総合判定
architecture-reviewer アーキテクチャレビュー
ai-antipattern-reviewer AI 生成コード特有のアンチパターン検出
security-reviewer セキュリティレビュー
frontend-reviewer フロントエンドレビュー
testing-reviewer テストレビュー
qa-reviewer QA レビュー
terraform-coder Terraform 実装
terraform-reviewer Terraform レビュー
pr-commenter PR コメント作成
research-planner / research-digger / research-analyzer リサーチ系
他多数
ビルトインポリシー一覧

coding, testing, review, ai-antipattern, terraform, qa, research, design-fidelity, design-planning, screen-api, task-decomposition

ビルトインナレッジ一覧

architecture, unit-testing, e2e-testing, frontend, backend, react, security, terraform-aws, cqrs-es, research, takt

各ファセットは Markdown ファイルで定義されており、プロジェクト固有のカスタムファセットも作成可能です。プロジェクトルートの .takt/facets/personas/ 等に配置すると、ビルトインより優先されます。

例えば、ビルトインの planner ペルソナは以下のような内容です:

# Planner

あなたはタスク分析と設計計画の専門家です。
ユーザー要求を分析し、コードを調査して不明点を解決し、
構造を意識した実装方針を立てます。

## 役割の境界

**やること:**
- ユーザー要求の分析・理解
- コードを読んで不明点を自力で解決する
- 影響範囲の特定
- ファイル構成・設計パターンの決定

**やらないこと:**
- コードの実装
- コードレビュー

## 行動姿勢
- 調査してから計画する。既存コードを読まずに計画を立てない
- 推測で書かない。名前・値・振る舞いは必ずコードで確認する
...

このように、各ペルソナは「やること / やらないこと」の境界や行動方針が詳細に定義されています。

出力成果物（Output Contracts）

各ステップが生成するレポートの形式を定義します。後続のステップがこのレポートを参照して判断します。

ワークフロー例1: テスト駆動開発（TDD）

まず、~/.takt/config.yaml でグローバル設定を行います。

provider: claude
model: opus
language: ja

次に、テスト駆動開発（TDD）ワークフロー（~/.takt/workflows/default.yaml）の全体像です。

plan (planner)
  ↓ 要件が明確
write_tests (coder)
  ↓ テスト作成完了
implement (coder)
  ↓ 実装完了
ai_review (ai-antipattern-reviewer)
  ↓ AI特有の問題なし     ↓ 問題あり
  ↓                    ai_fix (coder) → ai_review（threshold で制限）
reviewers ── arch-review (architecture-reviewer)
          └─ supervise (supervisor)        ※ 並列実行
  ↓ 全て承認             ↓ 指摘あり
COMPLETE               fix (coder) → reviewers（threshold で制限）

注: 簡略化したフロー図です。実際の YAML にはセルフループ（ユーザー入力待ち）や ABORT への遷移パスも定義されています。

ポイント

1. AI アンチパターンレビュー

ai-antipattern-reviewer ペルソナが、AI 生成コード特有の問題（不要なコメント、過剰な抽象化、存在しない API の使用等）を検出します。

- name: ai_review
  edit: false
  persona: ai-antipattern-reviewer
  policy:
    - review
    - ai-antipattern
  rules:
    - condition: AI特有の問題なし
      next: reviewers
    - condition: AI特有の問題あり
      next: ai_fix

2. 並列レビュー

reviewers ステップでは、アーキテクチャレビューと監督レビューを並列で実行します。

- name: reviewers
  parallel:
    - name: arch-review
      persona: architecture-reviewer
      policy: review
      knowledge: architecture
    - name: supervise
      persona: supervisor
      policy: review
  rules:
    - condition: all("approved", "すべて問題なし")
      next: COMPLETE
    - condition: any("needs_fix", "要求未達成、テスト失敗、ビルドエラー")
      next: fix

3. ループ監視

レビューと修正のサイクルが無限ループに陥るのを防ぎます。supervisor ペルソナが進捗を判定し、非生産的なループを検出したら脱出します。

loop_monitors:
  - cycle:
      - reviewers
      - fix
    threshold: 3
    judge:
      persona: supervisor
      instruction: loop-monitor-reviewers-fix
      rules:
        - condition: 健全（指摘数が減少、修正が反映されている）
          next: reviewers
        - condition: 非生産的（同じ指摘が繰り返される）
          next: ABORT

4. 権限制御

レビュアはコードを変更できず、coder だけが編集権限を持ちます。

# レビュアは読み取り専用
- name: ai_review
  edit: false

# coder は編集可能
- name: implement
  edit: true
  required_permission_mode: edit

ワークフロー例2: クロスレビュー

複数の AI プロバイダを組み合わせた「クロスレビュー」ワークフロー（~/.takt/workflows/cross-review.yaml）です。

設計意図

単一モデルのバイアスを排除するため、実装とレビューで異なる AI モデルを使います。

  • Claude Code (Opus): 実装・修正・最終レビュー
  • Copilot CLI (GPT 5.4 xthink): 中間レビュー
plan (Claude/Opus)
  ↓
implement (Claude/Opus)
  ↓
copilot_review (Copilot/GPT 5.4 xthink) ←──┐
  ↓ approved          ↓ needs_fix           │
  ↓                   fix (Claude/Opus) ────┘ threshold で制限
claude_review (Claude/Opus)
  ↓ すべて問題なし     ↓ 要求未達成
  ↓                   fix → copilot_review から再走行（threshold で制限）
COMPLETE

注: fix ステップの遷移先は常に copilot_review です。claude_review で指摘があった場合も、fix → copilot_review → claude_review のフロー全体を再走行します。

YAML 設定（全文）

name: cross-review
description: Claude Code で実装 → Copilot でレビュー → 修正 → Claude でアーキテクチャレビュー → 完了
max_steps: 20
initial_step: plan
loop_monitors:
  - cycle:
      - copilot_review
      - fix
    threshold: 3
    judge:
      persona: supervisor
      instruction: |
        copilot_review と fix のループが {cycle_count} 回繰り返されました。
        各サイクルのレポートを確認し、このループが健全（進捗がある）か、
        非生産的（同じ問題を繰り返している）かを判断してください。

        **参照するレポート:**
        - Copilotレビュー結果: {report:copilot-review.md}

        **判断基準:**
        - 各サイクルで指摘数が減少しているか
        - 同じ指摘が繰り返されていないか
        - 修正が実際に反映されているか
      rules:
        - condition: 健全（指摘数が減少、修正が反映されている）
          next: copilot_review
        - condition: 非生産的（同じ指摘が繰り返される）
          next: claude_review
  - cycle:
      - claude_review
      - fix
    threshold: 3
    judge:
      persona: supervisor
      instruction: |
        claude_review と fix のループが {cycle_count} 回繰り返されました。
        各サイクルのレポートを確認し、このループが健全（進捗がある）か、
        非生産的（同じ問題を繰り返している）かを判断してください。

        **参照するレポート:**
        - Claudeレビュー結果: {report:claude-review.md}

        **判断基準:**
        - 各サイクルで指摘数が減少しているか
        - 同じ指摘が繰り返されていないか
        - 修正が実際に反映されているか
      rules:
        - condition: 健全（指摘数が減少、修正が反映されている）
          next: claude_review
        - condition: 非生産的（同じ指摘が繰り返される）
          next: ABORT

steps:
  - name: plan
    edit: false
    persona: planner
    provider: claude
    model: opus
    knowledge: architecture
    provider_options:
      claude:
        effort: max
    instruction: plan
    rules:
      - condition: 要件が明確で実装可能
        next: implement
      - condition: ユーザーが質問をしている（実装タスクではない）
        next: COMPLETE
      - condition: 要件が不明確、情報不足
        next: ABORT
    output_contracts:
      report:
        - name: plan.md
          format: plan

  - name: implement
    edit: true
    persona: coder
    provider: claude
    model: opus
    policy:
      - coding
      - testing
    knowledge: architecture
    provider_options:
      claude:
        effort: max
    required_permission_mode: edit
    instruction: implement-after-tests
    rules:
      - condition: 実装完了
        next: copilot_review
      - condition: 実装未着手（レポートのみ）
        next: copilot_review
      - condition: 判断できない、情報不足
        next: ABORT

  - name: copilot_review
    edit: false
    persona: architecture-reviewer
    provider: copilot
    model: gpt-5.4
    provider_options:
      copilot:
        effort: xhigh
    policy: review
    knowledge: architecture
    instruction: review-arch
    rules:
      - condition: approved
        next: claude_review
      - condition: needs_fix
        next: fix
    output_contracts:
      report:
        - name: copilot-review.md
          format: architecture-review

  - name: fix
    edit: true
    persona: coder
    provider: claude
    model: opus
    policy:
      - coding
      - testing
    knowledge: architecture
    provider_options:
      claude:
        effort: max
    required_permission_mode: edit
    instruction: fix
    pass_previous_response: false
    rules:
      - condition: 修正完了
        next: copilot_review
      - condition: 判断できない、情報不足
        next: ABORT

  - name: claude_review
    edit: false
    persona: supervisor
    provider: claude
    model: opus
    policy: review
    provider_options:
      claude:
        effort: max
    instruction: supervise
    rules:
      - condition: すべて問題なし
        next: COMPLETE
      - condition: 要求未達成、テスト失敗、ビルドエラー
        next: fix
    output_contracts:
      report:
        - name: claude-review.md
          format: supervisor-validation
        - name: summary.md
          format: summary
          use_judge: false

ポイント

1. effort レベル

各ステップで AI の推論の深さを制御できます。

プロバイダごとに段階が異なります。

プロバイダ 段階 最高値
Claude low / medium / high / max max
Copilot low / medium / high / xhigh xhigh（xthink モード相当）

本ワークフローでは Claude に max、Copilot に xhigh を指定し、両方とも最高の推論深度で実行します。

2. 修正は実装者（Claude）に戻す

Copilot がレビューで指摘を出しても、修正は Claude が行います。コードベースに精通した同じモデルが修正することで、一貫性を保ちます。

3. ループ監視で品質を担保

copilot_review ↔ fix と claude_review ↔ fix の両方に loop_monitors を設定。指摘が無くなるまで修正サイクルを繰り返しつつ、同じ指摘の堂々巡りは supervisor が検出してループを抜けます。これまで手動で「レビュー → 修正依頼 → 再レビュー」を繰り返していた作業が自動化されます。

4. 最終レビューは Claude の supervisor

Copilot レビューを通過した後、Claude の supervisor ペルソナが最終確認を行います。テスト結果やビルド状態も含めた総合判定です。

実行方法

単発実行

# デフォルトワークフローで実行
takt "ユーザー認証機能を追加"

# ワークフローを指定して実行
takt -w cross-review "ログイン画面のバリデーションを強化"

Issue 連携

# GitHub Issue を参照して実行
takt "#123"
takt -i 123

タスクキュー

# タスクを追加
takt add "リファクタリング: 認証モジュール"

# 全ペンディングタスクを実行
takt run

# 監視モード（新規タスクを自動実行）
takt watch

PR 自動作成

# 実行完了後に PR を自動作成
takt --auto-pr "バグ修正: セッションタイムアウト"

# ドラフト PR として作成
takt --auto-pr --draft "#456"

Claude Code Agent Teams との比較

Claude Code には組み込みの Agent Teams 機能があり、複数エージェントの協調実行が可能です。takt とどう違うのかを整理します。

項目 takt Claude Code Agent Teams
プロバイダ Claude, Copilot, Codex, OpenCode, Cursor Claude のみ
ワークフロー定義 YAML ファイル（バージョン管理可能） agents.md でエージェント定義は可能。ワークフロー全体の定義は不可
再現性 同じ YAML で何度でも同じワークフローを実行 エージェント定義は永続化できるが、実行フローは毎回指示
ステップ間の遷移 条件分岐、ループ監視、ABORT/COMPLETE エージェント間のメッセージング
権限制御 ステップごとに edit / read-only を厳密に設定 エージェントごとのツール制限
出力管理 output_contracts で形式を強制 自由形式
CI/CD 統合 --pipeline モードで非インタラクティブ実行 Agent Teams 固有の CI/CD モードはなし
セットアップ npm install -g takt + YAML 記述 組み込み（設定不要）

使い分けの指針

  • アドホックな協調作業（「この PR を3人のレビュアで見て」等）→ Agent Teams が手軽
  • 繰り返し実行するワークフロー（毎回同じ手順で品質保証したい）→ takt で YAML 化
  • 複数モデルのクロスレビュー（Claude で実装 → Copilot でレビュー）→ takt のマルチプロバイダ機能
  • CI/CD に組み込みたい（PR 作成時に自動で品質チェック）→ takt の --pipeline モード

個人的には、takt はワークフローをコードとして管理できる点が最大の価値だと考えています。チーム内で YAML を共有すれば、誰が実行しても同じ品質保証プロセスが走ります。Agent Teams は柔軟性が高い一方、毎回の指示が属人的になりがちです。

まとめ

takt を使うことで、AI コーディングエージェントのワークフローを YAML で宣言的に定義し、繰り返し実行可能な形にできます。

  • テスト駆動開発（TDD）: 計画 → テスト → 実装 → AI レビュー → 並列レビュー の厳密なフロー
  • クロスレビュー: 異なる AI モデル（Claude × Copilot）による相互レビューで、単一モデルのバイアスを排除
  • ループ監視: 無限ループを supervisor が検出して自動で脱出
  • 権限制御: レビュアは読み取り専用、coder のみ編集可能

AI コーディングエージェントの品質を組織的に管理したい場合に、takt は強力な選択肢になると思います。

参考リンク

GitHubで編集を提案

Discussion