term-check

name	term-check
description	プロジェクトの用語一貫性チェック。diff・PR・実装計画に登場する用語(識別子・コメント・テストタイトル)を、リポジトリ別の用語集(glossary)と既存コードの語彙(inventory)に照らしてチェックし、新出概念の命名を確定して glossary を育てる。用語チェック・命名の相談・表記揺れの確認で発動。
argument-hint	[<PR番号> | plan <計画の説明・ファイル>]

term-check

ユーザー指示: $ARGUMENTS

リポジトリの用語(ドメイン用語・同義語・表記)の揺れを防ぐ。単一の 「term check」操作を、計画(実装前)と diff(実装後)のどちらにも適用する。

スクリプト: python3 <このスキルの base directory>/scripts/term_check.py <subcommand> (以下 term_check.py と表記)

データ(リポジトリごと。worktree 間で共有される):

• glossary.json — キュレーションされた用語集。全件 Read してよい
• inventory.json — 機械生成の全語彙。Read しない(大きい。スクリプト専用)

日本語の用語抽出は janome(形態素解析)がインストールされていれば自動で使い、 無ければ正規表現の近似にフォールバックする(python3 -m pip install janome で精度向上)。

チェック対象: 識別子(変数・関数・ファイル名)、コメント、テストタイトル。 チェック対象外: UI 文言、テストデータ内の文字列(スクリプトが文字列リテラルを 除外することで実現している)。

共通の準備

1. term_check.py paths で repo-id とデータの場所を確認(出力の dir: 行のディレクトリに glossary.json / inventory.json が置かれる。Read / Edit はこのパスで行う)
2. inventory を再生成する。diff チェックでは必ず --ref <base> を付ける (例: term_check.py inventory --ref origin/main)。--ref を省略すると 作業ツリーから抽出されるため、現在ブランチで追加した語彙が既存扱いになり 新出ワード判定から漏れる。base は「モード判定」で決めるデフォルトブランチを そのまま使う。計画チェックや単独利用では --ref 省略でよい(作業ツリー全体)。 大きいリポジトリでは数十秒。
3. glossary.json が存在すれば Read で全件読む。無ければ先に「初回ブートストラップ」

モード判定

• 引数が PR 番号 → diff チェック(gh pr diff <番号>)
• 引数なし → diff チェック(現在ブランチ: git diff <デフォルトブランチ>...HEAD)
  • デフォルトブランチは git symbolic-ref refs/remotes/origin/HEAD --short (origin/main 形式で返る)で特定する。失敗したら main / master の存在を 確認し、それでも不明ならユーザーに聞く
• 引数が plan ...、または会話の文脈が実装前の計画・設計 → 計画チェック

初回ブートストラップ(glossary が無いとき)

1. README・主要ディレクトリ名・コアモジュールの識別子から、このリポジトリの ドメイン用語(業務概念を表す語)を 10〜30 個拾う。気になる語は term_check.py lookup <語> で頻度と近い語を確認する
2. 日英ペア(term / ja)と、揺れそうな同義語(avoid / avoid_ja)を添えた 叩き台をユーザーに提示する
3. 承認された内容だけを glossary.json に書き込む

glossary.json のスキーマ(term / ja は片方だけでもよい。note は任意):

{
  "terms": [
    {
      "term": "fetch",
      "ja": "取得",
      "avoid": ["retrieve", "obtain"],
      "avoid_ja": [],
      "note": "外部 API からの取得。DB は find/get"
    }
  ]
}

diff チェック

1. diff をスクリプトに渡す:
   • 現在ブランチ: git diff <デフォルトブランチ>...HEAD | python3 .../term_check.py check
   • PR: gh pr diff <番号> | python3 .../term_check.py check
2. スクリプトのレポート(1 決定的違反 / 2 新出ワード / 2b 新出日本語フレーズ / 3 抽出サマリ)を読む。これは分析の入力であり、そのままユーザーに貼らない
3. 概念一貫性チェック(ここがあなたの仕事): 抽出サマリの識別子・コメント・ テストタイトル・日本語フレーズを概念ごとにクラスタリングし、検出する:
   • 同一概念に複数の日本語表現が使われている
   • 同一概念に複数の英語表現が使われている
   • 日英対応の不整合(日本語名から自然に導かれる英語名と識別子がずれている)
   • 定義なき新出概念(glossary に無く、inventory にも無い概念) 新出ワードは「既存語の同義語か(→既存語を提案)」「本当に新概念か (→glossary 登録を提案)」を判断する。文脈が足りなければ該当ファイルを Read する
4. 新出語の一般性チェック(ここもあなたの仕事): スクリプトが報告した 新出ワード(2)・新出日本語フレーズ(2b)の 全て について「日本で 一般的に通じる表現か」を検証する:
   • 自分の知識で判定できるものは判定する。確立した技術用語、辞書語、 業界で広く通用する表現は OK
   • 直訳調・造語・既存語の組み合わせで意味が変わっているものは NG とし、 一般的に通用する表現を代替案として提示する
   • 判定に迷うものは WebSearch で「<語> 意味」「<語> 技術用語」等を確認する
   • 例: 「壁時計」(wall clock time の直訳、エンジニア界でも使用率が低い) → 「現地時刻」「JST 表示時刻」など
   • 例: 「UTC エポック」(造語、技術文書で未定着) → 「Unix エポック」(POSIX 由来の確立した技術用語)
   • 一般性 OK な語は、概念として新規かどうかで glossary 登録の要否を別途判定する
5. 下記フォーマットで報告する
6. ユーザーが承認したエントリだけを glossary.json に追記する (Read してから Edit。JSON は日本語をエスケープせずそのまま、2 スペースインデント)

計画チェック

1. 計画(文書・会話)に登場する概念名・ファイル名・コンポーネント名を列挙する
2. 各名前を term_check.py lookup <語> [<語>...] で既存語彙と突き合わせる
3. 観点:
   • 既存概念に新しい名前を付けていないか(→ 既存語を使う)
   • 既存コードの語彙・命名慣習(動詞の選び方・ケース)に沿っているか
   • 日英ペアが決まっているか(コメント・テストタイトルで使う日本語名)
4. 概念ごとに「日本語名 / 英語名 / ファイル名・識別子の形」を提案し、 確定したものを glossary.json に登録する(ユーザー承認後)

報告フォーマット

スクリプト出力を以下の 3 セクションに整理して報告する(抽出サマリは分析の 入力なので報告に含めない。決定的違反はスクリプトの結果をそのまま使ってよい):

## 用語チェック結果

### 1. 決定的違反 (N件)
- `path:line` `retrieveUser` の retrieve → **fetch**(外部 API からの取得)

### 2. 概念揺れ (M件)
- 同一概念に「実長」「生テキスト」と `rawLength` が混在
  → **実効文字数 / EffectiveMessageLength** への統一を提案
  - 該当: path:line, path:line

### 3. 一般的でない新出語 (K件)
- 「壁時計」(×6) — wall clock time の直訳、エンジニア界でも使用率が低い
  → 推奨: 「現地時刻」「JST 表示時刻」「指定タイムゾーンの時刻」
- 「UTC エポック」(×1) — 造語、技術文書で未定着
  → 推奨: 「Unix エポック」(POSIX 由来の確立した技術用語)

### 4. 新出概念の登録提案
| term | ja | avoid | note |
| --- | --- | --- | --- |
| effective_message_length | 実効文字数 | raw_length | URL を固定長換算した文字数 |

問題がなければ「揺れなし」と簡潔に報告する。コードの修正は提案止まりとし、 ユーザーの指示があってから適用する。

glossary を育てるルール

• 登録するのは「ドメイン上の意味を持つ語」と「揺れが起きた・起きそうな語」だけ
• なんでも追記しない。目安 100〜200 エントリ
• 登録・変更は必ずユーザーの承認を得てから