takt-analyzer
既存のTAKTワークフローとファセットを分析し、改善提案を行うスキル。ワークフローYAMLの構造検証、 ファセット間の整合性チェック、スタイルガイド準拠の確認、未使用ファセットの検出、 ルール設計の最適化提案を実施する。実行ログ(.takt/logs/*.jsonl)が存在する場合は ログベース診断分析も行い、ルール評価効率・ループホットスポット・ABORT率等を報告する。 references/taktのスタイルガイド・エンジン仕様を基準として分析する。 トリガー:「ワークフローを分析」「taktの設定を確認」「ファセットの品質チェック」 「ワークフローのレビュー」「takt analyze」「ワークフローの改善提案」 「ワークフローの整合性チェック」「taktの問題を見つけて」 「ログを分析」「実行ログの診断」「taktのログを見て」「ルール評価の統計」 「ai_fallbackの頻度」「ループの検出」
How do I install this agent skill?
npx skills add https://github.com/j5ik2o/ai-tools --skill takt-analyzerIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The takt-analyzer skill is a comprehensive development tool designed to analyze, validate, and optimize TAKT workflows and facets. It performs structural checks on YAML configurations, ensures compliance with established style guides, and can perform diagnostic analysis based on execution logs. The analysis found no evidence of malicious patterns, prompt injection, data exfiltration, or unauthorized code execution. The skill operates as a read-only diagnostic utility within the TAKT ecosystem.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
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 チェック:
- ロール定義が1-2文
- 「やること」「やらないこと」に担当エージェント名
- ポリシーの詳細ルール(コード例・テーブル)が混入していない
- ワークフロー固有の概念(ステップ名等)がない
- サイズ: simple 100行以内、expert 550行以内
-
####以下のネストがない
Policy チェック:
- 目的説明が1文
- 原則テーブルが存在
- 特定エージェント固有の知識がない
- サイズ: 300行以内
Instruction チェック:
- 冒頭が命令形
-
{task},{previous_response}を手動記述していない - ペルソナ/ポリシーの内容が混入していない
- サイズ: 種別に応じた上限内
Output Contract チェック:
-
```markdownコードブロックで囲まれている - レビュー系にステータスと認知負荷軽減ルール
- ファイル名に番号プレフィックスがない
- サイズ: 30行以内
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(改善提案)
| # | カテゴリ | 場所 | 提案 |
|---|---------|------|------|
## ビルトイン活用の提案
{カスタムファセットのビルトイン置き換え提案}
## ログ診断結果(ログ提供時のみ)
{ログベース診断のサマリー}
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/j5ik2o/ai-tools/takt-analyzer">View takt-analyzer on skillZs</a>