agent-bot/takt
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

update ja

Browse Source
This commit is contained in:
nrslib 2026-01-30 21:01:38 +09:00
parent 4e7c3d0afb
commit e657211591
1 changed files with 226 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

394
docs/README.ja.md
View File

@ -22,6 +22,9 @@ npm install -g takt
# タスクを実行（ワークフロー選択プロンプトが表示されます）
takt "ログイン機能を追加して"
# GitHub Issueをタスクとして実行
takt "#6"
# タスクをキューに追加
takt /add-task "ログインのバグを修正"
@ -40,7 +43,7 @@ takt /switch
### タスク実行の流れ
`takt "ログイン機能を追加して"` を実行すると、以下の対話フローが表示されます：
`takt "ログイン機能を追加して"` を実行すると、以下の対話フローが表示されます:
**1. ワークフロー選択**
@ -71,7 +74,7 @@ Select workflow:
| ワークフロー | おすすめ用途 |
|------------|------------|
| `default` | 本格的な開発タスク。TAKT自身の開発で使用。修正ループ付きの多段階レビュー。 |
| `default` | 本格的な開発タスク。TAKT自身の開発で使用。アーキテクト＋セキュリティの並列レビュー付き多段階レビュー。 |
| `simple` | README更新や小さな修正などの軽量タスク。レビューはあるが修正ループなし。 |
| `expert-review` / `expert-cqrs` | Web開発プロジェクト。マルチエキスパートレビュー（CQRS、フロントエンド、セキュリティ、QA）。 |
| `research` | 調査・リサーチ。質問せずに自律的にリサーチを実行。 |
@ -82,16 +85,175 @@ Select workflow:
| コマンド | エイリアス | 説明 |
|---------|-----------|------|
| `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/`にコピーしてカスタマイズできます。
### ワークフローの例
```yaml
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: |
アーキテクチャとコード品質の観点で実装をレビューしてください。
```
### パラレルステップ
ステップ内でサブステップを並列実行し、集約条件で評価できます:
```yaml
- 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-review` | ドメインエキスパートによる包括的レビュー: CQRS+ES、フロントエンド、AI、セキュリティ、QAレビューと修正ループ。 |
| `expert-cqrs` | CQRS+ES、フロントエンド、AI、セキュリティ、QA専門のエキスパートレビュー。計画 → 実装 → マルチエキスパートレビュー → スーパーバイザー。 |
| `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 |
`takt /switch` でワークフローを切り替えられます。
## ビルトインエージェント
- **coder** - 機能を実装しバグを修正
- **architect** - アーキテクチャとコード品質をレビュー、仕様準拠を検証
- **supervisor** - 最終検証、バリデーション、承認
- **planner** - タスク分析、仕様調査、実装計画
- **ai-reviewer** - AI生成コードの品質レビュー
- **security** - セキュリティ脆弱性の評価
## カスタムエージェント
`.takt/agents.yaml`でカスタムエージェントを定義:
```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ファイルでエージェントプロンプトを作成:
```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/` のユーザーファイルが優先されます。
## 実践的な使い方ガイド
### タスク管理
@ -104,13 +266,16 @@ TAKTは`.takt/tasks/`内のタスクファイルによるバッチ処理をサ
# クイック追加（隔離なし）
takt /add-task "認証機能を追加"
# GitHub Issueをタスクとして追加
takt /add-task "#6"
# 対話モード（隔離実行、ブランチ、ワークフローオプションを指定可能）
takt /add-task
```
#### タスクファイルの形式
**YAML形式**（推奨、worktree/branch/workflowオプション対応）：
**YAML形式**（推奨、worktree/branch/workflowオプション対応）:
```yaml
# .takt/tasks/add-auth.yaml
@ -120,14 +285,14 @@ branch: "feat/add-auth" # ブランチ名（省略時は自動生成）
workflow: "default" # ワークフロー指定（省略時は現在のもの）
```
**Markdown形式**（シンプル、後方互換）：
**Markdown形式**（シンプル、後方互換）:
```markdown
# .takt/tasks/add-login-feature.md
アプリケーションにログイン機能を追加する。
要件：
要件:
- ユーザー名とパスワードフィールド
- フォームバリデーション
- 失敗時のエラーハンドリング
@ -135,7 +300,7 @@ workflow: "default" # ワークフロー指定（省略時は現在
#### 共有クローンによる隔離実行
YAMLタスクファイルで`worktree`を指定すると、各タスクを`git clone --shared`で作成した隔離クローンで実行し、メインの作業ディレクトリをクリーンに保てます：
YAMLタスクファイルで`worktree`を指定すると、各タスクを`git clone --shared`で作成した隔離クローンで実行し、メインの作業ディレクトリをクリーンに保てます:
- `worktree: true` - 隣接ディレクトリ（または`worktree_dir`設定で指定した場所）に共有クローンを自動作成
- `worktree: "/path/to/dir"` - 指定パスに作成
@ -162,7 +327,7 @@ takt /run-tasks
takt /watch
```
ウォッチモードは`.takt/tasks/`をポーリングし、新しいタスクファイルが現れると自動実行します。`Ctrl+C`で停止する常駐プロセスです。以下のような場合に便利です：
ウォッチモードは`.takt/tasks/`をポーリングし、新しいタスクファイルが現れると自動実行します。`Ctrl+C`で停止する常駐プロセスです。以下のような場合に便利です:
- タスクファイルを生成するCI/CDパイプライン
- 外部プロセスがタスクを追加する自動化ワークフロー
- タスクを順次キューイングする長時間の開発セッション
@ -173,7 +338,7 @@ takt /watch
takt /list-tasks
```
`takt/`プレフィックスのブランチをファイル変更数とともに一覧表示します。各ブランチに対して以下の操作が可能です：
`takt/`プレフィックスのブランチをファイル変更数とともに一覧表示します。各ブランチに対して以下の操作が可能です:
- **Try merge** - mainにスカッシュマージ（変更をステージングのみ、コミットなし）
- **Instruct** - 一時クローン経由で追加指示を与える
- **Merge & cleanup** - マージしてブランチを削除
@ -181,226 +346,119 @@ takt /list-tasks
### セッションログ
TAKTはセッションログを`.takt/logs/`にインクリメンタルに書き込みます。ログはワークフロー開始時、各ステップ完了後、ワークフロー終了時に保存されるため、プロセスが途中でクラッシュしても部分的なログが保持されます。
TAKTはセッションログをNDJSON（`.jsonl`）形式で`.takt/logs/`に書き込みます。各レコードはアトミックに追記されるため、プロセスが途中でクラッシュしても部分的なログが保持され、`tail -f`でリアルタイムに追跡できます。
- `.takt/logs/latest.json` - 現在（または最新の）セッションへのポインタ
- `.takt/logs/previous.json` - 前回セッションへのポインタ
- `.takt/logs/{sessionId}.json` - ワークフロー実行ごとの完全なセッションログ
- `.takt/logs/{sessionId}.jsonl` - ワークフロー実行ごとのNDJSONセッションログ
レコード種別: `workflow_start`, `step_start`, `step_complete`, `workflow_complete`, `workflow_abort`
エージェントは`previous.json`を読み取って前回の実行コンテキストを引き継ぐことができます。セッション継続は自動的に行われます — `takt "タスク"`を実行するだけで前回のセッションから続行されます。
### カスタムワークフローの追加
`~/.takt/workflows/`にYAMLファイルを追加して独自のワークフローを作成できます：
`~/.takt/workflows/`にYAMLファイルを追加するか、`/eject`でビルトインをカスタマイズします:
```bash
# defaultワークフローを~/.takt/workflows/にコピーして編集
takt /eject default
```
```yaml
# ~/.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: |
このリクエストを分析してください: {task}
transitions:
- condition: done
next_step: implement
このリクエストを徹底的に分析してください。
- name: implement
agent: ~/.takt/agents/default/coder.md
instruction_template: |
分析に基づいて実装してください: {previous_response}
edit: true
permission_mode: acceptEdits
pass_previous_response: true
transitions:
- condition: done
next_step: COMPLETE
rules:
- condition: 完了
next: COMPLETE
instruction_template: |
分析に基づいて実装してください。
```
> **Note**: `{task}`、`{previous_response}`、`{user_inputs}` は自動的にインストラクションに注入されます。テンプレート内での位置を制御したい場合のみ、明示的なプレースホルダーが必要です。
### エージェントをパスで指定する
ワークフロー定義ではファイルパスを使ってエージェントを指定します：
ワークフロー定義ではファイルパスを使ってエージェントを指定します:
```yaml
# ビルトインエージェントを使用
# ワークフローファイルからの相対パス
agent: ../agents/default/coder.md
# ホームディレクトリ
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ファイルとして作成：
```markdown
# ~/.takt/agents/my-agents/reviewer.md
あなたはセキュリティに特化したコードレビュアーです。
## 役割
- セキュリティ脆弱性をチェック
- 入力バリデーションを検証
- 認証ロジックをレビュー
## 出力形式
- [REVIEWER:APPROVE] コードが安全な場合
- [REVIEWER:REJECT] 問題が見つかった場合（問題点をリストアップ）
```
### ワークフロー変数
`instruction_template`で使用可能な変数：
`instruction_template`で使用可能な変数:
| 変数 | 説明 |
|------|------|
| `{task}` | 元のユーザーリクエスト |
| `{task}` | 元のユーザーリクエスト（テンプレートになければ自動注入） |
| `{iteration}` | ワークフロー全体のターン数（実行された全ステップ数） |
| `{max_iterations}` | 最大イテレーション数 |
| `{step_iteration}` | ステップごとのイテレーション数（このステップが実行された回数） |
| `{previous_response}` | 前のステップの出力（`pass_previous_response: true`が必要） |
| `{user_inputs}` | ワークフロー中の追加ユーザー入力 |
| `{report_dir}` | レポートディレクトリ名（例：`20250126-143052-task-summary`） |
| `{previous_response}` | 前のステップの出力（テンプレートになければ自動注入） |
| `{user_inputs}` | ワークフロー中の追加ユーザー入力（テンプレートになければ自動注入） |
| `{report_dir}` | レポートディレクトリ名（例: `20250126-143052-task-summary`） |
### ワークフローの設計
各ワークフローステップには3つの重要な要素が必要です。
各ワークフローステップに必要な要素:
**1. エージェント** - システムプロンプトを含むMarkdownファイル：
**1. エージェント** - システムプロンプトを含むMarkdownファイル:
```yaml
agent: ~/.takt/agents/default/coder.md # エージェントプロンプトファイルのパス
agent_name: coder # 表示名（オプション）
agent: ../agents/default/coder.md # エージェントプロンプトファイルのパス
agent_name: coder # 表示名（オプション）
```
**2. ステータスルール** - エージェントが完了を通知する方法を定義。エージェントは`[CODER:DONE]`や`[ARCHITECT:REJECT]`のようなステータスマーカーを出力し、TAKTがそれを検出して遷移を駆動します：
**2. ルール** - ステップから次のステップへのルーティングを定義。インストラクションビルダーがステータス出力ルールを自動注入するため、エージェントはどのタグを出力すべきか把握できます:
```yaml
status_rules_prompt: |
最終出力には必ずステータスタグを含めてください：
- `[CODER:DONE]` 実装が完了した場合
- `[CODER:BLOCKED]` 進行できない場合
rules:
- condition: "実装完了"
next: review
- condition: "進行不可"
next: ABORT
```
**3. 遷移** - ステータスに基づいて次のステップにルーティング：
特殊な `next` 値: `COMPLETE`（成功）、`ABORT`（失敗）
```yaml
transitions:
- condition: done # ステータスタグDONEに対応
next_step: review # reviewステップへ遷移
- condition: blocked # ステータスタグBLOCKEDに対応
next_step: ABORT # ワークフローを失敗終了
```
使用可能な遷移条件：`done`、`blocked`、`approved`、`rejected`、`improve`、`answer`、`always`
特殊なnext_step値：`COMPLETE`（成功）、`ABORT`（失敗）
**ステップオプション：**
**3. ステップオプション:**
| オプション | デフォルト | 説明 |
|-----------|-----------|------|
| `edit` | - | ステップがプロジェクトファイルを編集できるか（`true`/`false`） |
| `pass_previous_response` | `true` | 前のステップの出力を`{previous_response}`に渡す |
| `on_no_status` | - | ステータス未検出時の動作：`complete`、`continue`、`stay` |
| `allowed_tools` | - | エージェントが使用できるツール一覧（Read, Glob, Grep, Edit, Write, Bash等） |
| `provider` | - | このステップのプロバイダーを上書き（`claude`または`codex`） |
| `model` | - | このステップのモデルを上書き |
| `permission_mode` | `default` | パーミッションモード：`default`、`acceptEdits`、`bypassPermissions` |
## ワークフロー
TAKTはYAMLベースのワークフロー定義を使用します。以下に配置してください：
- `~/.takt/workflows/*.yaml`
### ワークフローの例
```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レビューと修正ループ。 |
| `expert-cqrs` | CQRS+ES、フロントエンド、AI、セキュリティ、QA専門のエキスパートレビュー。計画 → 実装 → マルチエキスパートレビュー → スーパーバイザー。 |
| `magi` | エヴァンゲリオンにインスパイアされた審議システム。3つのAIペルソナ（MELCHIOR、BALTHASAR、CASPER）が分析し投票。 |
`takt /switch` でワークフローを切り替えられます。
## ビルトインエージェント
- **coder** - 機能を実装しバグを修正
- **architect** - コードをレビューしフィードバックを提供
- **supervisor** - 最終検証と承認
- **planner** - タスク分析と実装計画
- **ai-reviewer** - AI生成コードの品質レビュー
- **security** - セキュリティ脆弱性の評価
## カスタムエージェント
`.takt/agents.yaml`でカスタムエージェントを定義：
```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/ # タスクブランチのメタデータ
├── worktree-sessions/ # クローンごとのエージェントセッション保存
├── reports/ # 実行レポート（自動生成）
└── logs/ # セッションログ（インクリメンタル）
├── latest.json # 現在/最新セッションへのポインタ
├── previous.json # 前回セッションへのポインタ
└── {sessionId}.json # ワークフロー実行ごとの完全なセッションログ
```
| `permission_mode` | `default` | パーミッションモード: `default`、`acceptEdits`、`bypassPermissions` |
| `report` | - | 自動生成レポートのファイル設定（name, format） |
## API使用例
@ -434,7 +492,7 @@ await engine.run();
## Docker サポート
他の環境でのテスト用にDocker環境が提供されています：
他の環境でのテスト用にDocker環境が提供されています:
```bash
# Dockerイメージをビルド
@ -458,7 +516,7 @@ docker compose run --rm build
- [Agent Guide](./agents.md) - カスタムエージェントの設定
- [Changelog](../CHANGELOG.md) - バージョン履歴
- [Security Policy](../SECURITY.md) - 脆弱性報告
- [ブログ：TAKT - AIエージェントオーケストレーション](https://zenn.dev/nrs/articles/c6842288a526d7) - 設計思想と実践的な使い方ガイド
- [ブログ: TAKT - AIエージェントオーケストレーション](https://zenn.dev/nrs/articles/c6842288a526d7) - 設計思想と実践的な使い方ガイド
## ライセンス