何がどう楽になるのか？
数百ページのマニュアル改定で「旧版と新版のどこが変わったか」を人が目で追う作業が、なくなります。
これまでは担当者が旧版と新版を1ページずつ突き合わせ、変更点をリスト化していました。1回の改定で数日規模。しかも「見落としていないか」は最後まで誰にも分かりません。
今回作ったアプリでは、2つのファイルを選んで1クリックすると、変更の件数（追加・変更・削除）、変わった箇所の左右比較（変わった文字だけ色付け）、そして「締め付けトルクが 25 N·m から 28 N·m に変更されました」といった日本語の要約文が表示されます。実文書サンプル（665ブロック・約126KB）でも処理は約0.2秒でした。
人の仕事は「変更点を探すこと」から「その変更が自社の手順書にどう効くかを判断すること」に絞られます。探す作業は機械のほうが確実です。
どんな案件だったのか？
産業機器の保守・整備に関わる製造業からのご相談で、商談用デモプロトタイプとして開発しました。整備マニュアルはメーカーから定期的に改定版が配布され、1冊300〜500ページ。保守を担う事業者はその都度、変更点を洗い出して社内の手順書や帳票に反映する必要があります。
困りごとは2つ。①比較作業が全部「目視」であること、②「その変更が自社にどう影響するか」の判断が属人化していることです。①は機械にできる作業、②は人が判断すべき業務。今回はまず①を機械に肩代わりさせることをゴールにしました。
マニュアルが XML（文書に「ここは手順」「ここは警告」といった意味のタグが付いた形式）で配布されている点に着目し、旧版・新版をブロックに分解→突き合わせ→変わった文字を特定→一覧・左右比較・要約文で表示する Windows デスクトップアプリを、要件定義から実装・テスト（自動テスト77本）・配布物作成まで一貫して担当しました（C# / .NET 8 / WPF、単一exe配布）。
工夫した点：素直に作ると、ことごとく失敗する
精度を決めるのは旧版と新版の「突き合わせ」です。ここで実際に踏んだ落とし穴を3つ紹介します。
① IDでの突き合わせは破綻する
最初はXMLの id="step1" のような識別子で突き合わせる方針でした。しかし実サンプルを見ると、手順の挿入でIDが振り直される連番であることが判明。IDで突き合わせると「トルクの手順が目視検査の手順に変わった」という事実でない差分が出て、本来の主役である「トルク値が25→28に変わった」は永久に検出されません。方針を変え、本文の文章の類似度で突き合わせることにしました。
② 定番の類似度指標では取りこぼす
類似度の定番であるレーベンシュタイン距離を、コードを書く前に実サンプルの文章で手計算したところ、4件中2件の変更を取りこぼすことが判明しました。マニュアル改定の典型は「既存の文への追記」で、文字数が倍近くになると類似度が機械的に半分近くまで落ち、「別の文だ」と誤判定されるためです。そこで「短いほうの文が長いほうにどれだけ残っているか」という指標に変更して解決。編集の実態に合った物差しを選ぶ、当たり前ですが定番手法をそのまま採ると外します。
③ 「似ているのに対応させてはいけない」ペアがある
類似度だけに頼ると逆方向の事故も起きます。「パネルP-21を取り外す」と「パネルP-21を再取り付けする」は類似度0.9台とほぼ同一に見えますが、意味は正反対。これを退けているのはしきい値ではなく**「順序を保つ」という制約**です。文書の手順は前から順に並んでいるため、全体の対応スコアが最大になる組み合わせを選ぶと、正しい対応関係が自動的に勝ちます。しきい値は「明らかに別物」を落とす役、誤対応を防ぐ役は順序制約。役割を分けると、しきい値を多少下げても壊れにくくなります。
④ 「順番が動いただけ」を変更に数えない
手順を1つ挿入すると後続の手順は全部位置がずれます。これを律儀に「移動」と報告すると、挿入1件で19件のノイズが出ることも。ノイズが混ざったリストは現場で読まれなくなります。 そこで「文章が変わらず位置だけ動いたもの」は変更件数から外し、参考情報として別枠に置く設計にしました。
このほか、25→28のような数値変更は文字単位で差分を取ると「5が8に変わった」と表示されて読みにくいため、連続する数字は1つの塊として丸ごと色付けする、要約文では安全に直結する数値の変更を必ず先頭に置く、といった「読み手に届く見せ方」にも手を入れています。
変わったものは漏らさず、変わっていないものは騒がない。 「文書の構造を理解しているから、押し出しによる位置ずれと本当の変更を区別できる」ことが、汎用の比較ツールとの差になります。
やってみて気づいたこと
サンプルは2組では足りません。 日本語サンプル2組で作り込んだ後、3組目として英文の公開文書を投入した瞬間、重大な欠陥が発覚しました。英語は文字種が少ないため、無関係な段落どうしでも文字レベルでは偶然似てしまう（無関係ペアの約2割がしきい値超え）。英文は単語単位で比較するよう切り替えて解決し、副次的に処理速度も約37分の1になりました。怖いのは、それまで「たまたま結果が正しく出ていた」こと。結果が合っていることと、仕組みが正しいことは別です。
もう1つ、「設計段階で電卓を叩く」のは効きます。 類似度指標の変更はコードを1行も書く前の手計算で判明しました。実装後に気付いていたら、やり直しで半日は溶けていたはずです。短期のプロトタイプほど「まず動かす」に流れがちですが、アルゴリズムの選定だけは紙の上で検算する価値があります。
発注者の方へ：どう頼むとうまくいくか
- 実物と同じ構造のサンプルを、早く・多様に（ダミーで可）。今回もサンプルを見る前の要件定義は前提から間違っていました
- 「たまに例外的にこういうケースがある」を最初に。例外ケースこそが設計を決めます
- 「全部自動化」ではなく「人の判断対象を絞る」で考える。機械にやらせるのは「探す」まで、「判断する」は人に残す。この線引きを最初に合意すると、プロジェクトは驚くほどスムーズに進みます
まとめ
「変わったものは漏らさず、変わっていないものは騒がない」。たった1行のポリシーですが、これを守るために設計の大半を使いました。差分を出すことより、出さない判断のほうが難しいというのが、今回いちばんの収穫です。
筆者
大久保 太樹（テックビーンズ株式会社）
「作るのが好きなリーダー」として、マネジメントの立場になっても現場のコードから離れないエンジニア。C言語の組込み開発からPHP（Laravel）、Python（FastAPI）のWeb開発まで約15年、近年はPL・PMとして要件定義から運用まで全工程を担当しています。
この記事の内容について、直接聞いてみませんか？
「うちの場合はどうなる？」「こんなことはできる？」——そのレベルのご質問で大丈夫です。プロフィールページから大久保に直接メッセージを送れます。
[ 大久保太樹にメッセージを送る ]