term-drift

English | 日本語

term-drift detects terminology introduced or distorted during AI-assisted development and helps keep project documents aligned with the project's ubiquitous language.

AI 支援開発を通じて持ち込まれたり、意味がずれたりした用語を見つけ、プロジェクトの文書をチームの共通語彙（ubiquitous language）に揃えるツールです。エージェント向けのスキルと、同じ入力なら同じ結果になる CLI を組み合わせています。書き換えは、人が確認した内容か、明示的に任された範囲でエージェントが低リスクと判断した内容に限ります。

Installation

必要なものは Node.js 18.17 以降と git だけです。対象プロジェクトのルートで、利用するエージェントに合わせてインストーラーを実行します。

# Claude Code（既定）
npx term-drift@latest

# 明示的に選ぶ場合
npx term-drift@latest --claude
npx term-drift@latest --codex
npx term-drift@latest --gemini

インストーラーは .term-drift/ と、選択したエージェント用のプロジェクトローカルなスキルを配置します。Gemini CLI 向けには、明示的に起動するための /term-drift コマンドも配置します。インストールした term-drift のバージョンは .term-drift/version.json に記録され、スキルは @latest ではなく、そのバージョンに固定した CLI を npx で実行します。対象プロジェクトの package.json、ロックファイル、node_modules は変更しません。

• Claude Code: .claude/skills/term-drift/
• Codex: .agents/skills/term-drift/
• Gemini CLI: .gemini/skills/term-drift/

Gemini CLI のコマンドは .gemini/commands/term-drift.toml に配置します。Gemini CLI がフォルダの信頼を確認した場合は、内容を確認して信頼すると、プロジェクトローカルなスキルとコマンドが読み込まれます。

既存の台帳やルール、同じ内容のスキルは上書きしません。同名のスキルでも内容が異なる場合は、勝手に置き換えず、インストールを完了せずに停止します。

すでに導入済みの環境を更新する場合は、利用中のエージェントを指定して更新コマンドを実行します。

npx term-drift@latest update --claude
npx term-drift@latest update --codex
npx term-drift@latest update --gemini

update は、公式配布版と一致することを確認できたルールとスキルだけをまとめて更新します。利用者が変更した可能性のあるファイルは上書きせずに停止し、途中で失敗した場合は変更を元に戻します。すべてのファイルを検証できた後にだけ .term-drift/version.json を更新するため、バージョン情報だけが新しく、ルールは古いままという状態を更新済みとして記録することはありません。

Quick start（推奨: スキルから使う）

インストール後、対象リポジトリで term-drift を起動します。Claude Code と Gemini CLI ではコマンドから起動できます。

/term-drift

Gemini CLI を起動したままインストールした場合は、/skills reload と /commands reload を実行してから /term-drift を使います。/skills list でスキルが認識されていることを確認できます。

Codex では、次のように依頼できます。Gemini CLI でも自然文による起動が可能です。

term-drift で用語を点検して

通常は、利用者が term-drift init /path/to/repository を組み立てて実行する必要はありません。インストーラーが台帳、ルール、スキルの配置先を決め、必要なファイルをすべて検証した後にだけインストール完了を表示します。

term-drift 自身は LLM API を呼びません。文意の読み取りと、明示的に任された範囲での低リスクな判断は、利用者が選んだエージェントが担います。重要な判断と台帳の変更は人が行い、走査、適用、再検査は同じ入力なら同じ結果になる CLI が処理します。

候補を単語の一覧として扱うことはしません。全出現を個別に読み、意味と修正内容が同じ箇所だけをグループにまとめます。標準のガイド方式では、対象となるすべてのファイルと行、引用、置き換え後の文を人が確認します。利用者がリポジトリ、現在のレビュー、特定の語など、明確な範囲をエージェントに任せた場合は、エージェントが低リスクな箇所を判断して進めます。意味を確定できない箇所、重要な選択肢がある箇所、義務の強さや法務、セキュリティ、公開 API、実行時の挙動に関わる箇所は、人に確認します。範囲を限定しない一任は勧めていません。どちらの方式でも、全出現の個別確認と適用箇所の記録は省略しません。

レビューの途中で「造語チェックの続き」と依頼すると、スキルは会話と承認済みの記録から決定済みの内容を復元します。操作手順を聞き直さず、全出現の確認を済ませたうえで、次の未決グループから再開します。一般語として承認した語は、台帳の任意の「分類」列に、状態「承認済み」・分類「一般語」と記録できます。この記録があれば、別のセッションで同じ分類を聞き直しません。ただし、記録されるのは語の分類だけです。一般語をプロジェクト固有の意味で使っている箇所や、曖昧な文章は引き続き確認します。再開位置を記録から確定できない場合に限り、復元できた内容と不足している情報を短く示し、どこから再開するかを確認します。

CLI はスキルから呼び出される実行部分です。開発やデバッグ、ほかのエージェントとの連携で直接使う場合は、下記の「コマンド」を参照してください。

基本的な流れ

1. 走査 — 対象リポジトリの文書を読み取り専用で集める（コミットメッセージと計画文書を優先し、秘密ファイルは集めない）
2. 検出 — 台帳にない造語だけでなく、一般的な言葉をプロジェクト固有の意味で使っている例（「配線」型の比喩）も候補に挙げる
3. 3分類 — 一般語／チーム共通語（台帳に承認済みで載る語）／未承認の独自用語の疑いに仕分ける。迷う語はすみやかに利用者へ確認する
4. 引用つき言い換え提案 — 実際の使用箇所を引用し、台帳の言い換え例を根拠に置き換え語と置き換え後の文を提案する
5. 内容の確認 — 通常は、人が意味の同じグループごとに確認する。明示的に任された範囲では、エージェントが低リスクな箇所を判断し、高リスクな箇所だけを人に確認する
6. 書き換えの適用 — 決定済みの置換だけを、同じ入力なら同じ結果になる処理でファイルへ適用する（git 管理下でのみ行い、元に戻せる）
7. 再検査 — 適用後に検出を再実行し、指摘ゼロ（または理由を添えた例外のみ）へ収束させる

安全上の原則

• 人が承認したか、明示的に任された範囲で低リスクと判断した置換だけを書き込む
• 実行時に外部サービスへ通信しない
• 秘密ファイル（.env・鍵・認証情報）を走査対象にしない
• 判断に迷う語は黙って処理せず、すみやかに利用者へ確認する

コマンド

term-drift
term-drift --claude | --codex | --gemini
term-drift update --claude|--codex|--gemini [dir]
term-drift init [dir]
term-drift scan [dir]
term-drift ledger [dir]
term-drift apply <dictionary.json> [dir]
term-drift recheck <dictionary.json> [dir]
term-drift rules [dir]

引数なしのコマンドと 3 つのエージェント指定オプションは、現在のディレクトリにプロジェクトローカルな環境をインストールします。そのほかのサブコマンドはスキルから呼び出される処理で、開発やデバッグ、別の仕組みとの連携にも直接利用できます。

apply は、決定済みの項目だけを、指定された相対パス内の一意な 1 箇所へ適用します。新しい形式では、誰の判断で変更するかも検証します。適用結果には、変更箇所ごとの from、to、decisionSource、decidedAt、delegationScope が含まれます。パスのない辞書や、1 つの項目が複数箇所に一致する辞書は、書き込む前に拒否します。対象は git で追跡されている UTF-8 文書です。ステージされていない変更があっても、現在の内容に from が一意に一致すれば、ほかの差分を残したまま適用し、warningsDirty と標準エラー出力で警告します。未追跡や非 UTF-8 のファイル、曖昧な一致、重なる置換、コードやリンク先など保護対象の変更は、拒否するかスキップします。

誰の判断で変更したかを後から確認できる、新しい辞書形式の最小例です。

{
  "decision_metadata_version": 1,
  "replacements": [
    { "term": "結線", "term_occurrences": 1, "path": "docs/setup.md", "from": "接続を結線して完了する。", "to": "接続をつなぎ込んで完了する。", "approved": true, "decision_source": "human-approved", "decided_at": "2026-07-16", "delegation_scope": null }
  ]
}

decision_source は、人が個別に承認した場合は human-approved、明示的に任された範囲でエージェントが低リスクと判断した場合は delegated-agent です。後者では、任せた範囲を delegation_scope に記録します。以前の形式の辞書も適用できますが、その変更は decisionSource: legacy-unknown と報告されます。適用に使った辞書を .term-drift/ 配下に残しておけば、本文にマーカーを埋め込まなくても、誰の判断で変更したかを追跡できます。

Documentation

• 理論的背景（English）— なぜ台帳、多層検出、判断した人の記録、再現可能な適用処理が必要なのか
• 検出 rules — 多層検出・3分類・除外条件
• 点検の進め方 — 走査から再検査までの手順

Status

walking skeleton 完了。安全境界と検出精度を継続して改善中。

実在する 2 つのリポジトリを対象範囲を限定して検証したところ、検出可能だった 24 件のうち 17 件（約 71%）を検出できました。完全な自動分類器ではなく、人が確認する候補を挙げるための検査手順です。

License

MIT