takt-optimizer

TAKT 优化器

对现有 TAKT 工作流执行优化。诊断和分析由 takt-analyze 负责。

前提 takt 版本：v0.47.0

参考资料

资料	路径	用途
YAML 架构	references/takt/builtins/skill/references/yaml-schema.md	工作流结构的验证标准
引擎规范	references/takt/builtins/skill/references/engine.md	理解提示词构建和令牌消耗
风格指南集	references/takt/builtins/ja/*_STYLE_GUIDE.md	Facet 大小上限
内置工作流	references/takt/builtins/ja/workflows/	参考优化模式
内置 Facet	references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/	内置替换候选项

与 takt-analyze 的区别

方面	takt-analyze	takt-optimize
目的	检测问题、诊断并生成报告	执行优化
输出	分析报告（Markdown）	优化后的文件集
更改	无（只读）	直接编辑和生成文件
输入	工作流 YAML + Facet + 执行日志	工作流 YAML + Facet + takt-analyze 的诊断结果
判断	对问题进行严重程度分类	判断成本与质量之间的权衡
日志分析	自行分析并生成诊断报告	利用 takt-analyze 的诊断结果

建议流程：takt-analyze（诊断）→ 根据结果使用 takt-optimize（执行优化）

优化类别

1. 降低令牌消耗

减少构建提示词时的令牌数量。

引擎的提示词构建顺序（参考：engine.md）：

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

注意：策略会在开头和结尾各注入一次，共两次（用于应对 Lost in the Middle）。策略膨胀会使令牌消耗翻倍。

优化	方法	效果
Persona 压缩	删除冗余描述，压缩到大小上限以内	每个步骤均可减少
策略拆分	按用途拆分大型策略，仅分配给必要步骤	双倍效果（包括提醒部分）
精简知识	移除步骤不需要的知识引用	减少不必要的上下文
简化指令	移除对自动注入内容的手动描述	消除重复内容
精简输出契约	压缩超过 30 行的输出契约	减少报告指令部分的内容

Facet 大小参考：

Facet	建议	上限
Persona (simple)	30-50 行	100 行
Persona (expert)	50-300 行	550 行
Policy	60-250 行	300 行
Instruction (review)	5-12 行	-
Instruction (plan/fix)	10-20 行	-
Instruction (implement)	30-50 行	-
Output Contract	10-25 行	30 行

2. 合并步骤

合并不必要的步骤，减少整个工作流的步骤数。

模式	检测条件	优化
连续使用相同 Persona	相邻步骤使用相同 Persona	合并为一个步骤
单一规则转换	只有一条规则，且为无条件转换	考虑与前后步骤合并
edit=false 连锁	连续出现只读步骤	评估是否可以合并

合并判断标准：

• 步骤之间使用的 Persona 是否相同
• 是否会破坏 session: refresh 边界
• 是否需要独立的报告输出
• 规则分支是否具有实际意义

3. 简化规则

提高规则条件的效率。

优化	Before	After
将 ai() 替换为标签	ai("実装が完了した")	"実装完了"（基于标签）
移除不可达规则	3 个条件中有 1 个不可达	删除不可达规则
缩短条件文本	"全てのレビュアーが承認した"	"approved"

ai() 与基于标签的判断：

• 基于标签（推荐）：结果可以明确分类时
• ai()：仅在判断需要理解上下文时使用

4. 重用 Facet

用内置 Facet 替代自定义 Facet，以精简 section map。

步骤：

1. 列出 section map 中的自定义 Facet
2. 读取每个自定义 Facet 的内容
3. 与内置 Facet 比较并评估相似度
4. 如果可以替代，则改为引用 bare name

内置替换示例：

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

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

不可替换的情况：

• Persona 包含内置 Facet 中没有的领域知识
• Policy 包含项目专属的判断标准
• Instruction 包含自定义步骤

5. ループ制御改善

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

最適化	内容
loop_monitors追加	review→fixサイクルにloop_monitorがない場合に追加
threshold調整	閾値が高すぎる/低すぎる場合に適正値を提案
ABORT条件追加	失敗時のABORT遷移がない場合に追加
max_steps調整	ステップ数に対してmax_stepsが過大/過小な場合に調整
supervise失敗遷移の修正	supervise 失敗時に plan へ遷移するルールを fix に変更する。supervise → plan ループは高コストで非生産的になりやすい
edit=false ビルド禁止の追記	edit: false のステップが参照するインストラクションに「ビルドコマンドを実行しないこと」の禁止セクション（## やらないこと）を追加する
loop monitor judge の instruction 正規化	loop_monitors.judge.instruction をビルトインファセット参照（loop-monitor-ai-antipattern-fix, loop-monitor-reviewers-fix）へ統一し、旧 judge テンプレート記法を除去する
allowed_tools の provider_options 移行	トップレベルの allowed_tools を provider_options.claude.allowed_tools に移動する（v0.30.0〜）
command quality gate の整理	文字列 gate と type: command gate を分け、command gate は agent step に限定する。不要な command gate は削除し、必要な場合は config 側の許可設定を確認する
provider_options.$ref → extends 移行	ワークフロー内の provider_options.$ref: provider-options/edit.yaml を provider_options.extends: edit に書き換える（v0.47.0〜 BREAKING: 旧 $ref は無効）
persona_providers → provider_routing 移行	ワークフロー内の persona_providers: を削除し、プロジェクト/グローバル設定の provider_routing.personas（または provider_routing.tags/provider_routing.steps）に移行する（v0.47.0〜非推奨）

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 が担当する。本カテゴリでは診断結果を受けて「何を変更するか」のみを扱う。

利用可能なログソース:

ログファイル	粒度	用途
logs/<session>.jsonl	step 単位	ループ検出、ルール評価効率、ABORT率
logs/<session>-provider-events.jsonl	provider 呼び出し単位	各呼び出しの token 消費
logs/<session>-usage-events.phase.jsonl	phase 単位（v0.45.0〜）	step × phase × provider のトークン消費。observability.usage_events_phase: true で出力。npm run analyze:usage で集計可能
OTLP span / metric（v0.46.0〜）	span / metric 単位	OTEL_EXPORTER_OTLP_ENDPOINT 設定時に Grafana Tempo 等へ送信。provider span が workflow trace にネストされるため、step ↔ provider 呼び出しの対応をトレースビューで確認可能

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

takt-analyze の診断	最適化アクション
ループホットスポット（Warning/Critical）	loop_monitor の threshold 調整、ルール条件の見直し
デッドルール（Critical）	到達不能ルールの除去
ルール評価効率が低い（ai_judge_fallback 高頻度）	タグベースルールへの書き換え、output-contract にタグ出力指示を追加
ABORT率が高い	ABORT原因の reason に応じたフロー改善（max_steps 調整、ABORT条件の追加）
フェーズ別エラーの繰り返し	エラー頻発フェーズのインストラクション・ペルソナの改善
イテレーション効率が低い	max_steps の適正値算出、ステップ統合の検討

ワークフロー

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

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

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

読み込む内容:

• ワークフロー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_stepがsteps配列内に存在
• 全ルールのnextが有効な遷移先
• parallel親ルールがall()/any()を使用
• parallelサブステップのルールにnextがない
• ファセットがサイズ上限内
• 削除したファセットへの参照が残っていない

Step 5: 結果レポート

# 最適化結果: {ワークフロー名}

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

## 変更一覧
| # | ファイル | 変更内容 |
|---|---------|---------|
| 1 | workflows/my-workflow.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_step/steps）、initial_step の step 参照、ファセットファイル参照の実在
• ファセット .md: 空チェック、persona/policy/knowledge は # 見出し 必須、instruction/output-contract は内容存在

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