JSONの改行エスケープ問題をbody.md分離で解決した話｜AI編集が確実に動くようになった

変更前：

articles/my-article/
└── article.json  ← メタデータ + body（全部入り）

変更後：

articles/my-article/
├── article.json  ← メタデータのみ
├── body.md       ← 本文Markdownのみ
└── eyecatch.svg

article.jsonにはtitle・slug・publishedAt・categorySlug等のメタデータだけを持たせます。bodyフィールドは削除します。

{
  "title": "記事タイトル",
  "slug": "my-article",
  "publishedAt": "2026-04-25T09:00:00.000Z",
  "categorySlug": "practice-log",
  "topicSlugs": ["tag1", "tag2"],
  "seoTitle": "SEOタイトル",
  "seoDescription": "説明文",
  "seoKeywords": "キーワード1,キーワード2"
}

body.mdには純粋なMarkdownを書きます。JSONエスケープは一切不要です。" も \n も気にせずそのまま書けます。

この設計にすることで、AIがbody.mdを差分修正するときにJSONエスケープの問題が発生しなくなります。Markdownファイルはテキストファイルなので、oldTextがそのまま一致します。

---

post.mjsへの実装手順（数行の追記で対応）

投稿スクリプト（post.mjs）にbody.mdを読み込む処理を追加します。以下の数行を追記するだけです。

既存コードでarticle.jsonを読み込んでいる箇所の直後に追記します。

const article = JSON.parse(fs.readFileSync(articlePath, 'utf-8'))

// body.mdが存在すれば article.body を上書き（分離管理対応）
const bodyMdPath = path.join(articleDir, 'body.md')
if (fs.existsSync(bodyMdPath)) {
  article.body = fs.readFileSync(bodyMdPath, 'utf-8')
  console.log(`📝 body.md を読み込みました`)
}

この追記により、body.mdが存在する記事はbody.mdの内容が本文として使われます。body.mdがない記事はarticle.json内のbodyフィールドが従来通り使われます。後方互換性があるため、既存記事への影響もありません。

既存記事の移行手順：

1. 該当フォルダにbody.mdを新規作成する
2. article.jsonのbodyフィールドの値をコピーする
3. 上記のVSCode正規表現置換で \n を実際の改行に変換する
4. body.mdに貼り付けて保存する
5. article.jsonのbodyフィールドを削除する

移行後は、AIに「body.mdを差分修正してください」と依頼するだけで、エスケープ問題なく編集できるようになります。

---

この後どうなったか（継続記録）

body.mdへの分離後、AIによる記事の差分修正が安定して動くようになりました。「exact match が見つからない」というエラーはほぼ出なくなっています。

新規記事はbody.mdで書く運用に統一し、記事ごとのフォルダ構成もシンプルになりました。記事本文の管理としても、Markdownファイルをそのまま開いて読めるので確認しやすくなっています。

課題として残っているのは、既存記事のbody.mdへの移行です。記事数が増えるほど手作業のコストがかかります。現時点では新規記事から順次対応しています。

---

よくある質問

Q：body.mdのMarkdownはどんな記法が使えますか

## 見出し・**太字**・箇条書き（-）・番号付きリスト（1.）・コードブロック（\\\`）がそのまま使えます。JSONエスケープが不要なので、ダブルクォートや改行を気にせず書けます。

Q：article.jsonにbodyを残したままbody.mdも作るとどうなりますか

post.mjsの実装では、body.mdが存在する場合にarticle.jsonのbodyフィールドを上書きします。つまりbody.mdが優先されます。移行期間中は両方あっても動作しますが、混乱を避けるためにarticle.jsonのbodyは削除することをお勧めします。

Q：AIによる差分修正の安定性はどのくらい改善しましたか

体感では大幅に改善しました。修正前は10回中5〜6回程度エラーが出ていましたが、body.md分離後はほぼエラーが出なくなっています。ただし現時点では正確な計測はしていません。

---

まとめ

JSONに本文を埋め込む設計は、AIによる差分修正と相性が悪いです。\n エスケープの解釈の違いがoldTextのマッチ失敗を引き起こします。

解決策はシンプルで、body.mdとして本文を分離することです。post.mjsへの数行の追記と、VSCodeの正規表現置換を使った移行作業で対応できます。

今日できる一歩は、次に作る記事からbody.mdで本文を管理することです。それだけでAIとの編集作業が安定します。

この記事のファイル設計の判断は、何をどう分けるかという構造設計の考え方とつながっています。設計の判断軸を体系的に整理したい方は、bizinets.biz の判断軸ページが参考になると思います。判断軸について