History

nrslib 897b63da8e docs: README・ガイドを現行アーキテクチャに合わせて全面修正

- expert-review → expert（実ファイル名に合わせる）
- ビルトインエージェント名を実ファイル名に統一
- Model Selectionをプロバイダー透過型に修正
- {report_dir}の例を.takt/reports/プレフィックス付きに更新
- {report:filename}テンプレート変数を追加
- gh CLIを#N用の条件付き要件として記載
- 日本語READMEにモデル選択・グローバル設定セクション追加
- docs/workflows.md: rules形式・パラレルステップに全面書き直し
- docs/agents.md: ルールベース自動注入・6エージェント構成に全面書き直し
- CHANGELOG.md: v0.3.0リリースノート追加

2026-01-30 21:44:12 +09:00

agents.md

docs: README・ガイドを現行アーキテクチャに合わせて全面修正

2026-01-30 21:44:12 +09:00

README.ja.md

docs: README・ガイドを現行アーキテクチャに合わせて全面修正

2026-01-30 21:44:12 +09:00

workflows.md

docs: README・ガイドを現行アーキテクチャに合わせて全面修正

2026-01-30 21:44:12 +09:00

README.ja.md

TAKT

Task Agent Koordination Tool - Claude CodeとOpenAI Codex向けのマルチエージェントオーケストレーションシステム

Note

: このプロジェクトは個人のペースで開発されています。詳細は免責事項をご覧ください。

必要条件

Claude Code または Codex がインストール・設定済みであること
GitHub CLI (gh) — takt "#N"（GitHub Issue実行）を使う場合のみ必要

TAKTはClaude CodeとCodexの両方をプロバイダーとしてサポートしています。セットアップ時にプロバイダーを選択できます。

インストール

npm install -g takt

クイックスタート

# タスクを実行（ワークフロー選択プロンプトが表示されます）
takt "ログイン機能を追加して"

# GitHub Issueをタスクとして実行
takt "#6"

# タスクをキューに追加
takt /add-task "ログインのバグを修正"

# 保留中のタスクをすべて実行
takt /run-tasks

# タスクを監視して自動実行
takt /watch

# タスクブランチ一覧（マージ・削除）
takt /list-tasks

# ワークフローを切り替え
takt /switch

タスク実行の流れ

takt "ログイン機能を追加して" を実行すると、以下の対話フローが表示されます:

1. ワークフロー選択

Select workflow:
  (↑↓ to move, Enter to select)

  ❯ default (current) (default)
    expert
    expert-cqrs
    magi
    research
    simple
    Cancel

2. 隔離クローン作成（オプション）

? Create worktree? (y/N)

y を選ぶと git clone --shared で隔離環境を作成し、作業ディレクトリをクリーンに保てます。

3. 実行 — 選択したワークフローが複数のエージェントを連携させてタスクを完了します。

ワークフロー	おすすめ用途
`default`	本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。
`simple`	README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。
`expert` / `expert-cqrs`	Web開発プロジェクト。修正ループ付き逐次マルチエキスパートレビュー（`expert`: アーキテクチャ、フロントエンド、セキュリティ、QA。`expert-cqrs`: CQRS+ES、フロントエンド、セキュリティ、QA）。
`research`	調査・リサーチ。質問せずに自律的にリサーチを実行。
`magi`	審議システム。3つのAIペルソナが分析・投票（エヴァンゲリオン風）。

コマンド一覧

コマンド	エイリアス	説明
`takt "タスク"`		現在のワークフローでタスクを実行（セッション自動継続）
`takt "#N"`		GitHub Issue #Nをタスクとして実行
`takt /run-tasks`	`/run`	`.takt/tasks/` の保留中タスクをすべて実行
`takt /watch`		`.takt/tasks/` を監視してタスクを自動実行（常駐プロセス）
`takt /add-task`	`/add`	新しいタスクを対話的に追加（YAML形式、複数行対応）
`takt /list-tasks`	`/list`	タスクブランチ一覧（マージ・削除）
`takt /switch`	`/sw`	ワークフローを対話的に切り替え
`takt /clear`		エージェントの会話セッションをクリア
`takt /eject`		ビルトインのワークフロー/エージェントを`~/.takt/`にコピーしてカスタマイズ
`takt /refresh-builtin`		ビルトインのエージェント/ワークフローを最新版に更新
`takt /config`		パーミッションモードを設定
`takt /help`		ヘルプを表示

ワークフロー

TAKTはYAMLベースのワークフロー定義とルールベースルーティングを使用します。ビルトインワークフローはパッケージに埋め込まれており、~/.takt/workflows/ のユーザーワークフローが優先されます。/eject でビルトインを~/.takt/にコピーしてカスタマイズできます。

ワークフローの例

name: default
max_iterations: 10
initial_step: plan

steps:
  - name: plan
    agent: ../agents/default/planner.md
    model: opus
    edit: false
    rules:
      - condition: 計画完了
        next: implement
    instruction_template: |
      リクエストを分析し、実装計画を作成してください。

  - name: implement
    agent: ../agents/default/coder.md
    edit: true
    permission_mode: acceptEdits
    rules:
      - condition: 実装完了
        next: review
      - condition: 進行不可
        next: ABORT
    instruction_template: |
      計画に基づいて実装してください。

  - name: review
    agent: ../agents/default/architecture-reviewer.md
    edit: false
    rules:
      - condition: 承認
        next: COMPLETE
      - condition: 修正が必要
        next: implement
    instruction_template: |
      アーキテクチャとコード品質の観点で実装をレビューしてください。

パラレルステップ

ステップ内でサブステップを並列実行し、集約条件で評価できます:

  - name: reviewers
    parallel:
      - name: arch-review
        agent: ../agents/default/architecture-reviewer.md
        rules:
          - condition: approved
          - condition: needs_fix
        instruction_template: |
          アーキテクチャとコード品質をレビューしてください。
      - name: security-review
        agent: ../agents/default/security-reviewer.md
        rules:
          - condition: approved
          - condition: needs_fix
        instruction_template: |
          セキュリティ脆弱性をレビューしてください。
    rules:
      - condition: all("approved")
        next: supervise
      - condition: any("needs_fix")
        next: fix

all("X"): すべてのサブステップが条件Xにマッチした場合にtrue
any("X"): いずれかのサブステップが条件Xにマッチした場合にtrue
サブステップの rules は可能な結果を定義しますが、next は省略可能（親が遷移を制御）

ルール条件の種類

種類	構文	説明
タグベース	`"条件テキスト"`	エージェントが `[STEP:N]` タグを出力し、インデックスでマッチ
AI判定	`ai("条件テキスト")`	AIが条件をエージェント出力に対して評価
集約	`all("X")` / `any("X")`	パラレルサブステップの結果を集約

ビルトインワークフロー

TAKTには複数のビルトインワークフローが同梱されています:

ワークフロー	説明
`default`	フル開発ワークフロー: 計画 → 実装 → AIレビュー → 並列レビュー（アーキテクト＋セキュリティ）→ スーパーバイザー承認。各レビュー段階に修正ループあり。
`simple`	defaultの簡略版: 計画 → 実装 → アーキテクトレビュー → AIレビュー → スーパーバイザー。中間の修正ステップなし。
`research`	リサーチワークフロー: プランナー → ディガー → スーパーバイザー。質問せずに自律的にリサーチを実行。
`expert`	ドメインエキスパートによる逐次レビュー: アーキテクチャ、フロントエンド、セキュリティ、QAレビューと修正ループ。
`expert-cqrs`	ドメインエキスパートによる逐次レビュー: CQRS+ES、フロントエンド、セキュリティ、QAレビューと修正ループ。
`magi`	エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。

takt /switch でワークフローを切り替えられます。

ビルトインエージェント

エージェント	説明
planner	タスク分析、仕様調査、実装計画
coder	機能の実装、バグ修正
ai-antipattern-reviewer	AI特有のアンチパターンレビュー（存在しないAPI、誤った仮定、スコープクリープ）
architecture-reviewer	アーキテクチャとコード品質のレビュー、仕様準拠の検証
security-reviewer	セキュリティ脆弱性の評価
supervisor	最終検証、バリデーション、承認

モデル選択

model フィールド（ワークフローステップ、エージェント設定、グローバル設定）はプロバイダー（Claude Code CLI / Codex SDK）にそのまま渡されます。TAKTはモデルエイリアスの解決を行いません。

Claude Code

Claude Code はエイリアス（opus、sonnet、haiku、opusplan、default）およびフルモデル名（例: claude-sonnet-4-5-20250929）をサポートしています。利用可能なモデルは Claude Code ドキュメントを参照してください。

Codex

モデル文字列はCodex SDKに渡されます。未指定の場合は codex がデフォルトです。利用可能なモデルはCodexのドキュメントを参照してください。

カスタムエージェント

.takt/agents.yamlでカスタムエージェントを定義:

agents:
  - name: my-reviewer
    prompt_file: .takt/prompts/reviewer.md
    allowed_tools: [Read, Glob, Grep]
    provider: claude             # オプション: claude または codex
    model: opus                  # Claude: opus/sonnet/haiku、Codex: gpt-5.2-codex 等

またはMarkdownファイルでエージェントプロンプトを作成:

# ~/.takt/agents/my-agents/reviewer.md

あなたはセキュリティに特化したコードレビュアーです。

## 役割
- セキュリティ脆弱性をチェック
- 入力バリデーションを検証
- 認証ロジックをレビュー

プロジェクト構造

~/.takt/
├── config.yaml          # グローバル設定（プロバイダー、モデル、ワークフロー等）
├── workflows/           # ユーザーワークフロー定義（ビルトインを上書き）
└── agents/              # ユーザーエージェントプロンプトファイル

.takt/                   # プロジェクトレベルの設定
├── agents.yaml          # カスタムエージェント定義
├── tasks/               # 保留中のタスクファイル（.yaml, .md）
├── completed/           # 完了したタスクとレポート
├── reports/             # 実行レポート（自動生成）
└── logs/                # NDJSON形式のセッションログ
    ├── latest.json      # 現在/最新セッションへのポインタ
    ├── previous.json    # 前回セッションへのポインタ
    └── {sessionId}.jsonl # ワークフロー実行ごとのNDJSONセッションログ

ビルトインリソースはnpmパッケージ（dist/resources/）に埋め込まれています。~/.takt/ のユーザーファイルが優先されます。

グローバル設定

デフォルトのプロバイダーとモデルを ~/.takt/config.yaml で設定:

# ~/.takt/config.yaml
language: ja
default_workflow: default
log_level: info
provider: claude         # デフォルトプロバイダー: claude または codex
model: sonnet            # デフォルトモデル（オプション）
trusted_directories:
  - /path/to/trusted/dir

モデル解決の優先順位:

ワークフローステップの model（最優先）
カスタムエージェントの model
グローバル設定の model
プロバイダーデフォルト（Claude: sonnet、Codex: codex）

実践的な使い方ガイド

タスク管理

TAKTは.takt/tasks/内のタスクファイルによるバッチ処理をサポートしています。.yaml/.ymlと.mdの両方のファイル形式に対応しています。

`/add-task` でタスクを追加

# クイック追加（隔離なし）
takt /add-task "認証機能を追加"

# GitHub Issueをタスクとして追加
takt /add-task "#6"

# 対話モード（隔離実行、ブランチ、ワークフローオプションを指定可能）
takt /add-task

タスクファイルの形式

YAML形式（推奨、worktree/branch/workflowオプション対応）:

# .takt/tasks/add-auth.yaml
task: "認証機能を追加する"
worktree: true                  # 隔離された共有クローンで実行
branch: "feat/add-auth"         # ブランチ名（省略時は自動生成）
workflow: "default"             # ワークフロー指定（省略時は現在のもの）

Markdown形式（シンプル、後方互換）:

# .takt/tasks/add-login-feature.md

アプリケーションにログイン機能を追加する。

要件:
- ユーザー名とパスワードフィールド
- フォームバリデーション
- 失敗時のエラーハンドリング

共有クローンによる隔離実行

YAMLタスクファイルでworktreeを指定すると、各タスクをgit clone --sharedで作成した隔離クローンで実行し、メインの作業ディレクトリをクリーンに保てます:

worktree: true - 隣接ディレクトリ（またはworktree_dir設定で指定した場所）に共有クローンを自動作成
worktree: "/path/to/dir" - 指定パスに作成
branch: "feat/xxx" - 指定ブランチを使用（省略時はtakt/{timestamp}-{slug}で自動生成）
worktree省略 - カレントディレクトリで実行（デフォルト）

Note

: YAMLフィールド名は後方互換のためworktreeのままです。内部的にはgit worktreeではなくgit clone --sharedを使用しています。git worktreeの.gitファイルにはgitdir:でメインリポジトリへのパスが記載されており、Claude Codeがそれを辿ってメインリポジトリをプロジェクトルートと認識してしまうためです。共有クローンは独立した.gitディレクトリを持つため、この問題が発生しません。

クローンは使い捨てです。タスク完了後に自動的にコミット＋プッシュし、クローンを削除します。ブランチが唯一の永続的な成果物です。takt /list-tasksでブランチの一覧表示・マージ・削除ができます。

`/run-tasks` でタスクを実行

takt /run-tasks

タスクはアルファベット順に実行されます（001-、002-のようなプレフィックスで順序を制御）
完了したタスクは実行レポートとともに.takt/completed/に移動されます
実行中に追加された新しいタスクも動的に取得されます

`/watch` でタスクを監視

takt /watch

ウォッチモードは.takt/tasks/をポーリングし、新しいタスクファイルが現れると自動実行します。Ctrl+Cで停止する常駐プロセスです。以下のような場合に便利です:

タスクファイルを生成するCI/CDパイプライン
外部プロセスがタスクを追加する自動化ワークフロー
タスクを順次キューイングする長時間の開発セッション

`/list-tasks` でタスクブランチを一覧表示

takt /list-tasks

takt/プレフィックスのブランチをファイル変更数とともに一覧表示します。各ブランチに対して以下の操作が可能です:

Try merge - mainにスカッシュマージ（変更をステージングのみ、コミットなし）
Instruct - 一時クローン経由で追加指示を与える
Merge & cleanup - マージしてブランチを削除
Delete - マージせずにブランチを削除

セッションログ

TAKTはセッションログをNDJSON（.jsonl）形式で.takt/logs/に書き込みます。各レコードはアトミックに追記されるため、プロセスが途中でクラッシュしても部分的なログが保持され、tail -fでリアルタイムに追跡できます。

.takt/logs/latest.json - 現在（または最新の）セッションへのポインタ
.takt/logs/previous.json - 前回セッションへのポインタ
.takt/logs/{sessionId}.jsonl - ワークフロー実行ごとのNDJSONセッションログ

レコード種別: workflow_start, step_start, step_complete, workflow_complete, workflow_abort

エージェントはprevious.jsonを読み取って前回の実行コンテキストを引き継ぐことができます。セッション継続は自動的に行われます — takt "タスク"を実行するだけで前回のセッションから続行されます。

カスタムワークフローの追加

~/.takt/workflows/にYAMLファイルを追加するか、/ejectでビルトインをカスタマイズします:

# defaultワークフローを~/.takt/workflows/にコピーして編集
takt /eject default

# ~/.takt/workflows/my-workflow.yaml
name: my-workflow
description: カスタムワークフロー
max_iterations: 5
initial_step: analyze

steps:
  - name: analyze
    agent: ~/.takt/agents/my-agents/analyzer.md
    edit: false
    rules:
      - condition: 分析完了
        next: implement
    instruction_template: |
      このリクエストを徹底的に分析してください。

  - name: implement
    agent: ~/.takt/agents/default/coder.md
    edit: true
    permission_mode: acceptEdits
    pass_previous_response: true
    rules:
      - condition: 完了
        next: COMPLETE
    instruction_template: |
      分析に基づいて実装してください。

Note

: {task}、{previous_response}、{user_inputs} は自動的にインストラクションに注入されます。テンプレート内での位置を制御したい場合のみ、明示的なプレースホルダーが必要です。

エージェントをパスで指定する

ワークフロー定義ではファイルパスを使ってエージェントを指定します:

# ワークフローファイルからの相対パス
agent: ../agents/default/coder.md

# ホームディレクトリ
agent: ~/.takt/agents/default/coder.md

# 絶対パス
agent: /path/to/custom/agent.md

ワークフロー変数

instruction_templateで使用可能な変数:

変数	説明
`{task}`	元のユーザーリクエスト（テンプレートになければ自動注入）
`{iteration}`	ワークフロー全体のターン数（実行された全ステップ数）
`{max_iterations}`	最大イテレーション数
`{step_iteration}`	ステップごとのイテレーション数（このステップが実行された回数）
`{previous_response}`	前のステップの出力（テンプレートになければ自動注入）
`{user_inputs}`	ワークフロー中の追加ユーザー入力（テンプレートになければ自動注入）
`{report_dir}`	レポートディレクトリパス（例: `.takt/reports/20250126-143052-task-summary`）
`{report:filename}`	`{report_dir}/filename` に展開（例: `{report:00-plan.md}`）

ワークフローの設計

各ワークフローステップに必要な要素:

1. エージェント - システムプロンプトを含むMarkdownファイル:

agent: ../agents/default/coder.md    # エージェントプロンプトファイルのパス
agent_name: coder                    # 表示名（オプション）

2. ルール - ステップから次のステップへのルーティングを定義。インストラクションビルダーがステータス出力ルールを自動注入するため、エージェントはどのタグを出力すべきか把握できます:

rules:
  - condition: "実装完了"
    next: review
  - condition: "進行不可"
    next: ABORT

特殊な next 値: COMPLETE（成功）、ABORT（失敗）

3. ステップオプション:

オプション	デフォルト	説明
`edit`	-	ステップがプロジェクトファイルを編集できるか（`true`/`false`）
`pass_previous_response`	`true`	前のステップの出力を`{previous_response}`に渡す
`allowed_tools`	-	エージェントが使用できるツール一覧（Read, Glob, Grep, Edit, Write, Bash等）
`provider`	-	このステップのプロバイダーを上書き（`claude`または`codex`）
`model`	-	このステップのモデルを上書き
`permission_mode`	`default`	パーミッションモード: `default`、`acceptEdits`、`bypassPermissions`
`report`	-	自動生成レポートのファイル設定（name, format）

API使用例

import { WorkflowEngine, loadWorkflow } from 'takt';  // npm install takt

const config = loadWorkflow('default');
if (!config) {
  throw new Error('Workflow not found');
}
const engine = new WorkflowEngine(config, process.cwd(), 'My task');

engine.on('step:complete', (step, response) => {
  console.log(`${step.name}: ${response.status}`);
});

await engine.run();

免責事項

このプロジェクトは個人プロジェクトであり、私自身のペースで開発されています。

レスポンス時間: イシューにすぐに対応できない場合があります
開発スタイル: このプロジェクトは主に「バイブコーディング」（AI支援開発）で開発されています - 自己責任でお使いください
プルリクエスト:
- 小さく焦点を絞ったPR（バグ修正、タイポ、ドキュメント）は歓迎します
- 大きなPR、特にAI生成の一括変更はレビューが困難です

詳細はCONTRIBUTING.mdをご覧ください。

Docker サポート

他の環境でのテスト用にDocker環境が提供されています:

# Dockerイメージをビルド
docker compose build

# コンテナでテストを実行
docker compose run --rm test

# コンテナでlintを実行
docker compose run --rm lint

# ビルドのみ（テストをスキップ）
docker compose run --rm build

これにより、クリーンなNode.js 20環境でプロジェクトが正しく動作することが保証されます。

ドキュメント

Workflow Guide - ワークフローの作成とカスタマイズ
Agent Guide - カスタムエージェントの設定
Changelog - バージョン履歴
Security Policy - 脆弱性報告
ブログ: TAKT - AIエージェントオーケストレーション - 設計思想と実践的な使い方ガイド

ライセンス

MIT - 詳細はLICENSEをご覧ください。

README.ja.md Unescape Escape

TAKT

必要条件

インストール

クイックスタート

タスク実行の流れ

おすすめワークフロー

コマンド一覧

ワークフロー

ワークフローの例

パラレルステップ

ルール条件の種類

ビルトインワークフロー

ビルトインエージェント

モデル選択

Claude Code

Codex

カスタムエージェント

プロジェクト構造

グローバル設定

実践的な使い方ガイド

タスク管理

/add-task でタスクを追加

タスクファイルの形式

共有クローンによる隔離実行

/run-tasks でタスクを実行

/watch でタスクを監視

/list-tasks でタスクブランチを一覧表示

セッションログ

カスタムワークフローの追加

エージェントをパスで指定する

ワークフロー変数

ワークフローの設計

API使用例

免責事項

Docker サポート

ドキュメント

ライセンス

README.ja.md

`/add-task` でタスクを追加

`/run-tasks` でタスクを実行

`/watch` でタスクを監視

`/list-tasks` でタスクブランチを一覧表示