検証事例|LDXhub

評価基準の構造化は、MarkdownではなくJSONで持つ

作成者: Admin|Nov 16, 2026, 4:20:09 AM
3つの段階 JSONが優位な点 実例 Markdownの役割 使い分け
StructFlow 設計メモ

評価基準の構造化は、
MarkdownではなくJSONで持つ

AIに文書を点検させるとき、評価基準(スタイルガイド、品質モデル、記載要領)をどの形式でAIに渡し、どの形式で保存するか。StructFlow Loop の開発で、人が読み書きする境界は Markdown、プログラムとAIの受け渡しと保存は JSON、という分け方に落ち着いた理由を整理する。

公開日 — 【YYYY.MM.DD】 使用ツール — LDX hub StructFlow 執筆 — 川村インターナショナル
3
構造化に関わるデータの段階
5
JSONが優位な点
43
構造化した規則数(JTF日本語標準スタイルガイド)
1件=1行
StructFlow に渡すレコードの単位
結論 構造化の処理そのものを Markdown で行う利点は、中身を人が直接読めること以外にない。人が書いて読む基準ファイルは Markdown でよいが、StructFlow に渡すレコードと、構造化した結果の保存は JSON/JSONL にする。

「構造化」には、3つの段階のデータがある

StructFlow Loop は、評価基準を「確認事項・手がかり語・修正方針・範囲・重大度」に分解(構造化)してから、対象文書を1文ずつ点検・修正する方式である。この記事では、JTF日本語標準スタイルガイド(翻訳用)第4.0版(CC BY 4.0)の第1〜4章を43の規則に分けて構造化した例で説明する。

この「構造化」をデータの形式で見ると、次の3つの段階に分かれる。形式の優劣を論じるときは、どの段階の話かを分けて考える必要がある。

①

入力:基準ファイル

人が書き、読み、直す対象。スタイルガイドのPDF、品質モデルの表、記載要領の文書など、元の形はさまざまである。

②

受け渡し:StructFlow に渡すレコード

規則1件=1レコードにして、指示と出力例を添えて StructFlow に送る。StructFlow は、レコードごとに出力例と同じ形の結果を返す。

③

保存:構造化した基準

返ってきた結果を保存し、点検の段階で規則IDから確認事項や重大度を引く。同じ基準・同じモデルなら、次回はこれを使い回す。

JSON が優位なのは②と③である。①は Markdown でよい。

受け渡しと保存で、JSON/JSONL が優れている5つの点

1. 項目の境界が機械的に決まる

「確認事項」「手がかり語」「修正方針」「範囲」「重大度」を、それぞれ別の項目(キー)として持てる。Markdown でも見出しや箇条書きで分けて書けるが、書き方が少し違うだけで、どこからどこまでが1つの項目かを読み取る処理が壊れる。見出しの階層が1つずれる、箇条書きの記号が「・」と「-」で混ざる、といった揺れは、人が書く限り必ず起きる。

2. 型を持てる

手がかり語は配列、重大度は Critical/Major/Minor のどれか、範囲は「行単位」か「文書全体」のどちらか、という制約を、出力例(example_output)で示せる。StructFlow は出力例と同じ形で返すので、43の規則すべてで型のそろった結果を受け取れる。Markdown にはこの仕組みがなく、「重大度:やや重い」のような値が混ざっても止められない。

3. 1件=1行で扱える

JSONL(1行に1つの JSON)にすると、43の規則を1行ずつ送れる。規則が数百件ある基準でも同じである。1リクエストの大きさの上限(LDX hub では約64KB)に合わせて自動で分割でき、1件が失敗しても他の件に影響しない。結果も入力と同じ順で突き合わせられる。Markdown の1ファイルを送ると、分割の位置を決めるだけで解析が要る。

4. 照合がそのままできる

点検の段階で、AIが返した指摘の rule_id を、構造化した基準の rule_id と照らして規則名や重大度を引く。JSON なら辞書の検索で済む。Markdown だと、いったん解析して辞書に直す処理を毎回通すことになり、その処理が1の理由で壊れやすい。

5. 再利用が安全

構造化した基準は保存して次回も使う(基準ファイルとモデルから作ったキーでキャッシュする)。JSON なら読み直しても壊れない。Markdown で保存すると、人が手で直したときに形が崩れて読めなくなるおそれがある。「人が直せる」ことは、保存形式にとっては利点ではなく欠点になる。

補足:JSON を人に読ませない JSON の欠点は人が読みにくいことだが、これは保存した JSON から一覧の Markdown を書き出せば済む。StructFlow Loop の汎用版は、構造化のたびに _criteria/<基準名>.json と、確認用の _criteria/<基準名>.md の両方を作る。人は Markdown を見て、プログラムは JSON を読む。

1つの規則が、3つの段階でどう変わるか

JTF日本語標準スタイルガイド(翻訳用)第4.0版(CC BY 4.0)の規則「1.1.1 本文」を例にする。

① 入力:基準ファイル(Markdown)

見出し1つが規則1つ。見出しの先頭の番号が規則IDになる。人が読んで直せる形である。

markdown
## 1.1.1 本文

本文の文体は、敬体(ですます調)あるいは常体(である調)のどちらかで統一します。
敬体と常体を混在させないようにします。
敬体と常体のどちらを使うかは、文書の目的や読み手に応じて決めます。

② 受け渡し:StructFlow に渡すレコード(JSONL)

スクリプトが Markdown を読み、規則ごとに1行の JSON にする。これに指示(システムプロンプト)と出力例を添えて送る。

jsonl
{"id": "1.1.1", "data": {"rule_id": "1.1.1", "title": "本文", "text": "本文の文体は、敬体(ですます調)あるいは常体(である調)のどちらかで統一します。敬体と常体を混在させないようにします。..."}}

③ 保存:構造化した基準(JSON)

StructFlow が返した結果。確認事項・手がかり語・修正方針・範囲・重大度が、それぞれ別の項目として、型のそろった形で入っている。

json
{
  "rule_id": "1.1.1",
  "applicable": true,
  "scope": "文書全体",
  "check": "本文の文体が、敬体か常体のどちらかに統一されているか。",
  "cues": ["です", "ます", "である", "だ。"],
  "targets": ["本文の文末"],
  "violations": ["同じ文書の本文に、敬体の文と常体の文が混在している。"],
  "fix_policy": "修正",
  "fix_method": "文書の中で多く使われている文体にそろえる。",
  "severity": "Major",
  "severity_note": ""
}

項目名は StructFlow Loop 汎用版のもの。scope が「文書全体」の規則は、1文だけでは判定できないため、事前分析(全文を読んで候補を出す処理)の対象になる。この振り分けも、scope が決まった値を持つ項目だからできる。

基準ファイルは Markdown でよい。弱点は区切りだけ

①の基準ファイルは、人が書いて読み、直す対象である。Markdown(見出し1つ=規則1つ)のほうが扱いやすく、スクリプトが②の JSONL に変換してから送るので、送る段階では同じになる。CSV・Excel・JSON でも受け付けているのは、元の基準がどの形で来ても、同じ JSONL にそろえるためである。

Markdown の弱点は、規則の区切りが曖昧になりうることだけである。番号付きの見出し(「2.1.6 カタカナ語の長音」など)があれば機械的に区切れるが、番号のない見出しや、PDF から取り出した本文には、区切りの手がかりがないことがある。StructFlow Loop の汎用版では、この場合に StructFlow に「規則の始まる行」を尋ねて区切る処理(--split ai)を入れた。区切りが決まれば、あとは②③の JSON の世界である。

基準ファイルの形 規則の区切り方
Markdown・テキスト 見出し1つ=規則1つ。見出しの先頭の番号が規則ID
CSV・Excel 1行=規則1つ。「規則」「基準」「内容」などの列を本文にする
PDF・Word・PowerPoint ExtractDoc で文字を取り出し、番号付きの見出しで区切る。区切れなければ StructFlow に区切りを尋ねる
画像・スキャンしたPDF AnalyzeDoc(画像を読めるAI)で、読み取りと規則の区切りを1回で行う

人が触る境界は Markdown、機械の受け渡しと保存は JSON

段階 形式 理由
① 基準ファイル(入力) Markdown(CSV・Excel・PDF も可) 人が書いて読み、直す。スクリプトが JSONL に変換する
② StructFlow に渡すレコード JSONL 1件=1行。分割・失敗の切り分け・順序の突き合わせが機械的にできる
③ 構造化した基準(保存) JSON 項目の境界と型が決まる。規則IDで引ける。再利用しても壊れない
確認用の一覧 Markdown(③から書き出す) 人が確かめるため。直すときは①を直して作り直す
点検の結果(指摘一覧) Markdown・CSV(JSONL から書き出す) 人が読む。元の JSONL は別の処理に渡すために残す
設計の指針 「AIに渡す基準をどう書くか」で迷ったら、人が触る境界と機械が触る境界を分ける。人が触る側は Markdown で、機械が触る側は JSON で、その間の変換はスクリプトに固定する。構造化の精度は指示文の出来で決まるが、構造化の結果が安定して使い回せるかは、この形式の分け方で決まる。

この分け方を実装したSkill

Skill 内容
StructFlow Loop(汎用版) 任意の基準(Markdown・CSV・Excel・PDF・画像)を構造化して、1文ずつ点検・修正する。社内で検証中
StructFlow(汎用) ループをせず、表や文書の1件ごとに同じ指示で決まった項目の JSON を返す。分類・抽出・採点などに使う。社内で検証中
項目 内容
使用サービス LDX hub StructFlow(基準の構造化と1文ずつの点検)、ExtractDoc・AnalyzeDoc(PDF・画像の読み取り)
入力 基準ファイル(Markdown・CSV・Excel・PDF・画像)
受け渡し 規則1件=1行の JSONL(1リクエスト約64KBで自動分割)
保存 構造化した基準の JSON(基準ファイルとモデルごとにキャッシュ)と、確認用の Markdown
構造化の項目 確認事項・手がかり語・対象・違反の例・修正方針・修正方法・範囲(行単位/文書全体)・重大度
例に使った基準 JTF日本語標準スタイルガイド(翻訳用)第4.0版(CC BY 4.0)、第1〜4章を43の規則に分けたもの
川村インターナショナル — StructFlow 設計メモ — 【YYYY.MM.DD】