ADR-0006: プロセスは3ズームレベル+プレインランゲージで表現する

ステータス

採用(2026-07-09)

コンテキスト

ISO 等の原典は特許文書のように難解で、そのまま載せると新人エンジニアは読み解けない。ISO の規定すらわかりやすく表現できないなら、AI-DLC 導入後のプロセス表現も同じく伝わらないはずだ(ユーザー指摘)。表現手法のディープリサーチ(検証済み25クレーム)と複数案の批評ループを経て決定した(検討記録: research/20260709-representation-policy-proposals.md)。

決定

フェーズ1以降のプロセス公開ページに、次の表現ポリシーを適用する。

3ズームレベルのドリルダウン: C4 model の地図アナロジーに倣い、L1 全体マップ → L2 フェーズ → L3 個別作業の3段階で構成する。図のノードをクリックすると下位レベルのページへ遷移する
1図15ノード前後を上限とし、超える場合は分割する(認知負荷対策)
各ページは3点セット: 図(構造)+ 平易な解説(なぜ・何のため)+ 原典対照(出典付き引用)。図と言葉の併用は二重符号化の知見に基づく
プレインランゲージ: 一文60字目安、段落5文まで(GOV.UK の定量規則を日本語換算)。難解な原典定義は「平易な言い換え → 原典引用」の対で示す
平易化は情報の取捨選択から始める(やさしい日本語の3ステップ): 逐語の言い換えではなく、読者に必要な情報へ絞り込む。伝わるかの最終確認はコミュニティのフィードバックが担う
学習用と実務用の分離(Diátaxis): 平易な解説と、6+2要素の正確なリファレンス(調査フレームワーク準拠)は同居させず、ページ内セクションまたは別ページとして分ける

検討した選択肢

案A: 読み物主導型 — 文章は読みやすいが全体像の把握を読者に委ね、8プロセスで表現が発散する。記述原則のみ採用して本体は見送り
案C: bpmn-js ビューア埋め込み型 — ドリルダウンは本格的だが、BPMN 記法自体が新人に未知の語彙で、XML は差分レビュー不能。将来の表現力拡張オプションとして保留

影響

専門家にとっても読みやすくなる(GOV.UK の調査: 専門家ほどプレインランゲージを好む)
執筆コストは上がるが、表現の統一により8プロセスの比較可能性が保たれる
Mermaid の click 有効化の条件として securityLevel: 'loose' が必要(描画設定で対応)