AquaVoiceのDictionary・CustomInstructions・Replacements、公式ドキュメントに見る役割分担
AquaVoiceのDictionary・CustomInstructions・Replacements、公式ドキュメントに見る役割分担
AquaVoice（音声入力アプリ）には、認識精度やフォーマットを調整する3つの機能がある。Dictionary・CustomInstructions・Replacementsだ。公式ブログとガイドページを読むと、この3つには明確な役割分担がある。
- Dictionary: その単語を正しく聞き取らせるための機能。固有名詞・専門用語・ツール名・サービス名が対象
- CustomInstructions: 聞き取ったあとの表記・文体を整えるための機能。ケース規則や言い回しのルールが対象
- Replacements: 短い合言葉を長い定型文に展開する機能。LLMプロンプトやURLが対象
一言でいえば、Dictionaryは「聞き取り」の担当、CustomInstructionsは「整形」の担当。この切り分けを知らずに使うと、固有名詞の誤変換をCustomInstructionsのルールだけで力技解決しようとして、うまくいかないことがある。
背景: 前回の記事で浮かんだ疑問
前回の記事では、過去30日分のセッションログから誤変換パターンを洗い出し、Dictionaryに「Codex」「Turso」「mdx-playground」など11件を登録した。
その一方で、「Claude Code」の誤変換（「codex」と聞き間違えられる等）はCustomInstructionsのルール追加だけで対応していた。Dictionaryに入れるべき単語をCustomInstructions側に置いてしまっていないか、公式ドキュメントで確認することにした。
Dictionary: 「正しく聞き取らせる」ための機能
公式ガイドはDictionaryの用途をこう説明する。
"The Dictionary is made for difficult words: from names and terms that are hard to spell, to business acronyms that are used only at your company internally, to even fantasy names you've invented for your novel."
「スペルが難しい単語」向けの機能、という位置づけだ。ガイドが挙げる登録例は4種類ある。
| カテゴリ | 例 |
|---|---|
| 国際的な人名 | Izadi、Kamil Szczerba、Zsófia |
| 専門用語（医学） | Ruxolitinib、Myelofibrosis、JAK1/JAK2 inhibitor、Splenomegaly |
| 社内ツール名・略語 | Bookface、MCP、Praxivault、Opsinova |
| 創作上の固有名詞 | Rokhollow、Draewenford、Thornvale（小説の架空地名） |
登録上限はFAQに記載があり、最大800件まで追加できる。
開発者向けのClaude Code連携を紹介するブログ記事では、もう一段具体的に踏み込んでいる。
"Load your stack into the Custom Dictionary: framework names, services, CLI tools, the libraries you say twenty times a day."
フレームワーク名・サービス名・CLIツール名・毎日何度も口にするライブラリ名は、まさにDictionaryの対象として名指しされている。「Claude Code」もCLIツールの名前である以上、この分類に当てはまる。
CustomInstructions: 「聞き取ったあとどう整形するか」を制御する機能
CustomInstructionsは、認識済みのテキストをどう書式化するかを指定する機能だ。
"Aqua can format your text in any way you want: from emails, casual text, to specific region preference."
書き方の原則も示されている。
"Instructions are understood best by Aqua when listed and with an example of what you want."
ルールを列挙するだけでなく、望ましい出力例・望ましくない出力例をセットで書くと精度が上がる、ということだ。ガイドに載っている用途例は次の通り。
- メール文面: 挨拶文と署名の改行の入れ方を指定する
- 文体: 「Never use em-dashes.」のように、使ってほしくない表現を禁止する
- 地域表現: 「Always use UK English, in a South African context.」のように地域ごとの言葉遣いを指定する
- 簡潔さ: 「Never start sentences with 'and', 'but' or 'because'」のように文の書き出しを制限する
- コードの命名規則: 「keep code identifiers in camelCase」のように識別子の大文字小文字ルールを指定する
いずれも「単語をどう聞き取るか」ではなく、「聞き取ったあとどう書き直すか」の指定になっている。
Replacements: 「短い合言葉→長い定型文」の展開機能
Replacementsは、決まった短いフレーズを長いテキストに置き換える機能だ。
"Replacements allow users to enter short snippets to be replaced with something else."
用途は3つ挙げられている。
- 繰り返し使うLLMプロンプトのテンプレート
- よく使うメールアドレスの自動入力
- 頻繁に共有するURL（カレンダーリンク等）
設定は「置換前の短いフレーズ」と「置換後の定型文」をペアで登録するだけ。Aqua v0.10.8以上で利用できる機能で、聞き取りにも文体調整にも関係しない、単純なテンプレート展開の機能として独立している。
3機能の役割分担まとめ
| 機能 | 目的 | 対象の例 |
|---|---|---|
| Dictionary | 単語を正しく聞き取らせる（認識精度） | 固有名詞・専門用語・ツール名・サービス名 |
| CustomInstructions | 聞き取ったあとの表記・文体を整える | ケース規則・文体・地域表現・句読点ルール |
| Replacements | 短い合言葉を長い定型文に展開する | LLMプロンプトのテンプレート・メールアドレス・URL |
前回の実施結果と照らし合わせると
この役割分担は、前回記事で実際に体験した挙動とも一致する。
前回、「減価償却費」という単語はCustomInstructionsのルール追加だけでは4回連続失敗し、「原価償却費」「原価消却費」といった誤変換が続いた。最終的にDictionaryへ完全な形で「減価償却費」を登録して初めて安定した。「聞き取りの問題は聞き取りの機能（Dictionary）で直す」という公式の役割分担に、この結果はそのまま当てはまる。
一方、「Claude Code」については、「codexへの誤変換」という聞き取りの問題をCustomInstructionsのルール追加で対応し、記事上は「新規ルール追加で解決」としていた。だが公式の役割分担に沿うなら、これはDictionaryで直すべき問題だったことになる。CustomInstructionsのルールで一時的に解決できたとしても、減価償却費のケースと同じく、条件が変わったときに再び不安定になる可能性がある。
まとめ
AquaVoiceのDictionaryとCustomInstructionsは、見た目は両方とも「単語や表現をカスタマイズする機能」だが、公式ドキュメント上は担当領域がはっきり分かれている。固有名詞・専門用語・ツール名の誤変換はDictionaryで直し、文体やフォーマットのルールはCustomInstructionsに任せる。この線引きを意識すると、CustomInstructionsに個別の単語ルールを積み増して不安定なまま運用するという状態を避けやすくなる。
Sources: