agent-bot/takt

Fork 0

nrslib 63d6932c01 Stop using git worktree due to Claude Code SDK working at repository root

2026-01-29 11:24:47 +09:00

16 KiB

Raw Blame History

TAKT

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

Note

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

必要条件

Claude Code または Codex がインストール・設定済みであること

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

インストール

npm install -g takt

クイックスタート

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

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

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

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

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

コマンド一覧

コマンド	説明
`takt "タスク"`	現在のワークフローでタスクを実行（セッション継続）
`takt -r "タスク"`	前回のセッションを再開してタスクを実行
`takt /run-tasks`	`.takt/tasks/` の保留中タスクをすべて実行
`takt /watch`	`.takt/tasks/` を監視してタスクを自動実行（常駐プロセス）
`takt /add-task`	新しいタスクを対話的に追加（YAML形式）
`takt /switch`	ワークフローを対話的に切り替え
`takt /clear`	エージェントの会話セッションをクリア
`takt /refresh-builtin`	ビルトインのエージェント/ワークフローを最新版に更新
`takt /config`	現在の設定を表示
`takt /help`	ヘルプを表示

実践的な使い方ガイド

`-r` でセッションを再開する

TAKTの実行中にエージェントから追加の情報を求められた場合（例：「詳細を教えてください」）、-rフラグを使って会話を継続できます：

# 最初の実行 - エージェントが確認を求めることがある
takt "ログインのバグを直して"

# 同じセッションを再開して要求された情報を提供
takt -r "パスワードに特殊文字が含まれているとバグが発生します"

-rフラグはエージェントの会話履歴を保持し、自然なやり取りを可能にします。

タスク管理

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

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

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

# 対話モード（隔離実行、ブランチ、ワークフローオプションを指定可能）
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 /review-tasksでブランチのレビュー・マージ・削除ができます。

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

takt /run-tasks

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

`/watch` でタスクを監視

takt /watch

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

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

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

~/.takt/workflows/にYAMLファイルを追加して独自のワークフローを作成できます：

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

max_iterations: 5

steps:
  - name: analyze
    agent: ~/.takt/agents/my-agents/analyzer.md
    instruction_template: |
      このリクエストを分析してください: {task}
    transitions:
      - condition: done
        next_step: implement

  - name: implement
    agent: ~/.takt/agents/default/coder.md
    instruction_template: |
      分析に基づいて実装してください: {previous_response}
    pass_previous_response: true
    transitions:
      - condition: done
        next_step: COMPLETE

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

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

# ビルトインエージェントを使用
agent: ~/.takt/agents/default/coder.md
agent: ~/.takt/agents/magi/melchior.md

# プロジェクトローカルのエージェントを使用
agent: ./.takt/agents/my-reviewer.md

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

カスタムエージェントプロンプトをMarkdownファイルとして作成：

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

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

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

## 出力形式
- [REVIEWER:APPROVE] コードが安全な場合
- [REVIEWER:REJECT] 問題が見つかった場合（問題点をリストアップ）

ワークフロー変数

instruction_templateで使用可能な変数：

変数	説明
`{task}`	元のユーザーリクエスト
`{iteration}`	ワークフロー全体のターン数（実行された全ステップ数）
`{max_iterations}`	最大イテレーション数
`{step_iteration}`	ステップごとのイテレーション数（このステップが実行された回数）
`{previous_response}`	前のステップの出力（`pass_previous_response: true`が必要）
`{user_inputs}`	ワークフロー中の追加ユーザー入力
`{git_diff}`	現在のgit diff（コミットされていない変更）
`{report_dir}`	レポートディレクトリ名（例：`20250126-143052-task-summary`）

ワークフローの設計

各ワークフローステップには3つの重要な要素が必要です。

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

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

2. ステータスルール - エージェントが完了を通知する方法を定義。エージェントは[CODER:DONE]や[ARCHITECT:REJECT]のようなステータスマーカーを出力し、TAKTがそれを検出して遷移を駆動します：

status_rules_prompt: |
  最終出力には必ずステータスタグを含めてください：
  - `[CODER:DONE]` 実装が完了した場合
  - `[CODER:BLOCKED]` 進行できない場合

3. 遷移 - ステータスに基づいて次のステップにルーティング：

transitions:
  - condition: done        # ステータスタグDONEに対応
    next_step: review      # reviewステップへ遷移
  - condition: blocked     # ステータスタグBLOCKEDに対応
    next_step: ABORT       # ワークフローを失敗終了

使用可能な遷移条件：done、blocked、approved、rejected、improve、always 特殊なnext_step値：COMPLETE（成功）、ABORT（失敗）

ステップオプション：

オプション	デフォルト	説明
`pass_previous_response`	`true`	前のステップの出力を`{previous_response}`に渡す
`on_no_status`	-	ステータス未検出時の動作：`complete`、`continue`、`stay`
`allowed_tools`	-	エージェントが使用できるツール一覧（Read, Glob, Grep, Edit, Write, Bash等）
`provider`	-	このステップのプロバイダーを上書き（`claude`または`codex`）
`model`	-	このステップのモデルを上書き

ワークフロー

TAKTはYAMLベースのワークフロー定義を使用します。以下に配置してください：

~/.takt/workflows/*.yaml

ワークフローの例

name: default
max_iterations: 10

steps:
  - name: implement
    agent: coder
    instruction_template: |
      {task}
    transitions:
      - condition: done
        next_step: review
      - condition: blocked
        next_step: ABORT

  - name: review
    agent: architect
    transitions:
      - condition: approved
        next_step: COMPLETE
      - condition: rejected
        next_step: implement

ビルトインワークフロー

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

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

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

ビルトインエージェント

coder - 機能を実装しバグを修正
architect - コードをレビューしフィードバックを提供
supervisor - 最終検証と承認
planner - タスク分析と実装計画
ai-reviewer - AI生成コードの品質レビュー
security - セキュリティ脆弱性の評価

カスタムエージェント

.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 等
    status_patterns:
      approved: "\\[APPROVE\\]"
      rejected: "\\[REJECT\\]"

プロジェクト構造

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

.takt/                   # プロジェクトレベルの設定
├── agents.yaml          # カスタムエージェント定義
├── tasks/               # 保留中のタスクファイル（.yaml, .md）
├── completed/           # 完了したタスクとレポート
├── worktree-meta/       # タスクブランチのメタデータ
├── reports/             # 実行レポート（自動生成）
└── logs/                # セッションログ

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をご覧ください。

16 KiB Raw Blame History Unescape Escape