---
title: 検索語彙の補強と、書式・参照先の機械検査を追加
updated: 2026-07-23
---

# 2026-07-23 検索語彙の補強と機械検査の追加

AIサポートの品質について指摘を受け、**実測して裏を取ったうえで**2点に手を入れました。

## 1. 利用者の言葉で引けるようにした（実害の修正）

**「印刷」で検索して 0 件**でした。ほかにも「プリント」「元に戻す」「締め」「携帯」「パソコン」「見れない」などが、どのドキュメントにも書かれていませんでした。

原因は検索の仕組みではなく（本文は全文検索しています）、**製品側の呼び方しか書いていなかった**ことです。「PDF出力」「承認の取り消し」とは書いてあっても、利用者が使う「印刷」「元に戻す」が無いため、繋いだAIが「確認できません」と答えてしまう状態でした。

各ドキュメントの Front Matter `symptoms:` に、利用者の言葉を追加しました。

| 追加した語 | 引けるドキュメント |
|---|---|
| 印刷したい / プリントアウト / 紙で出したい | `manual/pc-report.md` |
| 印刷できない / プリントできない | `troubleshooting/pdf-not-issued.md` |
| 締め日を変えたい / 支払期限を変えたい | `manual/pc-invoice.md` |
| 見積書を印刷したい | `manual/estimate.md` |
| 並び順を元に戻したい / 承認を取り消したい | `troubleshooting/photo-order-not-reflected.md` |
| 確定を元に戻したい / やり直したい | `troubleshooting/edit-confirmed-estimate.md` |
| 見れない / 開けない / 表示されない | `decision-tree/cannot-use-feature.md` |
| 携帯を変えた / パソコンから使いたい | `manual/login-account.md` |

**回帰テストを追加しました**（`McpServerTest::test_search_finds_docs_by_user_vocabulary`）。上記の語で検索して、意図したドキュメントが返ることを固定しています。語彙を削ると赤くなることを確認済みです。

### 書かなかったこと（内容そのものが無い語）

「解約」「退会」「領収書」「バックアップ」「データ移行」も 0 件でしたが、**これらは説明するドキュメント自体がありません**。引けるようにしても答えられないため、`symptoms:` には足していません。**今後の執筆課題**です。

## 2. 書式・参照先の機械検査を追加

これまで機械で検知できるのは**プラン可否だけ**でした。新しく `tests/Feature/AiDocsIntegrityTest.php` を追加し、4点を三関門で見ます。

1. **内部リンク切れ** … ファイル名の変更・削除で参照が死んでいないか
2. **Front Matter の必須キー**（`title` / `updated`）… 書き忘れ
3. **`screen:` の画面名** … `glossary/screens.md` の許可リストに載っているか
4. **本文中のアプリURL** … Laravel の登録ルートに実在するか

4つとも、わざと壊すと赤くなることを確認しています。

**`glossary/screens.md`（画面名の一覧）を新設しました。** これが画面名の正本です。**画面を新設・改名したら、まずこの表を更新してください。**

URL照合の正規化ルール（誤検知を避けるため意図的に絞っています）：

- 対象は**バッククォートで囲まれ `/` で始まるもの**だけ（`` `/account/company` ``）。地の文の「/」は拾いません。
- クエリ文字列（`?`以降）とフラグメント（`#`以降）は無視します。
- 末尾の `...` は「以降は動的パラメータ」の意味とみなし、**前方一致**で判定します（`` `/reset-password/...` `` は `reset-password/{token}` に一致）。
- ルート側の `{param}` は1セグメントのワイルドカードとして扱います。

## この検査で見つかった実際のズレ

- **`index.md` に Front Matter がありませんでした**（唯一の例外状態）。追加しました。
- `screen:` の表記が揺れていました。「`・`」が「複数画面の区切り」と「画面名の一部（プラン・課金）」の両方に使われていて機械分割できなかったため、**区切りは `/` に統一**しました（4ファイル）。

## AI影響

- [x] **プランのゲート（`App\Services\Entitlement`）を変えた？** → いいえ。
- [x] **画面名・操作手順が変わった？** → いいえ。画面名の**正本 `glossary/screens.md` を新設**しました。
- [x] **画面のURLを変えた？** → いいえ。
- [x] **新しいエラー文言が出るようになった？** → いいえ。
- [x] **文言は出ないが挙動が変わる現象が増えた？** → いいえ。
- [x] **用語が増減した？** → いいえ（画面名の一覧を追加）。

## 注意（サポート時に効くポイント）

- **「解約したい」「領収書がほしい」は、まだドキュメントがありません。** 推測で答えず、お問い合わせに繋いでください。