| 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 文言、テストデータ内の文字列(スクリプトが文字列リテラルを
除外することで実現している)。
共通の準備
term_check.py paths で repo-id とデータの場所を確認(出力の dir: 行のディレクトリに glossary.json / inventory.json が置かれる。Read / Edit はこのパスで行う)- inventory を再生成する。diff チェックでは必ず
--ref <base> を付ける
(例: term_check.py inventory --ref origin/main)。--ref を省略すると
作業ツリーから抽出されるため、現在ブランチで追加した語彙が既存扱いになり
新出ワード判定から漏れる。base は「モード判定」で決めるデフォルトブランチを
そのまま使う。計画チェックや単独利用では --ref 省略でよい(作業ツリー全体)。
大きいリポジトリでは数十秒。
- 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 が無いとき)
- README・主要ディレクトリ名・コアモジュールの識別子から、このリポジトリの
ドメイン用語(業務概念を表す語)を 10〜30 個拾う。気になる語は
term_check.py lookup <語> で頻度と近い語を確認する
- 日英ペア(term / ja)と、揺れそうな同義語(avoid / avoid_ja)を添えた
叩き台をユーザーに提示する
- 承認された内容だけを glossary.json に書き込む
glossary.json のスキーマ(term / ja は片方だけでもよい。note は任意):
{
"terms": [
{
"term": "fetch",
"ja": "取得",
"avoid": ["retrieve", "obtain"],
"avoid_ja": [],
"note": "外部 API からの取得。DB は find/get"
}
]
}
diff チェック
- diff をスクリプトに渡す:
- 現在ブランチ:
git diff <デフォルトブランチ>...HEAD | python3 .../term_check.py check
- PR:
gh pr diff <番号> | python3 .../term_check.py check
- スクリプトのレポート(1 決定的違反 / 2 新出ワード / 2b 新出日本語フレーズ /
3 抽出サマリ)を読む。これは分析の入力であり、そのままユーザーに貼らない
- 概念一貫性チェック(ここがあなたの仕事): 抽出サマリの識別子・コメント・
テストタイトル・日本語フレーズを概念ごとにクラスタリングし、検出する:
- 同一概念に複数の日本語表現が使われている
- 同一概念に複数の英語表現が使われている
- 日英対応の不整合(日本語名から自然に導かれる英語名と識別子がずれている)
- 定義なき新出概念(glossary に無く、inventory にも無い概念)
新出ワードは「既存語の同義語か(→既存語を提案)」「本当に新概念か
(→glossary 登録を提案)」を判断する。文脈が足りなければ該当ファイルを Read する
- 新出語の一般性チェック(ここもあなたの仕事): スクリプトが報告した
新出ワード(2)・新出日本語フレーズ(2b)の 全て について「日本で
一般的に通じる表現か」を検証する:
- 自分の知識で判定できるものは判定する。確立した技術用語、辞書語、
業界で広く通用する表現は OK
- 直訳調・造語・既存語の組み合わせで意味が変わっているものは NG とし、
一般的に通用する表現を代替案として提示する
- 判定に迷うものは WebSearch で「<語> 意味」「<語> 技術用語」等を確認する
- 例: 「壁時計」(wall clock time の直訳、エンジニア界でも使用率が低い)
→ 「現地時刻」「JST 表示時刻」など
- 例: 「UTC エポック」(造語、技術文書で未定着) → 「Unix エポック」(POSIX
由来の確立した技術用語)
- 一般性 OK な語は、概念として新規かどうかで glossary 登録の要否を別途判定する
- 下記フォーマットで報告する
- ユーザーが承認したエントリだけを glossary.json に追記する
(Read してから Edit。JSON は日本語をエスケープせずそのまま、2 スペースインデント)
計画チェック
- 計画(文書・会話)に登場する概念名・ファイル名・コンポーネント名を列挙する
- 各名前を
term_check.py lookup <語> [<語>...] で既存語彙と突き合わせる
- 観点:
- 既存概念に新しい名前を付けていないか(→ 既存語を使う)
- 既存コードの語彙・命名慣習(動詞の選び方・ケース)に沿っているか
- 日英ペアが決まっているか(コメント・テストタイトルで使う日本語名)
- 概念ごとに「日本語名 / 英語名 / ファイル名・識別子の形」を提案し、
確定したものを 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 エントリ
- 登録・変更は必ずユーザーの承認を得てから
