Node.jsで生成AI向け社内用語集YAMLを検証する：定義・禁止例・見直し期限をCIで守る

生成AIを業務へ導入するとき、「確認済み」「正本」「承認」の意味が担当者ごとに違うと、コードが正常でも運用は止まります。そこで用語集をYAMLで管理し、必須項目、ID重複、見直し期限をPull Requestごとに検証します。

この記事ではNode.js 20以降を使い、次の状態まで作ります。

• 用語の定義、使用場面、禁止例、証跡、責任者をYAMLに保存する
• スキーマ不備、重複ID、期限切れを検出する
• GitHub ActionsでPull Request時に自動検査する
• 意味と責任境界の判断は人間のレビューに残す

個人情報や問い合わせ本文は用語集へ入れません。ここで管理するのは業務上の状態と判断ルールです。

ディレクトリ構成

ai-ops-rules/
├── ops/
│   └── glossary.yml
├── scripts/
│   └── validate-glossary.mjs
├── .github/
│   └── workflows/
│       └── glossary-check.yml
└── package.json

最初から全社用語を網羅せず、問い合わせ返信など一つの業務に限定します。

YAMLに運用可能な項目を持たせる

ops/glossary.yml を作成します。

version: 1
last_reviewed_at: 2026-08-02
terms:
  - id: human_review
    label: 人間確認
    definition: >-
      AIの出力を正本と照合し、送信または実行してよいかを
      指定された確認者が判断する工程。
    use_when:
      - 顧客向け返信を送信する前
      - 金額、契約、納期を含む出力を使う前
    not_equal_to:
      - 画面を開いただけ
      - 誤字だけを確認した状態
    evidence_required:
      - 参照した正本の文書ID
      - 確認者
      - 確認日時
      - 判断結果
    owner: inquiry_ops_owner
    review_by: 2026-11-02

  - id: canonical_source
    label: 正本
    definition: 最終判断で参照する、責任者が承認した一次情報。
    use_when:
      - AIの回答根拠を確認するとき
    not_equal_to:
      - 個人メモ
      - 更新日不明のコピー
    evidence_required:
      - 文書ID
      - 版番号
      - 承認者
    owner: knowledge_owner
    review_by: 2026-11-02

definition だけではなく、not_equal_to を必須にするのが重要です。「人間確認は画面を開くことではない」のように、似ているが不十分な状態を明示できます。

検証スクリプトを実装する

依存関係を用意します。

{
  "type": "module",
  "scripts": {
    "check:glossary": "node scripts/validate-glossary.mjs"
  },
  "devDependencies": {
    "yaml": "^2.8.0"
  }
}

scripts/validate-glossary.mjs では、構造だけでなく運用上の抜けも検査します。

import fs from "node:fs";
import process from "node:process";
import YAML from "yaml";

const file = process.argv[2] ?? "ops/glossary.yml";
const glossary = YAML.parse(fs.readFileSync(file, "utf8"));
const required = [
  "id", "label", "definition", "use_when", "not_equal_to",
  "evidence_required", "owner", "review_by",
];
const errors = [];
const ids = new Set();
const today = new Date();

if (!Array.isArray(glossary.terms) || glossary.terms.length === 0) {
  errors.push("terms must contain at least one term");
}

for (const [index, term] of (glossary.terms ?? []).entries()) {
  const at = `terms[${index}]`;

  for (const key of required) {
    const value = term[key];
    const emptyArray = Array.isArray(value) && value.length === 0;
    if (value === undefined || value === "" || emptyArray) {
      errors.push(`${at}.${key} is required`);
    }
  }

  if (!/^[a-z][a-z0-9_]*$/.test(term.id ?? "")) {
    errors.push(`${at}.id must be snake_case`);
  } else if (ids.has(term.id)) {
    errors.push(`${at}.id is duplicated: ${term.id}`);
  } else {
    ids.add(term.id);
  }

  const reviewBy = new Date(`${term.review_by}T23:59:59Z`);
  if (Number.isNaN(reviewBy.getTime())) {
    errors.push(`${at}.review_by must be YYYY-MM-DD`);
  } else if (reviewBy < today) {
    errors.push(`${at}.review_by has expired: ${term.review_by}`);
  }
}

if (errors.length > 0) {
  console.error(errors.map((e) => `- ${e}`).join("\n"));
  process.exit(1);
}

console.log(`OK: ${ids.size} glossary terms are valid`);

実行します。

npm install
npm run check:glossary

成功時は OK: 2 glossary terms are valid と表示されます。期限切れを警告だけにすると放置されやすいため、この最小例では検査を失敗させます。実運用では見直し期限の7日前から警告し、当日に失敗させる設計も可能です。

GitHub ActionsでPull Requestを止める

.github/workflows/glossary-check.yml を追加します。

name: glossary-check

on:
  pull_request:
    paths:
      - "ops/glossary.yml"
      - "scripts/validate-glossary.mjs"
      - "package-lock.json"

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm run check:glossary

このワークフローは秘密値を必要としません。permissions: contents: read とし、検査に不要な書き込み権限を与えない構成です。

機械検査と人間レビューを分ける

自動検査で確認できるのは、形式、空欄、重複、期限です。次は人が確認します。

• 実際の業務で定義が通じるか
• 禁止例が例外を十分に表しているか
• 正本と証跡の要件が妥当か
• 誰が送信・実行の責任を持つか
• フォーム、CRM、手順書の状態名と一致するか

Pull Requestには次のチェックリストを置きます。

- [ ] 変更理由と対象業務を書いた
- [ ] 使用例と禁止例を現場担当者が確認した
- [ ] 正本・証跡・責任者を承認責任者が確認した
- [ ] フォーム、CRM、FAQへの影響を確認した
- [ ] 適用日と次回見直し日を決めた

AIは既存文書から表記ゆれや重複候補を抽出できますが、契約、金額、個人情報、送信可否の責任境界は決めさせません。候補の採否は正本と現場運用を照合して人が決定します。

導入チェックリスト

1. 対象業務を一つに絞る
2. 現在使う状態語を集める
3. 同じ言葉で意味が違う事例を探す
4. YAMLへ定義、禁止例、証跡、責任者、見直し日を書く
5. 検証をPull Requestの必須チェックにする
6. 現場担当者と承認責任者を分ける
7. CRMや承認画面ではYAMLのIDを共通キーとして使う
8. 期限到来時と業務変更時に見直す

まとめ

生成AI向けの社内用語集は、用語解説ではなく判断状態をそろえる運用資産です。YAMLとNode.jsを使えば、必須項目、重複ID、見直し期限は機械的に守れます。一方、定義の意味や責任境界は人間レビューに残します。

まずは直近の業務で使った「確認済み」を一つ選び、誰が何を照合した状態なのかを書き出してください。AI導入前の業務整理では、ツールより先にこの状態をそろえることが、手戻りを減らす第一歩になります。