AI 出力フォーマット規約(extract-from-md 用)
これは情報が古いのでextract-from-md v6 仕様書 / エージェント指示 / マニュアルを参照すること。
opus 5バージョン
AI 出力フォーマット規約(extract-from-md 用)
# AI 出力フォーマット規約(extract-from-md 用)
このファイルの内容を、コード生成を依頼するプロンプトの末尾に貼り付けてください。この規約に従った出力は `scripts/extract-from-md.mjs` が **100% 機械的に**ファイルへ復元できます(既定モード `--mode marker` で最優先に解決されます)。
なお、以下の例ではフェンスをチルダ 3 個で書いていますが、実際の出力では **バッククォート 3 個** を使ってください(扱いは同一です)。
---
## プロンプトに貼るテキスト(ここから)
出力は次の規約に厳密に従ってください。説明文よりも規約遵守を優先します。
### 1. 1 ファイル = 1 見出し + 1 コードブロック
~~~## `js/80-split.js`
~~~js// @file: js/80-split.js...ファイルの中身(全文)...// @end~~~~~~
- 見出しは `##` + インラインコードで **相対パスのみ**。連番や説明を付けたい場合は `## 3/7: ` + インラインコードのパス のように、パスをインラインコードで囲む。- コードブロック本文の **1 行目**は必ずファイルマーカー `// @file: <相対パス>`(その言語のコメント記法で)。 - JS / TS / Java / C 系 : `// @file: path/to/a.js` - Python / Shell / YAML : `# @file: path/to/a.py` - HTML / XML / Markdown : `<!-- @file: path/to/a.html -->` - CSS : `/* @file: path/to/a.css */` - SQL : `-- @file: db/a.sql` - JSON(コメント不可) : マーカーを書かず、見出しとフェンス情報で示す (例: フェンス情報を `json title="package.json"` にする)- 最終行に `// @end` を書く(欠けていても動くが、途中切れの検出精度が上がる)。- フェンス情報は `言語` のみ、または `言語 title="相対パス"` のいずれか。
### 2. 途中で切れる場合(分割送信)
1 回の応答に収まらないときは、**必ず**パート宣言を入れる。
~~~## `js/60-model.js`
~~~js// @file: js/60-model.js// @part: 1/3...前半...~~~~~~
次の応答の冒頭は、**説明より先に**続きのブロックを置く。
~~~~~~js// @file: js/60-model.js// @part: 2/3...続き...~~~~~~
- パートは **行の途中で切らない**。必ず行末で区切る。- 最後のパートには `// @part: 3/3` と `// @end` を書く。- 同じファイルを作り直す場合は分割ではなく **全文を 1 ブロックで再送**し、 見出しに `(差し替え・全文)` と明記する。
### 3. 禁止事項
- 応答全体を 1 つの大きなコードブロックで包まない(フェンスの入れ子禁止)。- 1 つのコードブロックに複数ファイルを入れない。- ファイル内容のコードブロックに、説明文・省略記号・`...(中略)...`・ 差分(diff)を混ぜない。**常に完全な全文**を出す。- ファイル本文のコードブロック内に、さらにフェンス(バッククォート 3 個)を 書かない。どうしても必要なら外側フェンスをバッククォート 4 個以上にする。- 見出しやフェンス情報のパスと、`// @file:` のパスを食い違わせない。- 変更点の説明・表・チェックリストは、コードブロックの **外**に書く。
### 4. 推奨(任意)
- 応答の先頭に、その応答で出すファイルの一覧を箇条書きで書く。- パスは常にプロジェクトルート相対(`./` や絶対パス、`..` は使わない)。
## プロンプトに貼るテキスト(ここまで)
---
## パーサ側の対応状況
| 指定方法 | 例 | ソース名 | 既定で採用 ||---|---|---|---|| 本文先頭のマーカー | `// @file: js/a.js`, `// === @file: js/a.js ===` | `marker` | 最優先 || フェンス情報 | `js title="js/a.js"`, `js:js/a.js`, `js [js/a.js]` | `fence` | 2 番目 || 直近の見出し | `## Phase 2 / File 3: \`js/a.js\`` | `heading` | 3 番目 || 直前の段落 | `次のファイル \`js/a.js\` を差し替えます。` | `paragraph` | 4 番目 || 素のコメント | `// js/a.js` | `bare` | `--mode all` のみ |
- パスを含まない見出し(`### 完全版` など)は透過し、直近のパス付き見出しまで遡ります。- `// @import:` / `// @export:` 行はファイルマーカーとして誤認しません。- `@part:` / `@continue` / `@end` は既定で出力から除去されます (`--keep-part-markers` で保持)。
## 運用モード早見表
| やりたいこと | コマンド ||---|---|| 規約準拠の出力だけを厳密に取り込む | `--mode strict-marker` || 既定(マーカー優先、見出しも許容) | `--mode marker` || 見出し主体の古いメモから取り込む | `--mode heading` || とにかく全部拾う | `--mode all` || 特定ディレクトリだけ | `--include "js/**"` || 特定拡張子だけ | `--only-ext js,mjs` || まず確認だけ | `--dry --verbose` || 分割送信を確実に結合 | `--join same-target` || 競合の詳細を見る | `<out>/_report/collisions.jsonl` || 負けた側の中身を見る | `<out>/_superseded/` |要点: 未終端フェンスは既定で「書き出したうえで _report と _suspicious に記録」へ変更(情報を落とさない)。分割された同一ファイルは @part / 未完検出 / 同一ターゲット連続のいずれかで自動結合(ファイル跨ぎ可)。lang=md 以外のコンテナも展開対象。競合は後ろ勝ち+負け側を _superseded/ に保全し、勝者・敗者の md と行範囲・sha256・内容一致有無をログと collisions.jsonl に出力。全ブロックは必ず 1 つの disposition に分類され、総数が合わなければ終了コード 3 で異常を知らせる。
opus 4.7バージョン
LLM への出力形式指示テンプレ
extract-from-md.mjs が最も安定してパースできる形式で、コードを出力させるための指示文です。system プロンプトまたは user プロンプトの末尾に貼ってください。
出力ルール(厳守)
コードは必ず 「見出し + フェンス済みコードブロック + 先頭マーカー」 の三点セットで出力してください。1 ファイル = 1 セットです。分割・省略・要約は禁止です。
形式
## `relative/path/to/file.ext`
```<lang>// === @file: relative/path/to/file.ext ===<ファイルの完全な内容>```ルール詳細
- 見出しは必ず
##(H2) を使い、パスをバッククォートで囲むこと。- 例:
## `src/utils/foo.js`
- 例:
- コードブロックは必ず
```三連バッククォートで開閉すること。言語タグ (js,ts,py,html,css,json…) を必ず付けること。 - コード本体の 1 行目に、その言語のコメント記法で
@file: <パス>マーカーを書くこと:- JS / TS / CSS / Rust / Go :
// === @file: path/to/file.ext === - Python / Shell / YAML :
# === @file: path/to/file.ext === - HTML / XML / Vue :
<!-- === @file: path/to/file.ext === --> - SQL / Lua / Haskell :
-- === @file: path/to/file.ext ===
- JS / TS / CSS / Rust / Go :
- パスは 相対パスのみ。先頭
./は不要。..や絶対パスは禁止。 - 1 つのファイルは 1 つのコードブロックにまとめること。途中で説明を挟んで分断しない。省略記号 (
...) 禁止。 - ファイル間の説明文はコードブロックの外に置く。コードブロック内には実行可能な完全なファイル内容だけを書く。
- Markdown ファイル自体を出力する場合はフェンスを
~~~(チルダ 3 個) にしてネストに配慮すること。
良い例
## `src/hello.js`
```js// === @file: src/hello.js ===export function hello() { return "hi";}```悪い例(パーサが誤解する / 取りこぼす)
- 見出しなし、マーカーなしのコードブロック
- 1 ファイルを複数コードブロックに分割
- コードブロック内に
...で省略 - パスをコードブロックの後ろに書く
- 言語タグ省略
- コードの前後に「以下がファイルです」等の散文だけ書いてパスを明示しない
なぜ二重宣言(見出し + マーカー)が必要か
- 見出し はチャット全体の目次として人間が読みやすく、レポート生成や差分レビューに便利。
- マーカーコメント はコード本体に含まれるため、コードブロックだけコピペされてもファイル名が失われず、後日の再パースにも耐える。
- どちらか片方が壊れても、もう片方から復元できる冗長性を確保できる。
```markdown# extract-from-md.mjs 使い方
Markdown(AI 出力・設計メモなど)に含まれるコードブロックを、対応するファイルとしてディスクへ書き出すツールです。
## クイックスタート
```bash# 単一ファイルnode scripts/extract-from-md.mjs message.md --out ./out
# ディレクトリ再帰、既定モード (loose)node scripts/extract-from-md.mjs ./messages --out ./out
# 事前確認 (書き込みしない)node scripts/extract-from-md.mjs ./messages --out ./out --dry
# LLM 向けの推奨出力形式プロンプトを取得node scripts/extract-from-md.mjs --emit-prompt > prompts/output-format.md
# モード一覧を確認node scripts/extract-from-md.mjs --list-modesモード比較
| モード | 未解決ブロック | 軽微な競合 | 出力衝突 | 主用途 |
|---|---|---|---|---|
strict | 隔離 | 隔離 (failure) | 後勝ち + 敗者隔離 | CI / 厳格運用 |
loose (既定) | 隔離 | 書き込み + _suspicious/ にコピー | 後勝ち + 敗者隔離 | 通常運用 |
explicit-only | 隔離 | (source が fence/inline のみなので発生しにくい) | 後勝ち + 敗者隔離 | 散文とコードが混在する場合 |
permissive | 隔離 (パス候補なしのみ) | 書き込み | 後勝ち + 敗者隔離 | 乱れたダンプからの一括復旧 |
- 未解決: fence / inline / heading / paragraph のいずれからもパスが推定できない場合。
- 軽微な競合: 複数のソースが異なるパスを主張する / 言語タグと拡張子が食い違う / 本文が短すぎる など。
- 出力衝突: 別のブロックが既に同じ出力先へ書き込んだ場合。
隔離フォルダ
出力先ルート配下に以下が作られます (--quarantine-dir で接頭辞変更可):
_failed/: 書き出せなかったブロック + レポート +index.md_suspicious/: 書き出したが要確認のブロック + レポート +index.md_collisions/: 後勝ちで敗れたブロック + レポート +index.md+collisions.md
collisions.md は「勝者 md / 行 / sha256」と「敗者 md / 行 / sha256」のペアを一覧にします。どのファイル同士がぶつかったかを 1 画面で把握できます。
パス解決の仕組み
以下の 5 種類のソースから、--priority で指定した順に最初に見つかったものを採用します。既定 (loose) は fence > inline > heading > paragraph > inline-bare です。
| ソース | 例 |
|---|---|
fence | ```js title="src/a.js" / ```js:src/a.js |
inline | コード先頭付近の // === @file: src/a.js === |
heading | 直近の見出し ## \src/a.js“ |
paragraph | フェンス直前の段落内のインラインコード `src/a.js` |
inline-bare | キーワードなしの素コメント // src/a.js |
explicit-only モードでは heading / paragraph / inline-bare を無視するため、散文中の紛らわしい記述に釣られません。
LLM に安定して出力させるには
--emit-prompt で得られるテンプレを system / user プロンプトに貼ってください。要点は:
- コードブロックの直前に
## `path/to/file.ext`見出しを付ける - コードの 1 行目に
// === @file: path/to/file.ext ===などのマーカーを入れる - 1 ファイル = 1 コードブロックにまとめる (省略禁止)
見出しとマーカーの 二重宣言 により、片方が壊れてももう片方から復元でき、パーサの取りこぼしを最小化できます。
トラブルシューティング
- 途中で切れる: 出力側 LLM が同じファイルを複数コードブロックに分割している可能性。
_failed/index.mdを確認し、--emit-promptのテンプレを LLM に渡す。 - ファイル自体が出ない: 見出しがネストされた markdown ブロック内にあり、外側のパーサから見えていない可能性。
--max-depthを増やす、または LLM に「外側フェンスは~~~を使え」と指示する。 - 想定と違うファイルに書かれる:
_suspicious/index.mdの Reasons 欄で「どのソースが競合したか」を確認。--mode explicit-onlyに切り替えて散文由来を無視する。 - 衝突が多発:
_collisions/collisions.mdで勝敗ペアを確認。LLM が同じファイルを何度も出している場合が多い。
以上が v3 一式です。v2 からの重要挙動変更点を再掲:
- `--mode loose`(既定)で suspicious は原則書き込み、コピーが `_suspicious/` に残る- 出力先衝突時は後勝ち+敗者を `_collisions/` に隔離、`collisions.md` に勝敗ペア記録- `usedHeadings` 撤廃により同一見出し配下の複数ブロックが正しく解決- `matchKeywordedMarker` で `import`/`export` 等の JS 予約語行を誤検出しないよう強化- `--emit-prompt` で LLM 向け推奨出力形式テンプレを標準出力