| name | takt-analyzer |
| description | 既存のTAKTワークフローとファセットを分析し、改善提案を行うスキル。ワークフローYAMLの構造検証、 ファセット間の整合性チェック、スタイルガイド準拠の確認、未使用ファセットの検出、 ルール設計の最適化提案を実施する。実行ログ（.takt/logs/*.jsonl）が存在する場合は ログベース診断分析も行い、ルール評価効率・ループホットスポット・ABORT率等を報告する。 references/taktのスタイルガイド・エンジン仕様を基準として分析する。 トリガー：「ワークフローを分析」「taktの設定を確認」「ファセットの品質チェック」 「ワークフローのレビュー」「takt analyze」「ワークフローの改善提案」 「ワークフローの整合性チェック」「taktの問題を見つけて」 「ログを分析」「実行ログの診断」「taktのログを見て」「ルール評価の統計」 「ai_fallbackの頻度」「ループの検出」
|
TAKT Analyzer
既存のTAKTワークフローとファセットを分析し、問題点の検出と改善提案を行う。
前提 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 | ファセット品質基準 |
| ビルトインワークフロー | references/takt/builtins/ja/workflows/ | 構造パターンの参照 |
| ビルトインファセット | references/takt/builtins/ja/facets/{personas,policies,instructions,knowledge,output-contracts}/ | ファセット品質の参照 |
| ログ型定義 | references/takt/src/shared/utils/types.ts | NDJSONレコード型の参照 |
| プロバイダイベント | references/takt/src/core/logging/providerEventLogger.ts | *-provider-events.jsonl の構造 |
| 利用イベント | references/takt/src/core/logging/usageEventLogger.ts | 利用量イベントの構造 |
| span→NDJSONマッパー | references/takt/src/core/logging/span-to-ndjson-mapper.ts | OTel span 由来 shadow session log の構造（v0.44.0〜） |
| フェーズ利用イベント | references/takt/src/core/logging/phaseUsageEvent.ts | *-usage-events.phase.jsonl の PhaseUsageEventLogRecord 型（v0.45.0〜） |
| ルール評価 | references/takt/src/core/workflow/evaluation/RuleEvaluator.ts | matchedRuleMethod の仕組み（when: 決定論的条件含む） |
| トレース発見 | references/takt/src/core/workflow/observability/traceDiscovery.ts | OTel span から WorkflowTraceDiscovery（タスクメタデータ含む）を構築するモジュール（v0.47.0〜） |
takt-optimize との違い
| 観点 | takt-analyze | takt-optimize |
|---|
| 目的 | 問題検出・診断とレポート | 最適化の実行 |
| 出力 | 分析レポート（Markdown） | 最適化済みファイル群 |
| 変更 | なし（読み取り専用） | ファイルを直接編集・生成 |
| 入力 | ワークフローYAML + ファセット + 実行ログ | 同左 |
| 判断 | 問題の重大度分類 | コスト/品質のトレードオフ判断 |
分析カテゴリ
1. ワークフロー構造分析
ワークフローYAMLの構造的な問題を検出する。
チェック項目:
| チェック | 内容 | 重大度 |
|---|
| initial_step存在 | initial_stepがsteps配列内に存在するか | Critical |
| 遷移先の有効性 | 全rules.nextが有効なステップ名 or COMPLETE/ABORTか | Critical |
| loop健全遷移整合 | loop_monitors.cycle の健全時 next が cycle 先頭ノードと一致するか | Critical |
| loop参照レポート範囲 | loop_monitors.judge.instruction の {report:...} が cycle 内 step 生成物のみか | Critical |
| セクションマップ整合性 | セクションマップのキーとステップ内参照が一致するか | Critical |
| ファイルパス存在 | セクションマップのパスが実在するか | Critical |
| parallel構造 | 親ルールがall()/any()を使用、サブステップにnextがないか | Warning |
| edit=false + ビルド操作 | edit: false のステップのインストラクションがビルドコマンド（cargo check 等）の禁止を明示しているか。読み取り専用サンドボックスでビルドは Operation not permitted で失敗する | Warning |
| supervise失敗の遷移先 | supervise の失敗ルールが plan に遷移していないか。修正可能な問題は fix へ遷移すべきで、supervise → plan は根本設計変更が必要な場合のみ | Warning |
| CI実行の責任配置 | supervise/ai_review 等の edit: false ステップのインストラクションがCIの直接実行を禁止し、fix/implement のレポート証跡確認のみを求めているか | Warning |
| command quality gate | quality_gates の type: command が agent step にだけ置かれ、config 側で workflow_command_gates.custom_scripts: true が有効化されているか | Warning |
| provider_options構造 | allowed_tools がトップレベルではなく provider_options.claude.allowed_tools に配置されているか（v0.30.0〜） | Warning |
| provider_options.$ref 廃止 | provider_options.$ref を使用していないか（v0.47.0〜）。extends に移行が必要 | Warning |
| provider_routing 移行 | persona_providers を使用していないか（v0.47.0〜非推奨）。provider_routing（personas/tags/steps 軸）を使用すべき | Warning |
| edit権限 | edit: trueのステップに適切なrequired_permission_modeがあるか | Info |
| session設定 | 実装系ステップにsession: refreshがあるか | Info |
2. ファセット品質分析
各ファセットがスタイルガイドに準拠しているか確認する。
Persona チェック:
Policy チェック:
Instruction チェック:
Output Contract チェック:
3. ファセット分離分析
ファセット間の責務が適切に分離されているか検出する。
| 違反パターン | 説明 | 修正方向 |
|---|
| ペルソナにポリシー詳細 | コード例・テーブル付きのルールがペルソナ内に | → ポリシーに移動 |
| ペルソナにワークフロー概念 | ステップ名・レポートファイル名がペルソナ内に | → インストラクションに移動 |
| ポリシーに固有知識 | 特定エージェント固有の検出手法がポリシー内に | → ペルソナのドメイン知識に移動 |
| インストラクションに原則 | 共有コーディング原則がインストラクション内に | → ポリシーに移動 |
| 出力契約に手順 | 実行手順が出力契約内に | → インストラクションに移動 |
4. ルール設計分析
ルール条件の設計を評価する。
| チェック | 内容 |
|---|
| タグ vs AI判定 | タグベース条件で対応可能な箇所でai()を使用していないか |
| aggregate使用 | parallelの親でall()/any()を使用しているか |
| 到達不能ルール | どの条件にも該当しないケースがないか |
| ループリスク | fix→review等の循環にloop_monitorsがあるか |
| loop健全遷移 | 各 loop monitor で「健全（進捗あり）」の next が cycle 先頭ノードか |
| loopレポート整合 | loop monitor が cycle 外 step 専用レポートを参照していないか |
| ABORT条件 | 失敗時のABORT遷移が適切に定義されているか |
5. ビルトイン活用分析
カスタムファセットがビルトインで代替可能か検出する。
手順:
- カスタムファセットの内容をビルトインファセットと比較
- 類似度が高い場合はビルトインへの置き換えを提案
- ビルトインのbare name参照とセクションマップ参照の混在を検出
6. ログベース診断分析
実行ログ（.takt/logs/*.jsonl）を解析し、動的な問題を検出する。ログがない場合はスキップする。
a) ログの場所と形式
.takt/logs/{sessionId}.jsonl（NDJSON形式: 1行1JSONオブジェクト）.takt/logs/{sessionId}-provider-events.jsonl（プロバイダイベントログ、別ファイル）.takt/logs/{sessionId}/trace.md（トレースレポート、Markdown形式）.takt/logs/latest.json で最新セッションIDを参照
observability opt-in 出力（v0.44.0〜、observability.enabled: true が前提）:
.takt/runs/<run>/monitor.json: run 単位のワークフローメトリクス（observability.monitor: true で出力）- OTel span 由来の shadow session log（
observability.session_log_exporter: true で出力）。正規の NDJSON セッションログと同等の redaction が適用される
- span はフェーズ実行と status-judgment（judge）フェーズもカバーする
.takt/runs/<run>/logs/<session>-usage-events.phase.jsonl: フェーズ粒度の provider 利用量イベント（observability.usage_events_phase: true で出力、v0.45.0〜）。PhaseUsageEventLogRecord 型の NDJSON。各フェーズ（phase1_execute / phase2_report / phase3_structured / phase3_tag / phase3_fallback）ごとに provider, provider_model, step, step_type, phase, usage を記録する。npm run analyze:usage コマンドで集計可能
OTLP エクスポート（v0.46.0〜、observability.enabled: true + OTEL_EXPORTER_OTLP_ENDPOINT が前提）:
observability.enabled: true かつ OTEL_EXPORTER_OTLP_ENDPOINT 環境変数が設定されている場合、TAKT はローカル exporter を維持したまま span と metric を OTLP HTTP で送信するOTEL_EXPORTER_OTLP_TRACES_ENDPOINT / OTEL_EXPORTER_OTLP_METRICS_ENDPOINT で個別 endpoint を上書き可能（base endpoint が設定されている場合のみ有効）- 各プロバイダー subprocess に W3C trace context を伝播するため、provider CLI の span が親 workflow trace の下にネストされる（v0.46.0 以前は detached trace）
- 実行中 workflow を Grafana Tempo 等で発見しやすくする短命の
workflow_start.<workflowName> span を送信（takt.workflow.status = running 属性を持つ。root / step / phase / judge span の置き換えではなく discovery 専用）
- エクスポート実装の詳細は
references/takt/docs/observability.ja.md を参照
NDJSONレコード型一覧:
| type | 内容 |
|---|
workflow_start | ワークフロー実行の開始 |
step_start | ステップの開始 |
step_complete | ステップ完了（matchedRuleIndex, matchedRuleMethod を含む） |
phase_start | フェーズの開始 |
phase_complete | フェーズ完了（error フィールドあり） |
phase_judge_stage | ルール判定フェーズの段階記録（stage, method, status を含む） |
workflow_complete | ワークフロー実行の正常完了（iterations を含む） |
workflow_abort | ワークフロー実行の中断（reason を含む） |
interactive_start / interactive_end | インタラクティブモードの開始・終了 |
各レコード型の詳細フィールドは references/takt/src/shared/utils/types.ts を参照。
b) matchedRuleMethod
step_complete レコードの matchedRuleMethod は、ルール評価エンジンがどの手法でルールをマッチさせたかを示す。
評価順序（フォールバックチェーン）:
1. aggregate → all()/any() による並列サブステップ集約
2. phase3_tag → Phase 3 出力からのタグ検出
3. phase1_tag → Phase 1 出力からのタグ検出（フォールバック）
4. ai_judge → ai() 条件のみをAI判定
5. ai_judge_fallback → 全条件をAI判定（最終フォールバック）
手法別の特性:
| method | コスト | 信頼性 | 説明 |
|---|
aggregate | なし | 高 | 並列サブステップの完了状態で判定 |
phase3_tag | なし | 高 | 出力テンプレートのタグで確定的に判定 |
phase1_tag | なし | 中 | エージェント応答からタグ検出 |
ai_judge | API 1回 | 中 | ai() 条件のみをAI判定 |
ai_judge_fallback | API 1回 | 低 | 全条件をAI判定（タグ検出失敗時） |
auto_select | なし | 高 | ルールが1つのみの場合の自動選択 |
structured_output | なし | 高 | 構造化出力による判定 |
ai_judge_fallback の頻度が高い場合、output-contract にタグ出力指示を追加すべき。
step_start には providerOptions / providerOptionsSources も入るため、期待と異なる provider / effort 解決の原因分析に使える。
c) 診断分析項目
| 分析 | 方法 | 重大度判定基準 |
|---|
| ループホットスポット | 同一ステップの step_start 出現回数を集計 | 閾値超え=Warning、loop_monitor 未設定=Critical |
| デッドルール | matchedRuleIndex の分布でマッチ0回のルールを検出 | Critical（到達不能コード） |
| ルール評価効率 | matchedRuleMethod の分布を集計。ai_judge_fallback の割合に注目 | >50%=Warning、>80%=Critical |
| ABORT率 | workflow_abort / workflow_complete の比率 | >30%=Warning、>50%=Critical |
| フェーズ別エラー | phase_complete の error フィールドを集計 | 同一フェーズで繰り返しエラー=Warning |
| イテレーション効率 | workflow_complete.iterations vs max_steps | 常に上限近く=Warning |
d) 複数ログの統合分析ガイド
- 3回以上: パターン確認に十分。統計的な傾向を報告する
- 1回: 参考情報として扱い、静的分析を優先する
e) ログ診断レポート例
## ログ診断結果
### 分析対象
- セッション数: 5
- 期間: 2026-03-01 〜 2026-03-04
### ルール評価効率
| ステップ | phase3_tag | ai_judge | ai_judge_fallback | 改善優先度 |
|------------|-----------|---------|-------------------|----------|
| ai_review | 20% | 13% | 67% | 高 |
| supervise | 80% | 20% | 0% | - |
### ループホットスポット
| サイクル | 最大連続回数 | loop_monitor | 状態 |
|---------|------------|-------------|------|
| review→fix | 6 | threshold: 3 | OK |
| implement→test | 4 | なし | Warning: loop_monitor未設定 |
### ABORT分析
- 成功: 4/5 (80%)
- ABORT: 1/5 (20%) - reason: "max_steps exceeded"
ワークフロー
Step 1: 対象の特定
分析対象のワークフローYAMLを特定し、実行ログの有無を確認する。
探索順序:
1. ユーザー指定のパス
2. ~/.takt/workflows/ 内のカスタムワークフロー
3. .takt/workflows/ 内のプロジェクトワークフロー
ログ確認:
- .takt/logs/ ディレクトリの存在確認
- ログあり → 静的分析 + ログ診断
- ログなし → 静的分析のみ（従来通り）
Step 2: ワークフローYAML解析
ワークフローYAMLを読み込み、構造分析を実施する。
- YAML構文の検証
- ステップ構成の確認
- ルール条件の型チェック
- セクションマップの参照解決
Step 3: ファセット読み込みと品質チェック
セクションマップとビルトイン参照から全ファセットを読み込み、スタイルガイドに照合する。
Step 3.5: ログ読み込みと診断（ログがある場合のみ）
.takt/logs/latest.json から最新セッションIDを取得- 対象の
.jsonl ファイルを読み込み、NDJSONレコードを解析
- カテゴリ6の診断分析項目に従い、各指標を算出
- 複数ログがある場合は統合分析を実施
Step 4: 分離分析
ファセット間の責務侵犯を検出する。
Step 5: レポート出力
# TAKT分析レポート: {ワークフロー名}
## サマリー
- Critical: {N件}
- Warning: {N件}
- Info: {N件}
## Critical（必須修正）
| # | カテゴリ | 場所 | 問題 |
|---|---------|------|------|
## Warning（推奨修正）
| # | カテゴリ | 場所 | 問題 | 改善案 |
|---|---------|------|------|--------|
## Info（改善提案）
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|
## ビルトイン活用の提案
{カスタムファセットのビルトイン置き換え提案}
## ログ診断結果（ログ提供時のみ）
{ログベース診断のサマリー}
