From purge-private-vocab
Use after generating PR description, Jira ticket, design doc, RFC, or other reader-facing text from a local plan/spec file, to detect and rewrite vocabulary that exists only in the source and would confuse readers without it. Triggers when output of /create-pr, Jira create, design doc draft, or similar derives from a local plan.
How this skill is triggered — by the user, by Claude, or both
Slash command
/purge-private-vocab:purge-private-vocabThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
ローカルプランファイル (`~/.claude/plans/**/*.md` 等) には設計時の思考効率を上げるため、自分用の造語・略号・番号ラベルが多用される。例: `Single Switch Principle`, `Provider 内吸収型`, `Critical-A/B/C/D`, `4 象限`, `α/β/γ 層`, `rollout enabler`, `AC-12`, `§設計詳細`。
ローカルプランファイル (~/.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 内造語を持ち込みがち。
主条件 (どれかに該当):
/create-pr 等のコマンド実行直後 (plan が source の場合)副条件:
When NOT to use:
検出した候補語を以下の 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 切れ |
重要: 本セクションは 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 の決定木で分類されるまで「要対応」と決めつけない。
~/.claude/plans/<topic>/plan.md 等両方を Read。
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>
各候補語を以下の決定木に上から順に当てはめる。最初にヒットした分岐で分類確定:
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 の判定基準 (重要、しばしば衝突する):
Single Switch: Single Switch Principle により ... は self-contained ではない)Label vs Body の機能分離 (重要、Q2 が partial になる典型ケース):
**plan-only ラベル**: 平易な説明文… の場合、ラベルと本文を独立に扱う:
**Single Switch**: Flipper の参照を 1 箇所に集約 → ラベルを **Flipper 参照の 1 箇所集約** に置換、本文は維持Q1 の判定基準:
git grep <語> | wc -l が 1+ ヒット (プロジェクトルートで実行)書き換え前に提案レポートを提示し承認を取る。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) の判定で見落としはないか?
「持ち込み可」セクションの記述方針:
承認後、Edit で target に修正を適用。
検証:
| 操作 | コマンド / パターン |
|---|---|
| カタカナ造語検出 | 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 定義形式 | <用語> (= <短い説明>) を初出箇所のみに |
症状: Freee::Client を「ライセンスクライアント」に言い換え。読者が grep できなくなり混乱が増す。
修正: class/file/Flipper flag 名は維持。読者は codebase で確認できる前提。
症状: Single Switch (Flipper 参照を 1 箇所に集約) を出現箇所 3 回すべてに付ける。文書が読みづらくなる。
修正: 定義は 初出 1 回のみ。2 回目以降は短縮形のまま使う。
症状: §設計詳細 を機械削除。直前の「§設計詳細 を参照」が「を参照」だけ残り文として壊れる。
修正: 番号ラベル / anchor を削除する場合は文単位で再構成する。参照元が target に無いなら、参照先の要点を 1 文でインライン化するか、文ごと削除。
症状: target にある「Single Switch」が plan 内造語か codebase 由来か判別できないまま「要言い換え」に分類してしまう。
修正: source plan path を最初に確認。直前の Claude Code session で plan を扱っていれば ~/.claude/plans/<topic>/plan.md を Read。無ければユーザに確認。
症状: 候補語をいきなり言い換え → 「この語は意図的に使った」と後で指摘される。
修正: 必ず提案レポートを先に提示し承認を取る。
実証例: 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 / command が ローカル plan を source とする対外文書を生成した直後に組み合わせると効果が高い:
/create-pr — plan から PR description を生成 → 本 skill で語彙点検/create-jira-issues — plan からチケット生成 → 本 skill で description を点検/finalize-plan — 計画完成後、対外公開する design doc に派生させる際/dry-ssot-text — 同一文書内の重複集約 (本 skill とは独立した別目的)npx claudepluginhub yasuakiomokawa/skills --plugin purge-private-vocabProvides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.