takt-optimize（节拍优化）

TAKT Optimizer

既存のTAKTワークフローの最適化を実行する。診断・分析は takt-analyze が担う。

前提 takt バージョン: v0.30.0

参照資料

takt-analyzeとの違い

推奨フロー: takt-analyze（診断）→ その結果をもとに takt-optimize（最適化実行）

最適化カテゴリ

1. トークン消費削減

プロンプト構築時のトークン量を削減する。

エンジンのプロンプト構築順序（参照: engine.md）:

ペルソナ → ポリシー → コンテキスト → ナレッジ → インストラクション
→ タスク → 前回出力 → レポート指示 → タグ指示 → ポリシーリマインダー

注意: ポリシーは冒頭と末尾に2回注入される（Lost in the Middle対策）。ポリシーの肥大化はトークン消費を2倍にする。

ファセットサイズ目安:

2. ムーブメント統合

不要なムーブメントを統合してワークフロー全体のステップ数を減らす。

統合判断基準:

• ムーブメント間でペルソナが同じか異なるか
• session: refreshの境界を壊さないか
• レポート出力の独立性が必要か
• ルール分岐が実質的に意味を持つか

3. ルール簡素化

ルール条件の効率化を行う。

ai() vs タグベースの判断:

• タグベース（推奨）: 結果が明確に分類できる場合
• ai(): 判定に文脈理解が必要な場合のみ

4. ファセット再利用

カスタムファセットをビルトインで代替し、セクションマップを削減する。

手順:

1. セクションマップ内のカスタムファセットを列挙
2. 各カスタムファセットの内容を読み込む
3. ビルトインファセットと比較し、類似度を評価
4. 代替可能な場合はbare name参照に置換

ビルトイン置換例:

# Before: カスタムファセットをセクションマップで参照
personas:
  my-coder: ../personas/my-coder.md
movements:
  - name: implement
    persona: my-coder

# After: ビルトインのbare name参照
movements:
  - name: implement
    persona: coder    # ビルトインを直接参照

置換不可の条件:

• ビルトインにないドメイン知識を含むペルソナ
• プロジェクト固有の判定基準を含むポリシー
• 独自の手順を含むインストラクション

5. ループ制御改善

修正ループの効率化と安全性を改善する。

threshold推奨値:

• review→fix サイクル: 3回
• supervise→fix サイクル: 3回
• implement→test サイクル: 2回

6. 並列化提案

逐次実行されているが並列化可能なムーブメントを検出する。

並列化条件:

• 互いの出力を参照しない（pass_previous_response不要）
• 同じ前ムーブメントのレポートを入力とする
• 独立したレポートを出力する

# Before: 逐次レビュー
- name: arch-review
  ...
  rules:
    - condition: done
      next: qa-review
- name: qa-review
  ...

# After: 並列レビュー
- name: reviewers
  parallel:
    - name: arch-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
    - name: qa-review
      ...
      rules:
        - condition: approved
        - condition: needs_fix
  rules:
    - condition: all("approved")
      next: supervise
    - condition: any("needs_fix")
      next: fix

7. ログ診断結果に基づく最適化

takt-analyze のログ診断結果を入力として、実データに基づく最適化を実行する。

前提: ログの読み込み・解析・診断は takt-analyze が担当する。本カテゴリでは診断結果を受けて「何を変更するか」のみを扱う。

診断結果 → 最適化アクション:

ワークフロー

Step 1: 対象の特定と読み込み

対象のピースYAMLを特定し、関連ファセットを全て読み込む。

探索順序:
1. ユーザー指定のパス
2. ~/.takt/pieces/ 内のカスタムピース
3. .takt/pieces/ 内のプロジェクトピース

読み込む内容:

• ピースYAML全体
• セクションマップの全ファセットファイル
• ビルトインファセット（比較用）
• takt-analyze の診断レポート（提供された場合）

Step 2: 最適化プラン作成

各カテゴリの最適化可能性を評価し、プランを提示する。

# 最適化プラン: {ピース名}

## 分析ソース
- 静的分析: ピースYAML + ファセット{N}件
- takt-analyze診断: {診断レポートの要約}（提供された場合）

## 推定効果
- トークン削減: 約{N}%
- ムーブメント数: {before} → {after}
- ファイル数: {before} → {after}

## 最適化項目
| # | カテゴリ | 対象 | 内容 | 根拠 | リスク |
|---|---------|------|------|------|--------|
| 1 | トークン削減 | persona/coder | 120行→80行に圧縮 | 静的 | 低 |
| 2 | ビルトイン置換 | persona/my-reviewer | → architecture-reviewer | 静的 | 低 |
| 3 | ルール簡素化 | ai_review | ai_fallback 67% → タグ化 | 診断 | 低 |
| 4 | 並列化 | arch-review + qa-review | 逐次→並列 | 静的 | 中 |

ユーザーに確認: プランを提示し、実行する項目の承認を得る。

判定フロー:

• 最適化項目が0件 → 「既に十分最適化されています」を報告して終了
• ユーザーが一部承認 → 承認項目のみStep 3で実行
• ユーザーが全却下 → 終了

Step 3: 最適化の実行

承認された項目を実行する。

実行順序（依存関係順）:

1. ファセット圧縮・統合（ファイル内容の変更）
2. ビルトイン置換（セクションマップの変更）
3. ムーブメント統合（YAML構造の変更）
4. ルール簡素化（ルール条件の変更）
5. ループ制御改善（loop_monitors追加）
6. 並列化（ムーブメント構造の大幅変更）

Step 4: 整合性検証

最適化後のファイル群の整合性を確認する。

• セクションマップのキーとムーブメント内参照が一致
• セクションマップのパスが実在するファイルを指す
• initial_movementがmovements配列内に存在
• 全ルールのnextが有効な遷移先
• parallel親ルールがall()/any()を使用
• parallelサブステップのルールにnextがない
• ファセットがサイズ上限内
• 削除したファセットへの参照が残っていない

Step 5: 結果レポート

# 最適化結果: {ピース名}

## サマリー
- トークン削減: 約{N}%（推定）
- ムーブメント数: {before} → {after}
- ファイル数: {before} → {after}

## 変更一覧
| # | ファイル | 変更内容 |
|---|---------|---------|
| 1 | pieces/my-piece.yaml | ムーブメント統合、ルール簡素化 |
| 2 | personas/coder.md | 120行→80行に圧縮 |
| 3 | (削除) personas/my-reviewer.md | ビルトインに置換 |

## 削除ファイル
- personas/my-reviewer.md（→ ビルトイン architecture-reviewer で代替）

## 注意事項
{最適化による動作変更の可能性がある場合に記載}

バリデーション

作成・編集したファイルは validate-takt-files.sh で機械的に検証できる:

bash .agents/skills/takt-optimize/scripts/validate-takt-files.sh

検証項目:

• ピース YAML: 必須フィールド（name/initial_movement/movements）、initial_movement の movement 参照、ファセットファイル参照の実在
• ファセット.md: 空チェック、persona/policy/knowledge は # 見出し 必須、instruction/output-contract は内容存在

オプション --pieces / --facets で対象を絞り込み可能。