purge-private-vocab

Purge Private Vocabulary

Overview

ローカルプランファイル (~/.claude/plans/**/*.md 等) には設計時の思考効率を上げるため、自分用の造語・略号・番号ラベルが多用される。例: Single Switch Principle, Provider 内吸収型, Critical-A/B/C/D, 4 象限, α/β/γ 層, rollout enabler, AC-12, §設計詳細。

これらは plan 内では文脈があるため有効に機能するが、plan を読まない読者 (PR レビュワー / Jira watcher / design doc 閲覧者) がそのまま読まされると decode 不能で混乱する。

本 skill は、ローカル plan から派生した対外文書を点検し、ローカル固有語を「読者がそのまま理解できる表現」に書き換える。

核心原則: 「読者が source plan を持っていない前提で読み下せるか」。書き手 (AI 自身) が plan を読んだ状態で書くと、無意識に plan 内造語を持ち込みがち。

When to Use

主条件 (どれかに該当):

• ローカル plan ファイルから PR description / Jira / design doc / RFC / Slack / メール下書きを生成した直後
• /create-pr 等のコマンド実行直後 (plan が source の場合)
• 上記文書をレビューに出す直前

副条件:

• target 文書を読む人が plan ファイルにアクセスできない
• target 文書が plan を持たない第三者 (PSIRT, PdM, 外部監査) にも到達する

When NOT to use:

• target が plan そのもの (内部設計ノート、自分用メモ)
• target の読者全員が plan を読んでいる前提のチーム内資料
• API リファレンスなど語彙が codebase に直接マップされ、読者が grep で辿れる文書

Core Pattern: 3 分類判定

検出した候補語を以下の 3 分類に振り分ける:

分類	例	アクション	理由
持ち込み可	Flipper flag 名 (fy26q3_ebis_client)、class/file 名 (Freee::Client)、Jira ID (XPROJ-663)、Issue 番号 (#34074)	維持	codebase / 公開 issue tracker で grep 可能。読者が辿れる
要 in-line 定義	文書内で 2+ 回登場する有用な短縮形 (Single Switch, Provider 内吸収型)	初出箇所で 用語 (= 短い説明) を補う	略号として有用、定義 1 箇所追加で全箇所が読める
要言い換えまたは削除	1 回しか出ない造語、内部番号 (Critical-A, α/β/γ 層, AC-12)、section anchor (§設計詳細)	平易な日本語に書き換え、または文ごと削除	略す価値が無いか、参照先が target に無いため link 切れ

Detection Heuristics

重要: 本セクションは Step 2「候補抽出」専用。パターンにヒットした語は false positive を含む候補リスト。実際の分類は Step 3 の決定木で行う (heuristic ヒット ≠ 自動的に要対応)。

target 文書から以下のパターンを候補としてリストアップ:

パターン	候補例	typical false positive (Step 3 で「持ち込み可」に倒れやすい例)
カタカナ + 「型」「主義」「原則」「論」「系」	Provider 内吸収型, 短絡型, Critical-A/D 系	Faraday 系 (gem 名 + 系)、同期型/非同期型 (一般用語)
強調された (**...** / 「...」) 専門フレーズ	**Single Switch**, 「Provider 内吸収型」	強調された codebase 識別子、見出し用の強調
アルファベットラベル + 数字: [A-Z]+-[0-9a-z]+	Critical-A, AC-12, α 層 番号	XPROJ-663 (Jira ID)、AUTH-203 (Jira ID)、PR4-a 等 (target 内で全展開済なら OK)
ギリシャ文字 + 「層/相」: [α-ω]\s*層	α 層, β 層, γ 層	数学/物理文脈の正当な α/β 層
section anchor: §...	§設計詳細, §Single Switch	(基本 false positive なし、target 内に該当 section があれば OK)
フェーズ分類用語	rollout enabler, enabler	kill switch (英語圏で確立済)、feature flag 等
数字 + 「象限/層」	4 象限, 3 層 (文中で各要素が説明されていない場合)	OSI 7 層など公知の分類

heuristic ヒット後の方針: 列挙された語は全件 Step 3 へ渡す。Step 3 の決定木で分類されるまで「要対応」と決めつけない。

Workflow

1. 入力収集 (Collect)

• target: 検査対象の文書 (PR body、Jira description、design doc、RFC 等)。ファイルパス or インラインテキスト
• source plan: target の生成元。Claude Code session で plan を扱った直後なら ~/.claude/plans/<topic>/plan.md 等

両方を Read。

2. 候補抽出 (Extract candidates)

target 全文を読み、§Detection Heuristics の各パターンにマッチする語を列挙。

参考 grep 例:

# カタカナ造語パターン
grep -oE '[ァ-ヴー一-龥a-zA-Z]+(型|主義|原則|論|系)' <target>

# section anchor
grep -oE '§[^ ,。、）]+' <target>

# アルファベット + 番号ラベル
grep -oE '[A-Z][A-Za-z]*-[0-9a-z]+' <target>

3. 分類 (Classify) — 決定木

各候補語を以下の決定木に上から順に当てはめる。最初にヒットした分岐で分類確定:

Q1. codebase identifier / 公開規格名 / 公知の Jira/Issue ID か?
  YES → 【持ち込み可】 (例: Freee::Client, fy26q3_ebis_client, JWT, RFC 7519, XPROJ-663)
  NO  → Q2 へ

Q2. target 自身の中で**直近に定義/展開**されているか?
     (見出し直後の本文で挙動を平易に説明、bullet で全要素列挙、等)
  YES → 【持ち込み可 (target self-contained)】
  NO  → Q3 へ

Q3. source plan にしか定義がなく、target の読者は外部リソースで辿れないか?
  YES → Q4 へ (要対応)
  NO  → 【持ち込み可】 (公知用語など)

Q4. target 内の出現回数は?
  2+ 回 → 【要 in-line 定義】 (初出箇所で `用語 (= 短い説明)` を補う)
  1 回   → 【要言い換えまたは削除】 (平易な日本語に書き換え、または文ごと削除)

Q2 の判定基準 (重要、しばしば衝突する):

• 見出しラベル + 直後本文に意味が成立する平易な説明があれば self-contained と判定
• ただし「説明に plan 内造語がさらに混入」していれば NO (例: Single Switch: Single Switch Principle により ... は self-contained ではない)
• 迷ったら「plan を見たことが無い同僚に target だけ渡して読み下せるか」を音読で確認

Label vs Body の機能分離 (重要、Q2 が partial になる典型ケース):

• 構造が **plan-only ラベル**: 平易な説明文… の場合、ラベルと本文を独立に扱う:
  • ラベル: plan 内 navigation 用 → Q4 で「要言い換えまたは削除」(ラベルを平易表現に置き換え、または太字部を削除)
  • 本文: 既に reviewer 用に書かれている → そのまま維持
• これは Q2 を partial で抜ける default ルート。
• 例: **Single Switch**: Flipper の参照を 1 箇所に集約 → ラベルを **Flipper 参照の 1 箇所集約** に置換、本文は維持

Q1 の判定基準:

• codebase identifier: git grep <語> | wc -l が 1+ ヒット (プロジェクトルートで実行)
• 公開規格名: RFC/W3C/ISO/IETF 等で定義
• 公知の Issue/Jira ID: 公開 issue tracker でアクセス可能

4. 提案レポート (Dry-run)

書き換え前に提案レポートを提示し承認を取る。Step 3 の決定木の Q1–Q4 のどの分岐で分類されたかを併記すると、ユーザの誤検出疑念を減らせる:

## 語彙チェック提案レポート

### 持ち込み可 (維持) — Q1 / Q2 該当
- (Q1) `fy26q3_ebis_client` (Flipper flag 名、codebase 検索可)
- (Q1) `XPROJ-663` (Jira ID)
- (Q1) `Freee::Client` (class 名)
- (Q1) `JWT`, `RFC 7519` (公開規格名、heuristic 未ヒットだが reviewer 誤検出疑念回避のため明示)
- (Q2) `PR4-a/b/c/d` (target L12-L20 で全 PR が展開済 = target self-contained)

### 要 in-line 定義 (target 内 2+ 回出現) — Q4 該当
1. **Single Switch** (3 箇所: L14, L42, L58)
   - 提案: 初出 L14 を `Single Switch (= Flipper 参照を 1 箇所に閉じ込める設計)` に変更
2. **Provider 内吸収型** (2 箇所: L26, L44)
   - 提案: 初出 L26 を `Provider 内吸収型 (= OIDC nil を Provider 内で吸収し caller の挙動を変えない方式)` に変更

### 要言い換えまたは削除 (1 回出現または番号ラベル) — Q4 該当
1. `rollout enabler` (L18) → 「Flipper による本番経路切替を可能にする土台」に言い換え
2. `§設計詳細` (L33) → target には該当セクションなし、文ごと削除または該当内容をインライン化

### 確認ポイント
- in-line 定義の文言は妥当か？
- 持ち込み可リストに漏れはないか？
- Q2 (target self-contained) の判定で見落としはないか？

「持ち込み可」セクションの記述方針:

• heuristic ヒットして Q1/Q2 で持ち込み可になった語は全件明示 (false positive と判別したことを示す)
• heuristic 未ヒットだが reviewer が「これは plan 由来では?」と疑いそうな公開語 (JWT, RFC, Express 等) も列挙推奨 (誤検出疑念の事前回答)
• ファイルパス / メソッド名のような明らかな codebase identifier は省略可 (冗長になるため、代表例のみ)

5. 適用 (Apply)

承認後、Edit で target に修正を適用。

検証:

• in-line 定義を入れた語が target 内で初出箇所のみに定義があり、後続箇所はそのまま使われているか
• 削除した語の周辺文が文として成立しているか (主述破綻していないか)
• 要言い換えした箇所が、plan を見ない読者でも読み下せるか 再読

Quick Reference

操作	コマンド / パターン
カタカナ造語検出	grep -oE '[ァ-ヴー一-龥a-zA-Z]+(型|主義|原則|論|系)' <target>
section anchor 検出	grep -oE '§[^ ,。、）]+' <target>
番号ラベル検出	grep -oE '[A-Z][A-Za-z]*-[0-9a-z]+' <target>
候補語の出現回数	grep -c '<語>' <target>
codebase 検索 (持ち込み可判定)	git grep '<語>'
in-line 定義形式	<用語> (= <短い説明>) を初出箇所のみに

Common Mistakes

❌ 持ち込み可な codebase 固有名詞まで言い換えてしまう

症状: Freee::Client を「ライセンスクライアント」に言い換え。読者が grep できなくなり混乱が増す。

修正: class/file/Flipper flag 名は維持。読者は codebase で確認できる前提。

❌ in-line 定義を毎回繰り返して冗長化

症状: Single Switch (Flipper 参照を 1 箇所に集約) を出現箇所 3 回すべてに付ける。文書が読みづらくなる。

修正: 定義は 初出 1 回のみ。2 回目以降は短縮形のまま使う。

❌ 番号ラベル / section anchor の機械的削除

症状: §設計詳細 を機械削除。直前の「§設計詳細 を参照」が「を参照」だけ残り文として壊れる。

修正: 番号ラベル / anchor を削除する場合は文単位で再構成する。参照元が target に無いなら、参照先の要点を 1 文でインライン化するか、文ごと削除。

❌ source plan を未収集のまま target だけ点検

症状: target にある「Single Switch」が plan 内造語か codebase 由来か判別できないまま「要言い換え」に分類してしまう。

修正: source plan path を最初に確認。直前の Claude Code session で plan を扱っていれば ~/.claude/plans/<topic>/plan.md を Read。無ければユーザに確認。

❌ Dry-run なしで直接書き換え

症状: 候補語をいきなり言い換え → 「この語は意図的に使った」と後で指摘される。

修正: 必ず提案レポートを先に提示し承認を取る。

Real-World Impact

実証例: PR #39519 (Freee Sign の ebis 移行 PR4-b) を target に検査。

source: ~/.claude/plans/ebis/plan.md (365 行)、target: PR body (約 80 行)。

検出された plan 内造語と分類:

• Single Switch (target 1 箇所、太字ラベル形式、plan §Single Switch Principle 由来) → Q4: 1 回 → 要言い換え (Label vs Body 分離適用、ラベルを「Flipper 参照の 1 箇所集約」に置換、本文は維持)
• Provider 内吸収型 (target 1 箇所、太字ラベル形式、plan §Provider 内吸収型 由来) → Q4: 1 回 → 要言い換え (Label vs Body 分離適用、ラベルを「PublicApi 側で OIDC nil を吸収する戦略」に置換)
• rollout enabler (target 2 箇所、plan PR 進捗 table のフェーズ分類由来) → Q4: 2+ 回 → 要 in-line 定義 (初出箇所で (rollout enabler = Flipper による本番経路切替を可能にする土台 PR) を補う)

結果: plan 未読の PR レビュワーが PR body だけで設計判断を理解可能に。

併用推奨 skill

本 skill は以下の skill / command が ローカル plan を source とする対外文書を生成した直後に組み合わせると効果が高い:

• /create-pr — plan から PR description を生成 → 本 skill で語彙点検
• /create-jira-issues — plan からチケット生成 → 本 skill で description を点検
• /finalize-plan — 計画完成後、対外公開する design doc に派生させる際
• /dry-ssot-text — 同一文書内の重複集約 (本 skill とは独立した別目的)