Astro（静的サイト生成に強いWebフレームワーク）でサイトを構築していて、ビジュアルエディタの導入を検討したことがある方に向けた内容です。管理画面上で要素をクリックして編集すると、その裏でCMS（コンテンツ管理システム）のデータベースに書き込まれ、実際の.astroファイルとは別の場所に「もう一つの正解」が生まれる。この構造に違和感を持ったことがあるなら、今回紹介する@sudodevstudio/astro-aiの設計思想は参考になるはずです。
このツールは開発時専用のAstroインテグレーション（Astroの機能拡張の仕組み）です。特徴は、ブラウザ上で選んだ要素の編集が、それを描画した元の.astroファイルに直接書き込まれる点にあります。CMSやエディタ専用フォーマットという「第二のソース」を作らない設計です。
何が問題だったのか
一般的なビジュアルエディタは、コンテンツをCMSに移し、レイアウトをエディタ独自の形式に移す取引を読者に求めます。
この取引には代償があります。コードで管理していたサイトに別の表現形式が加わると、手動編集とビジュアル編集のどちらが優先されるかという未解決の問いが常につきまといます。
次のビジュアル編集で手動編集が上書きされないか。競合したときにどちらが勝つのか。こうした疑問に答え続ける運用コストは、意外と軽視されがちです。
astro-aiはこの問題を、ビジュアル編集と手動編集が同じソースファイルを操作する形で回避します。ビジュアル編集は通常のソース変更として扱われ、手入力の変更と同じdiff・同じプルリクエストに現れます。
仕組みを段階的に見る
導入はシンプルです。開発依存としてパッケージを追加し、Astroの設定ファイルにインテグレーションを登録します。
npm install --save-dev @sudodevstudio/astro-ai// astro.config.mjs
import { defineConfig } from 'astro/config';
import buildWithAI from '@sudodevstudio/astro-ai';
export default defineConfig({
integrations: [
buildWithAI({ agent: 'codex' }), // or 'claude'
],
});開発サーバーを起動し、Astroの開発ツールバーから「Build with AI」を開いて要素を選択するだけで使えます。agentオプションは省略も可能で、その場合はAI連携なしの決定的編集（deterministic editing、結果が一意に決まる機械的な変換）のみが有効になります。
AI機能を使う場合は、Codex CLIならcodex login、Claude CLIならclaude起動時のログインフローで事前に認証を済ませておく必要があります。認証情報はCLIの資格情報ストアに保持され、ブラウザ側のコードには一切送信されません。
見出しのテキストを編集すると、実際には以下のような差分が生成されます。
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -1 +1 @@
-<h1 class="hero-title">Build something useful</h1>
+<h1 class="hero-title">Build something people use</h1>テキストだけが変わり、class属性や周囲のコードはそのまま保持されます。Vite（高速なビルドツール）のHMR（Hot Module Replacement、変更を即座に画面反映する仕組み）によって、更新後のソースがすぐに描画されます。
内部では、開発中に.astroファイルを@astrojs/compiler-rsで、.jsx/.tsxファイルをBabel（JavaScriptのコード変換ツール）でパースしています。対応する要素にはdata-astro-ai-*という属性が付与され、描画されたDOMノードとファイルパス・ソース範囲を紐づけます。
編集を確定する前には、対象ファイルが検査時と同じ内容であるかを確認し、変換後のコードを再パースするチェックが入ります。これにより、古い選択情報に基づく編集や、構文エラーを生む変換を弾きます。
決定的編集とAIの役割分担
このツールの設計で重要なのは、機械的に処理できる編集と、判断を要する編集を明確に分けている点です。
テキストの変更、既存propの設定、互換性のある兄弟要素の並べ替え、要素の削除・挿入といった操作は、正解が一つに定まります。こうした操作にはAIモデルへのリクエストが発生せず、トークンコストもかかりません。ソース変換のルールが決まっているため、ローカルで処理が完結します。
一方、「このセクションをレスポンシブにする」といった要求は、構造・スタイル・コンポーネント境界にまたがる判断が必要です。「なぜこの要素が二重に描画されるのか説明して」という質問も、DOM情報だけでは答えが出ません。こうしたリクエストは、認証済みのCodexまたはClaude CLIに送られます。
エージェントは.gitignoreと追加のexcludeDirectoriesでフィルタされた一時的なプロジェクトコピー上で作業します。AGENTS.mdのようなプロジェクト規約ファイルをskillsとして渡すことも可能です。
buildWithAI({
agent: { provider: 'claude', model: 'your-model' },
excludeDirectories: ['vendor', 'src/generated'],
skills: ['AGENTS.md'],
});他の選択肢との位置づけ
ContentfulやSanityのようなヘッドレスCMSは、非技術者の編集者が多く関わる大規模な編集ワークフローに向いています。コンテンツとコードを分離することで、専門知識のない担当者でも安全に更新できる設計です。
一方、すでにコードベースでサイトを管理しているチームにとっては、CMS導入自体が新たな同期コストになります。astro-aiはこの層を狙っており、非技術者向けの編集基盤ではなく、開発者がローカルで素早く見た目を調整するためのツールという位置づけです。
Astro公式のContent Layer APIやMarkdown/MDXベースの管理と比較しても、astro-aiはファイル構造そのものを変えない点が異なります。既存のプロジェクト構成に手を加えずに導入できるのは、移行コストを抑えたいチームにとって現実的な利点です。
今日確認できること
導入を検討する前に、次の点を確認しておくと判断しやすくなります。
- Astroのバージョンが@astrojs/compiler-rsに対応しているか、package.jsonのastro依存バージョンを確認する
- 編集対象がリテラルなテキストやprop中心か、それとも配列mapで生成される動的要素が多いか（後者は独立したソース単位とみなせず、対応が制限される）
- CodexまたはClaude CLIのログイン状態と、利用中のモデルプランでコストが許容範囲か
- .gitignoreの構成が、AIエージェントに渡したくないディレクトリ（機密設定やvendorコード）を正しく除外できているか
特に配列のmap内で生成される要素（例: {items.map((item) => <a href={item.url}>Read more</a>)}）は、単一の描画要素が独立したソース単位に対応しないケースとして、決定的編集の対象外になる場合があります。自分のプロジェクトのコンポーネント構造がこのパターンに近いかどうか、事前に確認しておく価値があります。
まとめ
astro-aiは、ビジュアル編集とコード管理を同じソースファイル上で統合する試みです。
機械的な編集はローカルの決定的処理で完結させ、判断を要する編集だけをAIエージェントに委ねる設計は、トークンコストと編集の予測可能性を両立させる工夫として参考になります。
導入を検討する際は、まず開発環境で小さなAstroページに対してnpm installと設定追加を試し、テキスト編集がdiffとしてどう反映されるかを確認するところから始めるのが現実的です。
コンポーネント構造が複雑な既存プロジェクトでは、どの要素が決定的編集の対象になるか、動的なmap生成部分がどう扱われるかを先に洗い出しておくと、導入後の戸惑いを減らせます。