このブログの筆者をごんべえと呼ぶ。
作業そのもの——コマンドの実行やコードの書き換え——は大半を Claude 側で進めたが、いくつかの点はごんべえの判断が必要だった。その記録を残しておく。
やったこと
- Astro を 4系から 7系へメジャーアップデート
- Content Collections を Content Layer API へ移行
npm audit で出ていた脆弱性の対応- デプロイ先（Cloudflare Pages）の Node バージョン固定
- 生成AIとの共作をどう開示するかの仕組み化
以下、特に判断が要ったポイントを挙げる。
メジャーを2つ飛ばす移行
4→7 なので、間の v5・v6・v7 の破壊的変更をまたぐことになる。特に効いたのが v5 での変更で、Content Collections が Content Layer API に置き換わっている。
具体的には、
- 設定ファイルの置き場所が
src/content/config.ts から src/content.config.ts へ変わった
- コレクションの取得に
glob() ローダーの指定が必要になった
- エントリの
slug プロパティが id に変わった
あたりである。詳細は公式のアップグレードガイドとローダーのリファレンスにまとまっている。
メジャーを飛ばす場合は間のガイドを全部たどる必要がある、という当たり前の点だが、ここは省略できなかった。
脆弱性を「直さない」と決める
npm audit の警告は最初 23 件出ていて、対応後に 6 件まで減った。この残り 6 件は、直さないという結論になった。
残っていたのはビルド時にしか使わない開発依存（言語サーバや Cloudflare アダプタが引いている picomatch や yaml-language-server など）由来のもので、本番の出力には含まれない。これらは npm audit fix --force で無理に潰すと、逆に Astro 側に破壊的変更が入ってしまう。
この点は Astro 側でも把握されていて、issue に経緯と方針が書かれている。
Claude は当初、overrides で依存バージョンを強制的に上書きして警告を潰す案を出した。しかしこの公式スタンスを確認したうえで、本番に影響しない dev 依存を無理に上書きするのはやめ、overrides は外すことにした——この「直さない」判断はごんべえが決めている。警告がゼロになることと安全になることは別で、ここは機械的には決められない部分だった。
Node のバージョンをどれにするか
ローカルではビルドが通っていたが、Cloudflare Pages 側のデプロイが Node.js v18.17.1 is not supported by Astro! で失敗した。Astro 7 は Node 22.12 以上を要求する。
Cloudflare Pages はリポジトリに .nvmrc（または .node-version）を置くと、そのバージョンでビルドしてくれる。
では何を書くか。2026年7月時点で、Node は 24 が Active LTS、22 が Maintenance LTS である。
22 でも要件は満たすが、ごんべえのローカル開発環境が Node 24 だったため、環境を揃える意味で .nvmrc には 24 を採用した。「動く最低ライン」で選ぶか「ローカルと揃える」で選ぶかの判断で、後者を選んだ形になる。
既存記事の改行を壊さない
移行に伴って Markdown のデフォルト挙動が変わり、そのままだと本文中の改行（<br>）が効かなくなっていた。過去記事はこの改行挙動に依存して書かれているので、崩れると全記事に影響が出る。
対応として remark-breaks を明示的に追加し、これまで通り改行が反映されるようにした。既存の資産を壊さないという観点は、差分だけを見ていると見落としやすい。
AI 共作の開示を仕組み化する
今回のように AI との共作で記事を書くなら、「どこまでを AI がやったか」を読者に開示したい。ただ、それを毎回本文にべた書きすると手間だし、書きぶりがぶれて一貫性も落ちる。
そこで、開示を仕組みに逃がした。記事の frontmatter に任意項目 coauthor を持たせ、投稿レイアウトが、値があるときだけ定型の注記を自動で出すようにした。
- スキーマ（
src/content.config.ts）に coauthor: z.string().optional() を追加
- 投稿レイアウト（
BlogPost.astro）で、coauthor があれば「🤖 ◯◯との共作記事」と表示
これで、共作記事は frontmatter に coauthor: 'Claude Code' と1行足すだけで開示が付く。実際、この記事の冒頭に出ている共作の注記も、この仕組みが出している。仕組み化すること自体は Claude が提案したが、「今この土台更新のついでに入れておく」と決めたのはごんべえである。
さらに、テキストの注記だけでは「どこからどこまでを AI が書いたか」が塊として分かりにくい。そこで、範囲を視覚的に囲むことにした。
ここで技術的な壁がある。Markdown 本文を <div> で囲むと、中の Markdown が生の HTML 扱いになってレンダリングされない。囲みたいなら MDX にする必要がある。そのためこの記事を .md から .mdx に変え、AI 執筆範囲を囲む専用コンポーネント AiAuthored を用意した。いま読んでいる、ラベル付きのこの枠がそれである。
「視覚的に囲みたい」という要望はごんべえ、Markdown では囲めないので MDX 化が要るという切り分けと実装は Claude、という分担で進めた。