タグサジェスト

作成2026年4月27日Takeshi Takatsudo

ローカル LLM がプロジェクトのボキャブラリから最大3つの正規タグを提案するオプトイン機能。

自動ではなくオプトイン

pnpm tags:suggestは開発者向けのヘルパーであり、ビルドの一部ではありません。1つ以上のドキュメントファイルを読み、ローカルで動いている LLM にプロジェクトボキャブラリから最大3つのタグ id を提案させ、対話プロンプトで表示するか、バッチレビュー用に JSON Lines ファイルへ追記します。

このツールには意図的な3つの選択があります。

ローカルモデル、クラウドなし。 プロンプトとドキュメント本文はマシンから出ません。
ボキャブラリ対応。 tag-vocabulary.ts全体をコンテキストとしてモデルに渡すため、提案は常に正規セットから出てきます。
CI では動かさない。 提案はあくまで参考情報です。pnpm b4push、pnpm build、プリコミットフックのいずれにも組み込まれていません。

より厳密な強制が欲しい場合は、<code>tagGovernance: "strict"</code>と<code>pnpm tags:audit</code>の役割です。

Ollama のセットアップ

サジェスターはローカルで動くOllamaデーモンと HTTP で通信します。

ollama.comから Ollama をインストールします。
モデルを pull します。
```
ollama pull qwen2.5:7b
```
デーモンがhttp://localhost:11434(デフォルト)で接続できることを確認します。

デフォルトのモデルはqwen2.5:7bで、品質・速度・ディスク占有量(約5 GB)のバランスが取れています。--modelで上書きできます。

pnpm tags:suggest --model llama3.1:8b src/content/docs/guides/i18n.mdx

軽量モデル(qwen2.5:3b、llama3.2:3b)は高速ですがノイジーです。デーモンに接続できない、あるいは使えない出力が返ってきた場合、ツールは非ゼロ終了します。

対話フロー

デフォルト(TTY)フローは1ファイルずつレビューします。

pnpm tags:suggest src/content/docs/guides/deployment.mdx

サジェスターは現在のタグ、LLM の提案した id、そして y/n の確認プロンプトを表示します。受諾するとファイルのフロントマターに書き戻され、拒否すると捨てられます。これが通常の執筆で使うフローです。

バッチフロー

規模の大きなジョブや非 TTY 環境(CI、エディタプラグイン、パイプした stdin)では--batchを渡します。

pnpm tags:suggest --batch src/content/docs/guides/*.mdx

提案はリポジトリルートの.tag-suggestions.jsonlへ追記されます——ファイルごとにfile・current・suggestedを含む JSON オブジェクトが1行です。ドキュメントファイル自体は書き換えられません。JSONL を確認し、良さそうなものを手で適用(あるいはスクリプトで処理)したら、終わったらファイルを削除します。

--batchは stdout が TTY でないときにも自動で有効になるため、パイプやリダイレクトでログファイルに流しても意図通りに動きます。

なぜボキャブラリをコンテキストとして渡すのか

サジェスターを実行するたびに、tag-vocabulary.ts全体——id、ラベル、description、group——がプロンプトに含まれます。これが出力品質を決める最大の要因です。

モデルは正規セットから選ぶため、unknown を除外するラウンドトリップが無駄になりません。
group と description のコンテキストにより、近いトピック(contentとcustomizationなど)を区別できます。
新しいボキャブラリエントリを追加することが、ツールに新しいファセットを「教える」主要な手段です——ファインチューニングも埋め込みストアも不要です。

ドキュメント本文はプロンプトを小さく保つために1500文字で切り詰められます。フロントマターに関わる提案材料の大半は最初の1〜2ページに収まるので、この切り詰めが制約になることはほとんどありません。