## 自動ではなくオプトイン

`pnpm tags:suggest`はパッケージ所有のサジェスト CLI を実行する開発者向けヘルパーであり、ビルドの一部ではありません。生成された package script は`tags:audit`と同じ明示的な`src/config/tag-vocabulary.ts`の`TagCliConfig`を渡します。1つ以上のドキュメントファイルを読み、ローカルで動いている LLM にそのボキャブラリから最大3つのタグ id を提案させ、対話プロンプトで表示するか、バッチレビュー用に JSON Lines ファイルへ追記します。

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

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

より厳密な強制が欲しい場合は、[`tagGovernance: "strict"`](https://zudo-doc.takazudomodular.com/ja/docs/guides/tag-governance)と[`pnpm tags:audit`](https://zudo-doc.takazudomodular.com/ja/docs/guides/tags-audit)の役割です。

## Ollama のセットアップ

サジェスターはローカルで動く[Ollama](https://ollama.com/)デーモンと HTTP で通信します。

1. [ollama.com](https://ollama.com/)から Ollama をインストールします。
2. モデルを pull します。

   ```sh
   ollama pull qwen2.5:7b
   ```

3. デーモンが`http://localhost:11434`(デフォルト)で接続できることを確認します。

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

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

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

## 対話フロー

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

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

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

## バッチフロー

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

```sh
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ページに収まるので、この切り詰めが制約になることはほとんどありません。

## 関連

- [タグガバナンス](https://zudo-doc.takazudomodular.com/ja/docs/guides/tag-governance) — サジェスターが参照するボキャブラリを定義する。
- [タグ監査](https://zudo-doc.takazudomodular.com/ja/docs/guides/tags-audit) — 取りこぼした提案を拾う。