takt-analyze（节拍分析）

TAKT Analyzer

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

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

参照資料

takt-optimize との違い

分析カテゴリ

1. ピース構造分析

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

チェック項目:

2. ファセット品質分析

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

Persona チェック:

• ロール定義が1-2文
• 「やること」「やらないこと」に担当エージェント名
• ポリシーの詳細ルール（コード例・テーブル）が混入していない
• ピース固有の概念（ムーブメント名等）がない
• サイズ: simple 100行以内、expert 550行以内
• ####以下のネストがない

Policy チェック:

• 目的説明が1文
• 原則テーブルが存在
• 特定エージェント固有の知識がない
• サイズ: 300行以内

Instruction チェック:

• 冒頭が命令形
• {task}, {previous_response}を手動記述していない
• ペルソナ/ポリシーの内容が混入していない
• サイズ: 種別に応じた上限内

Output Contract チェック:

• ``` `markdown ```コードブロックで囲まれている
• レビュー系にステータスと認知負荷軽減ルール
• ファイル名に番号プレフィックスがない
• サイズ: 30行以内

3. ファセット分離分析

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

4. ルール設計分析

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

5. ビルトイン活用分析

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

手順:

1. カスタムファセットの内容をビルトインファセットと比較
2. 類似度が高い場合はビルトインへの置き換えを提案
3. ビルトインのbare name参照とセクションマップ参照の混在を検出

6. ログベース診断分析

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

a) ログの場所と形式

• .takt/logs/{sessionId}.jsonl（NDJSON形式: 1行1JSONオブジェクト）
• .takt/logs/latest.json で最新セッションIDを参照

NDJSONレコード型一覧:

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

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

これらはセッション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判定（最終フォールバック）

手法別の特性:

ai_judge_fallback の頻度が高い場合、output-contract にタグ出力指示を追加すべき。

c) 診断分析項目

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_movements exceeded"

ワークフロー

Step 1: 対象の特定

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

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

ログ確認:
- .takt/logs/ ディレクトリの存在確認
- ログあり → 静的分析 + ログ診断
- ログなし → 静的分析のみ（従来通り）

Step 2: ピースYAML解析

ピースYAMLを読み込み、構造分析を実施する。

1. YAML構文の検証
2. ムーブメント構成の確認
3. ルール条件の型チェック
4. セクションマップの参照解決

Step 3: ファセット読み込みと品質チェック

セクションマップとビルトイン参照から全ファセットを読み込み、スタイルガイドに照合する。

Step 3.5: ログ読み込みと診断（ログがある場合のみ）

1. .takt/logs/latest.json から最新セッションIDを取得
2. 対象の .jsonl ファイルを読み込み、NDJSONレコードを解析
3. カテゴリ6の診断分析項目に従い、各指標を算出
4. 複数ログがある場合は統合分析を実施

Step 4: 分離分析

ファセット間の責務侵犯を検出する。

Step 5: レポート出力

# TAKT分析レポート: {ピース名}

## サマリー
- Critical: {N件}
- Warning: {N件}
- Info: {N件}

## Critical（必須修正）
| # | カテゴリ | 場所 | 問題 |
|---|---------|------|------|

## Warning（推奨修正）
| # | カテゴリ | 場所 | 問題 | 改善案 |
|---|---------|------|------|--------|

## Info（改善提案）
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|

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

## ログ診断結果（ログ提供時のみ）
{ログベース診断のサマリー}