はじめに
こんにちは。Legalscape (採用情報) でLLMを用いたWebアプリケーションのエンジニアをやっていますhiroendoreです。
以前参加した勉強会で
のプレゼンを聞き、
最近我が社ではハーネスエンジニアリング
などの考え方を用いた開発の効率化・プロダクト価値向上の速度向上を目指している観点からとても気になったので、TAKT を試しに動かしてみました。
TAKTは、Claude Code や Codex などの AI エージェントを YAML で定義したワークフローに沿って強制的に走らせる CLI ツール。「AI に自由度を与える」のではなく「ワークフローに従わせる」というアプローチが特徴で、計画 → テスト作成 → 実装 → レビュー → 修正 のループを自動で回してくれます。
作者様による概要： TAKT: AIエージェント オーケストレーション ツール
セットアップ
npm install -g takt
10 秒くらいで終わります。
今回は検証用に空のディレクトリを切って takt を起動してみましたが、そうすると対話モードの選択肢が出てきます。
対話モードを選択してください: (↑↓ to move, Enter to select) ❯ アシスタント (default) 確認質問をしてから指示書を作成 ペルソナ 先頭エージェントのペルソナで対話 クワイエット 質問なしでベストエフォートの指示書を生成 パススルー 入力をそのままタスクとして渡す Cancel
今回はデフォルトのアシスタントモードを選択しました。
お題: FizzBuzz + pytest
簡単な例として、こんなお題を投げました。
FizzBuzz を Python で実装してください。 1〜100 まで標準出力に出力するスクリプトと、pytest で動くテストをつけてください。
その後エージェントと対話的にタスクの内容について細かく詰めるフェーズが挟まり、/go を打つと人間の介入はここまでで、TAKT が動き出し約 12 分で完走しました。
ちなみにこの 7 ステップは、ビルトインの default.yaml ワークフローにこう宣言されています（抜粋）。
name: default description: テスト先行開発ワークフロー（計画 → テスト作成 → 実装 → AIアンチパターンレビュー → 並列レビュー → 完了） initial_step: plan steps: - name: plan # 計画作成（planner） - name: write_tests # テスト先行（coder） - name: implement # 実装（coder） - name: ai_review # AI 特有のアンチパターン検出 - name: ai_fix # ai_review の指摘を修正 - name: reviewers # arch-review と supervise を並列実行 - name: fix # reviewers が指摘した内容を修正
実行中は、計画 → テスト作成 → 実装 → AI レビュー → 修正 → 再レビュー → 構造レビュー → 監督検証、と 9 イテレーションが動きました。今回は AI レビュー ↔ 修正のループが 2 回走って収束しています。uv run pytest -v も実行しています。
ワークフローの全体像
各イテレーションがどう繋がって動いていたのか、default ワークフローを一枚図にするとこういう流れです。
flowchart LR
plan --> write_tests --> implement --> ai_review
ai_review -->|問題あり| ai_fix
ai_fix --> ai_review
ai_review -->|問題なし| reviewers
ai_fix -.->|3 回ループしたら<br/>supervisor が判定| reviewers
subgraph reviewers["reviewers（並列実行）"]
direction LR
arch_review[arch-review]
supervise
end
reviewers -->|all 問題なし| COMPLETE
各ステップには
- ペルソナ: そのステップを担当する役割（例: planner / coder / ai-antipattern-reviewer）
- ポリシー: 役割が守るべきルール集（例: coding / testing / review / ai-antipattern）
- Knowledge (knowledge): AI に渡す参考ドメイン知識（例: architecture / unit-testing / e2e-testing）
- 許可ツール (provider_options.claude.allowed_tools): AI に使わせるツール集合（調査系ステップは Read/Glob/Grep 中心、編集系は Edit/Write/Bash まで開ける）
- 出力レポート (output_contracts.report): ステップが書き出す成果物のファイル名と format（例: plan.md / coder-scope.md / ai-review.md）
が宣言されており、フェーズが切り替わるたびに「そのフェーズ専用のプロンプト」が組み立てられて AI に渡される設計です（Faceted Prompting）。
最初のai_reviewの指摘は内容としては「テストに意味のないテンプレコメント（Given/When/Then）が機械的に貼られている」「型ヒントと既存テストで完全に包含されていて検出力ゼロのテストが追加されている」「既存ケースと完全重複したテストが追加されている」と言うもので、そして次のai_fixで 3 件すべて修正され、続く 2 回目の ai_reviewはapproveでした。
ai-antipattern-reviewerという、AI のコードの癖をチェックする専用ペルソナが用意されており、AI 自身が書いたコードを AI 自身が淡々と検出・修正しているのを眺めるのは結構面白い体験でした。
ai-antipatternと言う内容に留まらず様々なアンチパターンを蓄積していくことで、レビューの質をどんどん高めていけそうだと感じました。
また、superviseはdefaultワークフローの最終フェーズで、タスク指示書に書かれた要件が実コードで本当に満たされているかを最終チェックする役割を持つステップです。supervisorというペルソナが、タスク指示書を機械的に分解して 1 件ずつ実装と突き合わせていました。この辺りも充実させていくことで、コードの品質を高めることができそうです。
ワークフローの内部設計
ここまで見てきた挙動の中身は、ビルトインのdefault.yamlというワークフロー定義に書かれています（.../takt/builtins/ja/workflows/default.yaml）。レビュー ↔ 実装の動的ループはこの YAML の loop_monitors で宣言されています。
name: default description: テスト先行開発ワークフロー（計画 → テスト作成 → 実装 → AIアンチパターンレビュー → 並列レビュー → 完了） loop_monitors: - cycle: [ai_review, ai_fix] threshold: 3 judge: persona: supervisor rules: - condition: 健全（進捗あり） → next: ai_review - condition: 非生産的（改善なし） → next: reviewers
ループの回数は固定ではなく、ai_reviewがapproveすれば即抜ける動的な制御になっています。閾値 3 を超えたときだけ supervisor が「健全 / 非生産的」を判定するセーフティネットになっていました。
ビルトインのワークフローは default 以外にも frontend / backend / dual / audit-* / research / terraform / compound-eye / magi など 40 種類以上あって、takt eject <name> で手元にコピーして編集できるので、テンプレートをもとにして自プロジェクトに合わせたチューニングがしやすそうです。
トレースログ
実行ログとしてtrace.mdというファイルが残ります。中身は各イテレーションごとに「実行コンテキスト / Workflow Context / Knowledge / User Request / Instructions」がブロックで並ぶ構造で、たとえば 4 イテレーション目（1 回目の AI レビュー）の冒頭はこんな感じでした。
## Iteration 4: ai_review (persona: ai-antipattern-reviewer) - 2026-04-30T08:01:57.369Z ## Workflow Context - ワークフロー: default - 説明: テスト先行開発ワークフロー（計画 → テスト作成 → 実装 → AIアンチパターンレビュー → 並列レビュー → 完了） このワークフローは7ステップで構成されています: - Step 1: plan - Step 2: write_tests - Step 3: implement - Step 4: ai_review ← 現在 - Step 5: ai_fix - Step 6: reviewers - Step 7: fix - Iteration: 4/30（ワークフロー全体） - Step: ai_review
これが各フェーズに対して続いて、今回は最終的に trace.mdだけで約 10,000 行になりました。後からエージェントの振る舞いとパフォーマンスを追えるのは、エージェントの振る舞いを計測し、改善に役立てられるという点でエージェントを用いて開発効率を向上していく上で重要です。
自作ワークフローも試してみた
自作ワークフロー作成を試すために、HIL（Human-in-the-Loop）込みのレビュー用ワークフローを自作する実験もしてみました。以下の仕様を大まかに考えました。
- PR とブランチの両方に対応
- レビュー観点は流れベースで、随時追記していく
- 途中で人間と対話できる（HIL）
- 最終的に PR コメントとして反映
- レビューで得た観点をナレッジファイルに蓄積
やったこと
- ビルトインのワークフローを読み込む（review-default.yaml / audit-security.yaml / research.yaml の構文を真似る）
- 要件をすり合わせ、4 ステップ構成 (gather → discuss → comment → learn) に分解
- 実現方法を調査
- 内容の確認
claudeにコードの中身を読ませながら作成してもらいました。
HILの実現方法
調べたところ、HILはruleに requires_user_input: true と interactive_only: true を付けることで実現できると分かりました。default.yamlのwrite_testsステップに実例があります。
rules: - condition: ユーザーへの確認事項があるためユーザー入力が必要 next: write_tests requires_user_input: true interactive_only: true
requires_user_inputで「ユーザー入力を求める」遷移を表現し、interactive_onlyで「パイプラインモード（CI 用途）では発火しない」と制限する、という二段の宣言になっています。
動作確認
takt prompt review-guide で「組み立て後のプロンプト」をプレビューでき、takt workflow doctor でワークフローの定義に不備がないか事前にチェックできます。
触ってみての気付き
良かった点:
- 「指示書を作って積む →
takt runで実行」の分離: アシスタントモードで作った指示書はキューに入る形なので、計画と実行のタイミングを分けられます。
大きな開発タスクは小さなタスクに分割することが多いですが、エージェントに任せて一気にコードを書かせると後のレビューやテストの工程で変更が発生したときに後続のタスクでコンフリクトなど手戻りが発生しやすくなると最近は感じています。 そのため、コードを書かせる直前まで計画させておいて、好きなタイミングで実行できるようにしておけるのはありがたいなと感じました。
- オブザーバビリティ: 実行ログ・各フェーズの knowledge/policy/応答・全プロンプトを連結した
trace.md（約 10,000 行）など実行の記録が詳細に残るので、後から監査やパフォーマンスの計測ができます。
引っかかった点:
/goと/playの違いが分かりづらかった: TAKT 内のラベル定義 (labels_ja.yaml) にはこう書かれています。
go: "指示書を作成して実行"
play: "タスクを即実行する"
プロンプト上の説明も「/go（指示書作成・実行）, /play（即実行）」とあるのですが、この文言だけだと「指示書」の有無が何を意味するのか、/go を打たないと何が起きないのか、初見で判別しづらい印象でした。（/go は会話履歴（確認 Q&A 含む）を AI に渡して指示書を構造化生成するモード、/play は直後の文字列をそのままタスクとして渡すモード、とのことです）
- 「今どのステップか・いつ自分が入力する番か」が見えづらい: 確認質問の途中なのか、
/goを打つフェーズなのか、AI 処理待ちなのかが画面から判別しづらい瞬間がありました。「次はあなたの入力を待っています」のような明示があると初見の摩擦が減りそうです。
機構としての設計（YAML での宣言的ワークフロー・facet 分離・実行ログの完全保存）は強力ですが、対話インターフェース側はまだ改善の余地がありそうな印象でした。現状はどちらかというと、人と対話しながら使うというより、定義したワークフローを自律的に走らせる用途に寄せて作られているライブラリなのかなと感じます。
ただ、現状の私のエージェントの使い方は、出来合いのものをインストールして使うというよりも、人間の目を入れながら育てる -> 充分使えるようになったら機械的に人間の手を入れずに実行させる という流れにしたいと考えているので、対話的なインターフェースが充実していると嬉しいなと思いました。
カスタムワークフロー編集後は
takt workflow doctor必須: 特にエージェントにワークフローを編集させると、YAML を弄った後にエラーが出ることがあったので、事前検証なしでtakt runまで進むと時間を無駄にしがちでした。CI に組み込むのもアリかもしれません。エージェントを挟まない deterministic なステップを YAML で宣言できるか、というのが気になりました。
コードを読ませてみたところ結論としては部分的にサポートされていて、ステップに mode: system を指定すると AI を呼ばずにそのまま実行されます。ただし、走らせられる中身は schema 上で enqueue_task / comment_pr / sync_with_root / resolve_conflicts_with_ai / merge_pr の 5 種類に限られているようでした。linterなど素のシェルも YAML で書けると、AI コール抑制によるコスト/速度面のメリットが取れて嬉しいかなと思いました。
宣伝
Legalscapeではエンジニア全方面で募集中です。さまざまなAIツールを用いた開発の効率化に興味がある方はぜひカジュアル面談などからご応募お願いします！
参考:
