TAKT Analyzer

既存のTAKTピースとファセットを分析し、問題点の検出と改善提案を行う。

前提 takt バージョン: v0.30.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/pieces/

構造パターンの参照

ビルトインファセット references/takt/builtins/ja/{personas,policies,instructions,knowledge,output-contracts}/

ファセット品質の参照

ログ型定義 references/takt/src/shared/utils/types.ts

NDJSONレコード型の参照

ルール評価 references/takt/src/core/piece/evaluation/RuleEvaluator.ts

matchedRuleMethod の仕組み

takt-optimize との違い

観点 takt-analyze takt-optimize

目的 問題検出・診断とレポート 最適化の実行

出力 分析レポート（Markdown） 最適化済みファイル群

変更 なし（読み取り専用） ファイルを直接編集・生成

入力 ピースYAML + ファセット + 実行ログ 同左

判断 問題の重大度分類 コスト/品質のトレードオフ判断

分析カテゴリ

1. ピース構造分析

ピースYAMLの構造的な問題を検出する。

チェック項目:

チェック 内容 重大度

initial_movement存在 initial_movement がmovements 配列内に存在するか Critical

遷移先の有効性 全rules.next が有効なムーブメント名 or COMPLETE /ABORT か Critical

loop健全遷移整合 loop_monitors.cycle の健全時 next が cycle 先頭ノードと一致するか Critical

loop参照レポート範囲 loop_monitors.judge.instruction_template の {report:...} が cycle 内 movement 生成物のみか 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

provider_options構造 allowed_tools が provider_options.claude.allowed_tools に配置されているか（v0.30.0〜） Warning

edit権限 edit: true のムーブメントに適切なrequired_permission_mode があるか Info

session設定 実装系ムーブメントにsession: refresh があるか Info

2. ファセット品質分析

各ファセットがスタイルガイドに準拠しているか確認する。

Persona チェック:

• ロール定義が1-2文

• 「やること」「やらないこと」に担当エージェント名

• ポリシーの詳細ルール（コード例・テーブル）が混入していない

• ピース固有の概念（ムーブメント名等）がない

• サイズ: simple 100行以内、expert 550行以内

以下のネストがない

Policy チェック:

• 目的説明が1文

• 原則テーブルが存在

• 特定エージェント固有の知識がない

• サイズ: 300行以内

Instruction チェック:

• 冒頭が命令形

• {task} , {previous_response} を手動記述していない

• ペルソナ/ポリシーの内容が混入していない

• サイズ: 種別に応じた上限内

Output Contract チェック:

コードブロックで囲まれている

• レビュー系にステータスと認知負荷軽減ルール

• ファイル名に番号プレフィックスがない

• サイズ: 30行以内

3. ファセット分離分析

ファセット間の責務が適切に分離されているか検出する。

違反パターン 説明 修正方向

ペルソナにポリシー詳細 コード例・テーブル付きのルールがペルソナ内に → ポリシーに移動

ペルソナにピース概念 ムーブメント名・レポートファイル名がペルソナ内に → インストラクションに移動

ポリシーに固有知識 特定エージェント固有の検出手法がポリシー内に → ペルソナのドメイン知識に移動

インストラクションに原則 共有コーディング原則がインストラクション内に → ポリシーに移動

出力契約に手順 実行手順が出力契約内に → インストラクションに移動

4. ルール設計分析

ルール条件の設計を評価する。

チェック 内容

タグ vs AI判定 タグベース条件で対応可能な箇所でai()を使用していないか

aggregate使用 parallelの親でall()/any()を使用しているか

到達不能ルール どの条件にも該当しないケースがないか

ループリスク fix→review等の循環にloop_monitorsがあるか

loop健全遷移 各 loop monitor で「健全（進捗あり）」の next が cycle 先頭ノードか

loopレポート整合 loop monitor が cycle 外 movement 専用レポートを参照していないか

ABORT条件 失敗時のABORT遷移が適切に定義されているか

5. ビルトイン活用分析

カスタムファセットがビルトインで代替可能か検出する。

手順:

• カスタムファセットの内容をビルトインファセットと比較

• 類似度が高い場合はビルトインへの置き換えを提案

• ビルトインのbare name参照とセクションマップ参照の混在を検出

6. ログベース診断分析

実行ログ（.takt/logs/*.jsonl ）を解析し、動的な問題を検出する。ログがない場合はスキップする。

a) ログの場所と形式

• .takt/logs/{sessionId}.jsonl （NDJSON形式: 1行1JSONオブジェクト）

• .takt/logs/latest.json で最新セッションIDを参照

NDJSONレコード型一覧:

type 内容

piece_start

ピース実行の開始

step_start

ムーブメント（ステップ）の開始

step_complete

ムーブメント完了（matchedRuleIndex , matchedRuleMethod を含む）

phase_start

フェーズの開始

phase_complete

フェーズ完了（error フィールドあり）

piece_complete

ピース実行の正常完了（iterations を含む）

piece_abort

ピース実行の中断（reason を含む）

interactive_start / interactive_end

インタラクティブモードの開始・終了

各レコード型の詳細フィールドは references/takt/src/shared/utils/types.ts を参照。

別ファイルのログ（v0.30.0〜）:

ファイル 形式 内容 設定

{sessionId}-provider-events.jsonl

NDJSON プロバイダAPIイベント（トークン数、レイテンシ等） logging.provider_events: true

trace.md

Markdown 実行トレースレポート（フェーズ・ムーブメント実行履歴） logging.trace: true

これらはセッションNDJSONとは別ファイルに出力される。設定は ~/.takt/config.yaml の logging セクションで制御する（v0.30.0 で observability → logging にリネーム）。

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 にタグ出力指示を追加すべき。

c) 診断分析項目

分析 方法 重大度判定基準

ループホットスポット 同一ステップの step_start 出現回数を集計 閾値超え=Warning、loop_monitor 未設定=Critical

デッドルール matchedRuleIndex の分布でマッチ0回のルールを検出 Critical（到達不能コード）

ルール評価効率 matchedRuleMethod の分布を集計。ai_judge_fallback の割合に注目

50%=Warning、>80%=Critical

ABORT率 piece_abort / piece_complete の比率

30%=Warning、>50%=Critical

フェーズ別エラー phase_complete の error フィールドを集計 同一フェーズで繰り返しエラー=Warning

イテレーション効率 piece_complete.iterations vs max_movements

常に上限近く=Warning

d) 複数ログの統合分析ガイド

• 3回以上: パターン確認に十分。統計的な傾向を報告する

• 1回: 参考情報として扱い、静的分析を優先する

e) ログ診断レポート例

ログ診断結果

分析対象

• セッション数: 5
• 期間: 2026-03-01 〜 2026-03-04

ルール評価効率

ループホットスポット

ABORT分析

• 成功: 4/5 (80%)
• ABORT: 1/5 (20%) - reason: "max_movements exceeded"

ワークフロー

Step 1: 対象の特定

分析対象のピースYAMLを特定し、実行ログの有無を確認する。

探索順序:

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

ログ確認:

• .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（改善提案）

ビルトイン活用の提案

{カスタムファセットのビルトイン置き換え提案}

ログ診断結果（ログ提供時のみ）

{ログベース診断のサマリー}