telemetry-terminology-similarity

テレメトリ用語の類似度

3 つの独立したレイヤーにわたって、テレメトリのフィールド名のペアごとの類似度をスコアリングします。生のスコアを出力します。しきい値の設定、クラスタリング、意見の提示は行いません。利用する AI エージェントが独自にドメイン上の判断を適用します。

自己進化型スキル：このスキルは使用を重ねることで改善されます。指示が間違っている、パラメーターにずれが生じている、または回避策が必要だった場合は、先送りせず、すぐにこのファイルを修正してください。実際に再現できる問題がある場合にのみ更新してください。

このスキルを使用する場面

以下の場合にこのスキルを使用してください。

• テレメトリ／ロギングスキーマを監査し、名前の衝突を確認する
• 2 つの JSONL ログスキーマのフィールドの重複を比較する
• trace_id、traceId、request_id、correlation_id のような命名上の問題を検出する
• テレメトリの変更をリリースする前に、フィールド名の一貫性を検証する

アーキテクチャ

5 層のスコアリングパイプラインです。各レイヤーが、ほかのレイヤーでは見逃されるものを検出します。

┌─────────────────────────────────────────────────────────┐
│  Layer 1: NORMALIZE                                     │
│  camelCase/snake_case split + abbreviation expansion    │
│  wordninja for concatenated words                       │
│  "traceId" → "trace id", "ts" → "timestamp"            │
├─────────────────────────────────────────────────────────┤
│  Layer 2: SYNTACTIC (RapidFuzz, 0-100)                  │
│  token_set_ratio on normalized forms                    │
│  Catches: trace_id ↔ traceId, level ↔ log_level        │
├─────────────────────────────────────────────────────────┤
│  Layer 3: TAXONOMIC (WordNet Wu-Palmer, 0.0-1.0)        │
│  Head-noun synonym detection via hypernym tree          │
│  Catches: level ↔ severity, error ↔ fault, op ↔ action │
├─────────────────────────────────────────────────────────┤
│  Layer 4: SEMANTIC (sentence-transformers, 0.0-1.0)     │
│  Cosine similarity via all-MiniLM-L6-v2 embeddings     │
│  Catches: error ↔ exception, user_id ↔ account_id      │
├─────────────────────────────────────────────────────────┤
│  Layer 5: CANONICAL (--canonical flag, optional)        │
│  RapidFuzz vs bundled OTel/OCSF/CloudEvents dictionary  │
│  Catches: http_method → http.request.method (OTel)      │
├─────────────────────────────────────────────────────────┤
│  Output: All pairs scored + canonical anchors.          │
│  Agent decides what to act on — tool computes, judges.  │
│  Use proposer-prompt.md for structured rename proposals.│
└─────────────────────────────────────────────────────────┘

2 段階のワークフロー：スコアリング → 提案

このスキルは 2 段階で動作します。

1. フェーズ 1 — スコアリング（term_similarity.py）：5 層にわたって生の類似度スコアを計算します。ツールが計算を行い、意見は出力しません。
2. フェーズ 2 — 提案（references/proposer-prompt.md）：スコアリング結果の JSON を受け取り、信頼度レベル、根拠の引用、明示的な回避策を含む、構造化された名称変更案を LLM に作成させる、同梱のプロンプトテンプレートです。

この 2 つのフェーズは意図的に分離されています。フェーズ 1 は決定論的で再現可能です。フェーズ 2 では、会話のコンテキストを持つ LLM だけが提供できるドメイン上の判断を適用します。

依存関係

すべて uv run でインストールされます（PEP 723 のインラインメタデータを使用するため、グローバルへのインストールは不要です）。

パッケージ	用途	サイズ
sentence-transformers	セマンティック埋め込み（MiniLM-L6）	約 80 MB
rapidfuzz	高速なファジー文字列マッチング（C++）	約 1.3 MB
wordninja	確率的な単語分割	約 0.5 MB
nltk	WordNet の Wu-Palmer 同義語検出	約 30 MB
orjson	高速な JSON シリアライゼーション	約 0.3 MB

初回実行時に all-MiniLM-L6-v2 モデル（約 80 MB）と WordNet データ（約 30 MB）がダウンロードされます。

スクリプトの場所

分析スクリプトは、このスキルの references/ ディレクトリにあります。使用する前にパスを解決してください。

# SSoT-OK: marketplace path resolution for cross-repo invocation
SCRIPT_DIR="$(dirname "$(find ~/.claude/plugins -path '*/telemetry-terminology-similarity/references/term_similarity.py' -print -quit 2>/dev/null)")"
SCRIPT="$SCRIPT_DIR/term_similarity.py"

以下のすべての例では、$SCRIPT が設定されているものとします。cc-skills リポジトリ自体から実行する場合は、相対パスを直接使用してください。

使用方法

フィールド名を直接分析する

# SSoT-OK: uv run handles PEP 723 inline deps
uv run --python 3.14 "$SCRIPT" \
  trace_id traceId request_id correlation_id \
  level severity log_level priority

Python コードベースからフィールドを抽出する

Python の正規表現による抽出を使用します（macOS には grep -P がありません）。

python3 -c "
import re, glob
fields = set()
for f in glob.glob('**/*.py', recursive=True):
    text = open(f).read()
    for m in re.finditer(r'\"([a-z][a-z0-9_]*?)\":', text):
        fields.add(m.group(1))
for f in sorted(fields):
    print(f)
" | uv run --python 3.14 "$SCRIPT"

stdin から分析する（jq などからパイプする）

head -1 telemetry.jsonl | jq -r 'keys[]' | uv run --python 3.14 "$SCRIPT"

JSONL ファイルのフィールドを分析する

uv run --python 3.14 "$SCRIPT" --jsonl /path/to/telemetry.jsonl

2 つの JSON スキーマを比較する

uv run --python 3.14 "$SCRIPT" --schema-a schema_v1.json --schema-b schema_v2.json

出力サイズを調整する

uv run --python 3.14 "$SCRIPT" --top 30 field1 field2 field3   # Top 30 pairs
uv run --python 3.14 "$SCRIPT" --top 0 field1 field2 field3    # All pairs
uv run --python 3.14 "$SCRIPT" --json field1 field2 field3     # JSON output

正式な標準（OTel/OCSF/CloudEvents）と照合する

# Anchor each field against 1,453 bundled canonical names from OTel + OCSF + CloudEvents
uv run --python 3.14 "$SCRIPT" --canonical http_method http_status request_id severity

出力に === CANONICAL ANCHORS === セクションが追加され、各フィールドに最も近い標準名が示されます。「業界標準に合わせて名称を変更すべきか」を判断する際に役立ちます。

構造化された名称変更案を生成する（フェーズ 2）

--json --canonical を付けて実行した後、出力を references/proposer-prompt.md に貼り付けてください。これは、信頼度レベルと明示的な回避策を含む、レビュー可能で個別の名称変更案を生成する、同梱のプロンプトテンプレートです。

# Phase 1: Score
uv run --python 3.14 "$SCRIPT" --json --canonical [fields...] > analysis.json

# Phase 2: Apply proposer prompt (paste analysis.json into the template)
# The LLM produces structured proposals.json — review atomically

パラメーター

パラメーター	デフォルト	説明
--top	50	統合スコア上位 N 件のペアを表示します（0 = すべて）
--canonical	false	各フィールドを同梱の OTel/OCSF/CloudEvents 辞書と照合します
--jsonl	—	JSONL ファイルからフィールドを抽出します（すべての一意なキー）
--schema-a/-b	—	スキーマ間の比較（2 つの JSON スキーマファイル）
--json	false	テキストではなく、構造化 JSON として出力します

出力形式

テキスト出力（デフォルト）

Fields analyzed: 21
Unique after normalization: 19

=== EXACT DUPLICATES (after normalization) ===
  trace_id  ==  traceId
  timestamp  ==  ts

=== SCORED PAIRS (sorted by combined score) ===
    syn    tax    sem   comb  pair
    ---    ---    ---   ----  ----
  100.0  0.000  0.560  1.000  level                     <-> log_level
    0.0  1.000  0.472  1.000  error                     <-> fault
   66.7  0.909  0.457  0.909  operation                 <-> action
   46.2  0.833  0.251  0.833  level                     <-> severity
   28.6  0.667  0.700  0.700  error                     <-> exception

ペアごとに独立した 3 つのスコアが付与されます。エージェントは 3 つすべてを読み取って判断します。

• syn（構文）：高いほど、表面的な名前のバリエーションです
• tax（分類）：高いほど、WordNet の類義語です（上位語のツリー）
• sem（意味）：高いほど、埋め込みの類似度が高いです（分布に基づく）
• comb（統合）：max(syn/100, tax, sem) — 並べ替えのキー

JSON 出力（--json）

exact_duplicates と scored_pairs の配列を含む構造化 JSON です。

各レイヤーの寄与

シナリオ	syn	tax	sem	優位なレイヤー
trace_id vs traceId	100.0	0.0	1.0	構文
level vs severity	46.2	0.833	0.251	分類
error vs fault	0.0	1.000	0.472	分類
operation vs action	66.7	0.909	0.457	分類
error vs exception	28.6	0.667	0.700	意味
user_id vs account_id	47.1	0.0	0.792	意味

略語辞書

正規化処理では、一般的なテレメトリーの略語を展開します。

略語	展開後	略語	展開後
ts	タイムスタンプ	uid	ユーザー ID
req	リクエスト	resp	レスポンス
err	エラー	msg	メッセージ
svc	サービス	env	環境
op	操作	lvl	レベル
evt	イベント	ctx	コンテキスト
acct	アカウント	cfg	設定
dur	期間	lat	レイテンシ

term_similarity.py の ABBREVIATIONS を編集すると、ドメイン固有の略語を追加できます。

トラブルシューティング

問題	原因	解決策
ModuleNotFoundError	依存関係が不足しています	uv run を使用してください（PEP 723 により自動的に解決されます）
モデルのダウンロードが遅い	初回実行	初回ダウンロード後にキャッシュされます（合計約 110 MB）
別のリポジトリからスクリプトが見つからない	パスが解決されていません	スクリプトの場所セクションに従って $SCRIPT を設定してください
grep: invalid option -- P	macOS に PCRE がありません	代わりに python3 -c "import re..." パターンを使用してください

実行後の振り返り

このスキルの実行後、終了する前に次の点を確認してください。

1. コマンドは成功しましたか？ — 成功しなかった場合は、失敗の原因となった手順やエラーテーブルを修正してください。
2. パラメーターや出力に変更はありましたか？ — 基盤となるツールのインターフェイスに変更があった場合は、使用例とパラメーターテーブルを更新してください。
3. 回避策が必要でしたか？ — 異なるフラグや追加の手順など、即興の対応が必要だった場合は、次回の実行で同じ対応をせずに済むよう、この SKILL.md を更新してください。

問題が実際に発生し、再現可能な場合にのみ更新してください。推測に基づいて更新しないでください。