constraints-extractor

Constraints Extractor

プロジェクトのドキュメントから明示的および暗黙的な制約を抽出し、それらを正規の CONSTRAINTS.md にまとめます。これは、プロジェクトで構築できるものとその方法を形作る、外部から課される境界（コンプライアンス、セキュリティ、ホスティング、ツール、ステークホルダー、スコープ、依存関係）を記録し続けるドキュメントです。

他の継続的なドキュメントとの関係

このスキルの対象範囲は意図的に限定されています。制約であることが明確でない内容は、このファイルには含めません。記録する前に、以下の強制機能テストを適用してください。

Forcing-function test: if this were ignored, would something break OUTSIDE
the codebase — a contract, a law, a security posture, an executive decision,
a vendor relationship? If yes, it's a constraint.

If the honest answer is "the team would just be inconsistent" or "it would
look different," it's a pattern or a procedure, not a constraint — it
belongs in config.yaml or AGENTS.md instead.

ドキュメント	作成元	記録する内容
openspec/config.yaml	onboard-openspec スキル	チームが選択した内容（スタック、パターン）
AGENTS.md / CLAUDE.md	onboard-agent スキル	エージェントが従うべき振る舞い
ARCHITECTURE.md	architecture-doc スキル	現在のシステム構造
CONSTRAINTS.md	このスキル	特定の選択が譲れない理由

カテゴリの完全な定義、詳しく説明した強制機能テスト、およびカテゴリごとの対象／対象外の例を示す表は、references/category-guide.md にあります。ドキュメントごとの抽出を実行する前に、これを読んでください。

出力先

何かをスキャンする前に CONSTRAINTS.md の配置場所を決めてください。これにより、Source Discovery は既存ファイルをスキャン対象ではなく、信頼できる情報源として扱えます。

1. まず、リポジトリ全体を検索して、既存の CONSTRAINTS.md ファイルを探してください。ルートや docs/ だけを対象にするのではなく、リポジトリ全体を検索する手段（find、rg など）を使ってください。1 つだけ見つかった場合は、それを対象とします。ユーザーに確認せず、そのファイルを使用してください。
2. CONSTRAINTS.md が複数見つかった場合は、作業を中止して該当ファイルを表示してください。推測で決めず、どのファイルを正とするかユーザーに確認してください。
3. 見つからない場合は、ARCHITECTURE.md と AGENTS.md の隣にあるリポジトリのルートの CONSTRAINTS.md を既定の出力先とします。
4. 作業を続ける前に、選択したパスを通知してください。「既存の CONSTRAINTS.md が見つかりませんでした。./CONSTRAINTS.md に書き込みます。」

制約の抽出時に絶対にしてはいけないこと

• ソース文書の証拠で裏付けられていない制約を、絶対に作り出さないでください。 候補となる記述に実際の証拠がなければ、CONFIRMED には該当しません。低信頼度の項目として扱うのではなく、ニアミスとして扱ってください（下記の「書き込み前のプレビュー」を参照）。弱い証拠を頼りにできる第三の段階はありません。
• ソース間に矛盾があるからといって、制約を黙って削除しないでください。 両方の見解を記録し、項目に CONFLICTING の印を付け、それぞれのソースを引用してください。
• 少なくとも1つの証拠の引用（ファイルに加え、セクションまたは行の参照）なしに、制約を書かないでください。 ソースのない制約は、幻覚による記述と同じように見えます。
• 自信に満ちた表現のチームの好みを、絶対に制約として扱わないでください。 強制力のテストを適用してください。外部からの強制力が見られない場合は、書き込み前のプレビューでニアミスとして提示し、ファイルには含めないでください。下記の「書き込み前のプレビュー」を参照してください。
• CONSTRAINTS.md に「確認済み・未記載」セクションや、それに類するセクションを絶対に書かないでください。 ニアミスは会話の出力であり、ファイルの内容ではありません。「書き込み前のプレビュー」を参照してください。
• CONSTRAINTS.md に「関連ドキュメント」セクションを絶対に追加しないでください。 リンクは一方向です。AGENTS.md または CLAUDE.md から、相互リンクの手順でこのファイルを参照します。その逆ではありません。このファイルをすでに参照しているファイルへの逆向きの参照は、まったく不要です。
• スキャン対象のリポジトリ内に、スクラッチ用または調査結果の JSON ファイルを絶対に書き込まないでください。また、相対パスのファイル名も絶対に使用しないでください。 すべての中間ファイル（各サブエージェントのスクラッチ出力と、相関させた調査結果ファイル1つ）は、絶対パス /tmp/constraints-extractor.XXXXXX/ の下に置きます。相対パスのファイル名はエージェントの作業ディレクトリ、つまり /tmp ではなくスキャン対象のリポジトリを基準に解決されます。
• CONSTRAINTS.md の項目を手書きしたり、手動で書式設定したりしないでください。 新規項目も、既存項目の裏付けを追加する場合も、1件だけであっても、すべて scripts/merge_constraints.py を通してください。手動で書式設定すると、場当たり的な記号、余分なフィールド、不揃いなスペースなどによって構造が一貫しなくなり、次回の実行時にスクリプトがファイルを再解析できなくなります。
• scripts/merge_constraints.py が古い項目の削除や、誤った引用の差し替えを自動で行うと期待しないでください。 このスクリプトは設計上、追加のみを行います。新しい調査結果を挿入し、証拠を統合して既存の調査結果を補強しますが、削除する手段はありません。新たなスキャンが既存の CONFIRMED 項目を直接否定する場合でも同様です。その場合は CONFLICTING の調査結果になりますが、元の記述を削除せず、主張を追加します。古い項目の削除や誤った引用の修正は、CONSTRAINTS.md を直接編集してよい唯一のケースです。正確な手順については、下記の「古い項目と誤った引用の削除・修正」を参照してください。これは上記のルールの抜け道ではありません。ユーザーの明示的な確認のもと、すでに正しく書式設定されている既存の行を修正するものであり、新たな場当たり的な構造を作るものではありません。
• openspec/changes/archive/ を自動的にクロールしないでください。 全文書のスキャンには大きすぎ、解決済み変更によるノイズが、本当に有用な情報を埋もれさせてしまいます。ユーザーが明示的に指定した場合に限り、アーカイブ内の特定のファイルを読んでください。
• サブエージェントが利用可能な場合、抽出を直列で実行しないでください。 最大同時実行数を5として、並列にディスパッチしてください。ソース文書が5件を超える場合は、同時実行数を無制限にするのではなく、複数回に分けて実行してください。
• 既存の CONSTRAINTS.md を、最初に読まずに上書きしないでください。 人間が信頼度を手動で修正したり、曖昧さを解消したりしている場合があり、新たなスキャンではその内容を復元できないことがあります。

ソースの検出

サブエージェントを起動する前に、スキャン対象となるソース文書のセットをまとめます。 サブエージェントに指示を出す前に、最終的な一覧をユーザーに伝えます。

ステップ 1 — 一般的な場所を自動検出する。 次の場所を確認し、存在する場合は含めます。

• docs/、documents/、doc/（再帰的に検索 — Markdown とプレーンテキスト）
• README.md、CONTRIBUTING.md、SECURITY.md、COMPLIANCE.md、LICENSE*
• ARCHITECTURE.md、AGENTS.md / CLAUDE.md、openspec/config.yaml — これらは意思決定の結果ですが、説明文には、正式な制約として 明文化されなかった根拠が埋もれていることがあります。
• 存在する場合は、意思決定記録形式のフォルダー：adr/、decisions/、rfd/、 rfcs/、notes/、spikes/ — NOTE／SPIKE／RFC 形式の文書を含むフォルダーは 重要な情報源です。解決済みの意思決定の根拠には、強制力のある条件が 明示的に記されていることが多いためです。
• 上記の「出力先」で定めた場所に既存の CONSTRAINTS.md があれば、それも含めます （「CONSTRAINTS.md の場所を特定する、または作成する」を参照し、内容を すべて読みます。ほかのスキャン対象と同列には扱いません）。

上記の確認はすべて、個別のパスごとにツールを呼び出すのではなく、1 つにまとめた bash コマンドとして実行します。どれも推論を必要としない高速な存在確認であるため、まとめて実行すれば、十数回ではなく 1 回の往復で済みます。

for p in docs documents doc README.md CONTRIBUTING.md SECURITY.md \
         COMPLIANCE.md ARCHITECTURE.md AGENTS.md CLAUDE.md \
         openspec/config.yaml adr decisions rfd rfcs notes spikes; do
  [ -e "$p" ] && echo "FOUND: $p"
done
ls LICENSE* 2>/dev/null

ステップ 2 — ユーザーが明示した一覧を受け付ける。 ユーザーが特定のファイルやパスを指定した場合は、openspec/changes/archive/ 内のファイルも含め、そのセットに追加します。これはステップ 1 に加えるものであり、置き換えるものではありません。

ステップ 3 — 重複を除いて一覧を伝える。

Merge (Step 1 ∪ Step 2) by resolved path, then tell the user:

"Scanning N documents across ceil(N/5) waves of up to 5 subagents each:
[list]. This excludes openspec/changes/archive/ by default since it's
typically too large for a full pass — name specific files there if you
want them included."

統合したセットが空の場合は、パスを推測するのではなく、ドキュメントの保存場所をユーザーに尋ねて作業を停止します。

---

文書ごとの抽出（並列サブエージェント）

ソース文書ごとにサブエージェントを 1 つ起動します。直列ではなく並列で実行し、同時実行数は最大 5 件とします。検出された文書が 5 件を超える場合は、最大 5 件ずつのウェーブに分け、次のウェーブを開始する前に現在のウェーブの完了を待ちます。

ウェーブは指示のバッチ処理に関するものにすぎません。以下の「単一の照合パス」は変更されず、すべてのウェーブが完了した後に 1 回だけ実行し、ウェーブごとには実行しません。

各サブエージェントは次のとおりです。

1. 割り当てられたファイルを全体にわたって読みます。
2. 見つかったすべてのルール、制限、境界を示す記述に対して、強制力テストを適用します。
3. 制約の候補ごとに、以下を抽出します。
   • statement — 平易な英語で記述した、自己完結型の制約（ソースファイルを開かなくても正しく理解できること）
   • impact — 実務上の影響を説明する1～3文：何を制約するのか、どのような判断に反映すべきか、無視すると何が破綻するのか。制約を含める場合は必須です。サブエージェントがこれを明確に説明できない場合、通常、その候補は実際の制約ではなく、惜しい候補です。
   • category — 正確なスラッグをそのまま使用します：compliance-governance、security-privacy-ip-cui、hosting-infrastructure、tooling-approved-path、workflow-sequencing、stakeholder-executive、scope-prioritization-delivery、またはexternal-dependencies。定義の全文はreferences/category-guide.mdにあります。短縮形や表示名ではなく、スラッグ自体を使用してください。merge_constraints.pyはいくつかの一般的な異形を自動修正しますが、確実に解決できないものがあると処理を停止します。ここでの不一致は、カテゴリの調査結果が気づかれないまま欠落する原因になります。
   • confidence — この段階では常にCONFIRMEDです。「根拠が弱い」という段階はありません。実際の引用で裏付けられていない記述は、信頼度の低い制約ではなく、惜しい候補です。CONFLICTINGが割り当てられるのは、以下の単一相関パスで抽出結果同士が食い違った場合のみです。単一ドキュメントを担当するサブエージェントは、それだけでは食い違いを確認できません。
   • evidence — 引用のリスト。それぞれに、file（絶対パスではなく、プロジェクトルートからの相対パス）、location（ソースに実際の行番号がある場合は行番号または範囲、それ以外は短いセクションアンカー）、note（その引用が示す内容を説明する必須の一文）を含めます。この文は該当する引用のEvidence notes箇条書きとして登録されるため、単に記述を言い換えるのではなく、それ自体で一行に値する内容にしてください。
   • affects — 任意のリスト。この制約の適用が影響する、名称のみのトークン（ルールID、他の制約ID、システム名）を指定します。ソースで実際に名前が示されていないトークンを推測するのではなく、省略するか空のままにしてください。
   • enforced_by — 任意のリスト。この制約の適用を促す、特定の下流ルール（AGENTS.md、ARCHITECTURE.md、config.yaml、その他のファイル内）を名称のみのトークンで指定します。推測せず、省略してください。
4. 強制力テストを満たさない、制約のように見える記述も、惜しい候補としてフラグを立てます。その理由は1行で記載します。これらは書き込み前のプレビュー（「書き込み前にプレビュー」を参照）にのみ表示され、CONSTRAINTS.md自体には書き込まれません。
5. 調査結果全体をJSONとして、mktemp -d "/tmp/constraints-extractor.XXXXXX"配下の絶対パスにある一時ファイルへ書き込みます（サブエージェントごとに1ファイル。相対ファイル名は使用せず、スキャン対象のリポジトリ内にも保存しないでください）。その後、オーケストレーターには「docs/SECURITY.mdから制約を4件、惜しい候補を2件抽出しました」のような確認文を1行だけ返します。調査結果全体をオーケストレーターのコンテキストに含めないでください。オーケストレーターは単一相関パスで一時ファイルを直接読み取り、調査結果をインラインでは受け取りません。

抽出段階でも相関処理でも、エントリのCONSTR-<CATEGORY>-<NNN> IDを割り当てないでください。IDの割り当ては、カテゴリごとにスコープを限定してmerge_constraints.py内で一度だけ行われます。抽出と相関で生成するのは調査結果のみであり、IDを割り当てるのはこのスクリプトだけです。

単一の相関処理

すべてのサブエージェントが完了した後、reduce パスを1 回だけ実行します。各ウェーブごとに実行してはいけません。

1. すべてのスクラッチファイルを 1 回の呼び出しで読み取ります。個別のツール呼び出しで 1 つずつ開くのではなく、cat /tmp/constraints-extractor.XXXXXX/*.json を使用します。
2. 候補をカテゴリ別にグループ化します。
3. 重複を相関させます。 2 つ以上のソースが同じ根本的な制約を裏付けている場合は、1 つの検出事項にまとめ、証拠の引用（合算ではなく、ファイルと場所の組み合わせで重複排除）を 1 つの evidence リストに統合します。各引用はそれぞれの note を保持します。検出事項を統合しても、ノート同士は統合しません。
4. 矛盾を明示します。 2 つのソースが同じ境界について両立しない主張をしている場合、どちらかを採用してはいけません。claims リストを作成し、片方の主張ごとに 1 つのエントリを設け、それぞれに statement、file、location を含めます。confidence を CONFLICTING に設定し、その検出事項から evidence／impact フィールドを完全に削除します（CONFLICTING の検出事項には claims が含まれ、evidence と impact は含まれません）。
5. ニアミスを振り分けます。 ドキュメントごとの抽出中にニアミスとしてフラグが付けられたものは、プレビュー手順で表示されるよう、相関済み検出事項ファイルに含めます。CONSTRAINTS.md にセクションを設けてはいけません。

相関結果を <scratch-dir>/correlated-findings.json に書き込みます。これはスクラッチファイルと同じ /tmp ディレクトリ内の絶対パスでなければなりません。トップレベルの構造は、カテゴリ別にグループ化せず、フラットなリストにします。

{"constraints": [ {"category": "workflow-sequencing", "title": "...", ...}, ... ], "near_misses": [...]}

{"workflow-sequencing": [...], "compliance-governance": [...]} のような形式にはしません。マージスクリプトは constraints 配列を読み取り、各項目の category フィールドを参照します。トップレベルの JSON キーに使われたカテゴリ名を解釈する方法はありません。スクリプトは constraints キーの有無を明示的に確認し、キーが見つからない場合は実際に見つかったキーを示して実行を拒否します。そのため、結果が何も書き込まれない状態がエラーとして明確に表示されます。マージスクリプトが想定する完全な構造については、references/troubleshooting.md を参照してください（マージ手順のトラブルシューティングが必要な場合のみ参照してください。通常の使用では読む必要はありません）。

---

CONSTRAINTS.md の場所を特定するか作成する

上記の「出力先」で決定したパスを使用します。

• 存在する場合： まず全体を読み取ります。手動で編集された項目は、同じ制約に対する新しいスキャン結果よりも優先されるものとして扱います。ただし、新しい証拠がそれと直接矛盾する場合は、黙って上書きするのではなく、プレビュー手順で矛盾を報告します。新しい検出事項を、該当するカテゴリのセクションにその場で統合します。
• 存在しない場合： references/template.md から新規作成します。

追加と裏付けに関するすべての機械的なファイル操作（ID の割り当て、カテゴリへの挿入、重複の統合、並べ替え）は、scripts/merge_constraints.py が処理します。場当たり的に文字列を追記して、ファイルの構造を手動で編集してはいけません。ファイル末尾に安易に追記すると、カテゴリのグループ化が壊れます。新規項目や裏付け済み項目の挿入方法については、このスクリプトが唯一の信頼できる情報源です。スクリプトでは項目や引用を削除できません。直接ファイルを編集してよい唯一のケースについては、以下の「古くなった項目と不適切な引用の削除」を参照してください。

python3 scripts/merge_constraints.py \
  --target <absolute path to CONSTRAINTS.md> \
  --findings <absolute path to correlated-findings.json under /tmp>

両方の引数には絶対パスを指定する必要があります。スクリプトが相対パスを拒否するのは、相対パスが /tmp ではなくスキャン対象のリポジトリを基準に解決されるためです。

このスクリプトは冪等です。同じ検出事項ファイルを指定して再実行しても、差分は発生しません。

検証に失敗した検出事項（不正なカテゴリ、証拠の不足、変換できない未知の形式）は、個別にスキップされます。バッチの残りが書き込まれなくなることはありません。実行するたびにスクリプトの標準出力を確認してください。書き込まれた内容とスキップされた内容の両方が、それぞれのスキップ理由とともに報告されます。スキップされた検出事項は担当者に伝えてください。正常終了したからといって、「今回の実行ですべて反映された」と扱ってはいけません。一部のみの書き込みでも、実行自体は成功と見なされます。

---

古いエントリと不適切な引用の削除

merge_constraints.py は追加のみを行います。新しい調査結果を挿入し、根拠を統合して既存の調査結果を補強しますが、削除する機能はありません。既存のエントリを削除したり、引用を取り除いたり、不適切になった引用を置き換えたりすることはありません。新たなスキャン結果が既存の CONFIRMED エントリと直接矛盾する場合も同様です。その場合は CONFLICTING の調査結果となり、元の内容を削除するのではなく、主張を追加します。削除や引用の修正が必要な場合、スクリプトを新しい調査結果とともに再実行しても対応できません。

通常のマージ実行ではなく、次のような状況では、この方法を使います。

• 古いエントリ。 制約がもはや当てはまらない場合です。たとえば、元のドキュメントが書き換えられた、ポリシーが変更された、ベンダーとの関係が終了した場合などです。スクリプトはカテゴリとタイトルだけで照合し、「これはもう当てはまらない」という内容を照合する手段がないため、新たな調査結果ファイルで古いエントリが置き換えられることはありません。
• 不適切な引用。 既存のエントリにある file:location が、かつての参照先のテキストを指さなくなった場合です。ファイルが移動した、セクションが書き換えられた、行番号がずれたなどの理由で、そのエントリの根拠が記述内容を裏付けなくなっていることに気づけない可能性があります。

どちらの場合も、ファイルに加えるほかの変更と同じように扱います。理由とともに、以下の「書き込み前のプレビュー」に変更内容を示し、ユーザーの確認を得てから手動で編集してください。同じ処理で追加や補強があれば、まず merge_constraints.py を実行し、その後に手動で整理します。こうすることで、スクリプトの解析・レンダリング処理が編集中のファイルを再解析するのを防げます。

「手動」とは、references/entry-format.md に従い、正しい形式ですでに記述されている行を修正または削除することです。自由な形式で書き換えることは決してせず、ファイルを編集中だからといって新しいエントリを手書きすることも認められません。

• エントリ全体を削除する場合： `### CONSTR- · ` ブロック全体を、末尾の空行も含めて削除します。その結果、カテゴリセクションにエントリがなくなる場合は、セクションが空のままにならないよう、`*No entries yet.*` マーカーを復元します。削除した ID を再利用してはいけません。以降に欠番があっても、次回の `merge_constraints.py` 実行時に次の未使用番号が割り当てられます。
• 有効なエントリにある不適切な引用を1件修正する場合： Evidence: 行の該当する引用の部分（引用を修正するのではなく削除する場合は、その引用の (N refs) 件数も含む）と、Evidence notes: の下にある対応する箇条書きだけを編集します。references/entry-format.md のフィールド規則に従い、両方のリストで同じ位置にある項目を編集してください。エントリのほかのフィールドは変更しないでください。

このスキルで CONSTRAINTS.md を直接編集することが適切なのは、ここだけです。上記の「エントリを手書きしない」というルールは、場当たり的な構造が入り込むのを防ぐためのものであり、スクリプトでは変更できない内容をユーザー確認のもとで修正することまで禁じるものではありません。

---

書き込み前のプレビュー

ファイルシステムに触れる前に、ユーザーに概要を提示します。

• 見つかった新しい制約をカテゴリ別に分類
• 複数のソースによる裏付けで、エビデンスの参照数が増えた制約
• CONFLICTING の項目があれば、すべての主張を並べて表示
• 見つかったニアミスと、その理由を一行で表示 — ここでのみ表示し、CONSTRAINTS.md には決して書き込みません
• 今回の実行で見つかった古い項目や不適切な引用は、削除または修正の対象として理由とともに明示します — 上記の「古い項目と不適切な引用の削除」を参照してください。merge_constraints.py では処理できず、直接編集して明示的に確認する以外に方法がないため、これらにも他のすべての項目と同じく明示的な確認が必要です。

次のように尋ねます。「この内容でよさそうですか？書き込む前に、分類の変更、統合、削除をすべき項目はありますか？」

コンプライアンス境界を誤ることは、別の箇所にある参照ドキュメントの項目を誤るよりも深刻です。差分が小さくても、この手順を省略しないでください。実行の結果、新しい制約が一つもなければ、ファイルを充実しているように見せるために内容を水増しせず、その旨を明確に伝えてください。

---

エージェントの動作ファイルからの相互リンク

プロジェクトルートに AGENTS.md または CLAUDE.md がある場合、対象ファイルに CONSTRAINTS.md を参照する「関連ドキュメント」セクションがすでにあるか確認します。なければ、参照の追加を提案してください。

制約が今後のエージェント実行に役立つのは、エージェントがその存在を把握できる場合に限られます。CONSTRAINTS.md 自体は純粋なリストのままにし、エージェントの動作ファイルには触れないでください。一方、逆方向の参照は必要です。AGENTS.md または CLAUDE.md のいずれかが存在する場合、後からこのプロジェクトで作業するエージェントがコンテキストとして制約を読み込めるよう、制約ファイルを参照する必要があります。

プロジェクトルートで ./AGENTS.md または ./CLAUDE.md が存在するか、記載の順に確認します。./CLAUDE.md が存在していても、その内容が AGENTS.md へのインポート用ポインターにすぎない場合（たとえば、ファイルの内容が実質的に @AGENTS.md だけの場合）は、./AGENTS.md も存在すれば、ポインターファイルではなく AGENTS.md を編集対象とします。どちらのファイルも存在しない場合は、この手順を省略してください。新規作成はこのスキルの対象外です。

対象ファイルが見つかった場合は、まず全体を読み、その後、次の手順に従います。

• ## Related Documentation セクションがすでにある場合は、制約ファイルがその中に記載されているか確認します。パスまたは CONSTRAINTS.md を検索してください。記載済みであれば、ファイルは変更しません。記載がなければ、既存の各項目を一字一句そのまま保ち、そのセクションに項目を一つ追加します。
• そのようなセクションがない場合は、ファイルの末尾に追加します。

項目は次の形式で記述し、CONSTRAINTS.md の部分を制約ファイルの実際のパスに置き換えます。

- **CONSTRAINTS.md** — Externally-imposed boundaries (compliance,
  security, hosting, stakeholder) that shape what this project can build
  and how.
  _(Check this before scoping any change with compliance,
  security, hosting, or stakeholder-priority implications — it is not
  optional background reading)_

補助スクリプトは使わず、通常の文章編集で行ってください。これはファイルごとに一度だけ存在を確認する作業です。大量の並べ替えや重複排除のような継続的な機械処理ではないため、スクリプトを使う根拠はありません。

---

参照ファイル

• references/category-guide.md — 8つの制約カテゴリ、例を使って詳しく説明した強制機能テスト、各カテゴリの対象内・対象外をまとめた表です。ドキュメントごとの抽出を始める前に読んでください。
• references/template.md — 新規ファイル作成時に使用する、最小限の CONSTRAINTS.md のひな形です。8つのカテゴリ見出しだけが含まれ、例となる内容はありません。そのため、初回解析時に実際の項目と誤認されることはありません。
• references/entry-format.md — merge_constraints.py が描画および解析する、CONSTRAINTS.md の項目文法です。実行ごとに一度読んでください。
• references/troubleshooting.md — 抽出および相関処理で生成される JSON の構造、構造の許容処理、マージスクリプトの正確な動作について説明しています。実行で実際に失敗した場合にのみ必要です。