Claude CodeでAstroブログを作る — インストールから執筆までの最短手順

Astroは、ブログやドキュメントサイトなどのテーマが公式に用意されているWebフレームワークで、公式のcreate astroコマンドが最短の立ち上げ手段です。ここではClaude Codeのターミナルから同じコマンドを叩き、ページの追加やプロジェクト規約の固定までをひと続きで進める手順を扱います。

Astroとは何か、なぜClaude Codeと組むのか

Astro公式のテーマ集には、ブログやポートフォリオ、ドキュメントサイト、ランディングページ向けのテンプレートが並びます。ブログはAstroが想定する主要な用途のひとつです。

骨格はcreate astroウィザードが作ってくれます。残る「記事ページを増やす」「設定ファイルを整える」という反復作業をClaude Codeに任せる組み合わせが向いています。Claude Codeはターミナルで動くAIコーディングアシスタントで、プロジェクトのファイルを読み込みながら会話形式でコードを編集します。本稿はCLIでの利用を前提にします。

前提条件 — Node.jsのバージョンとエディタ

Astroのインストールには次の環境が必要です。

Node.jsのバージョンはnode -vで確認できます。奇数バージョンは公式が非対応としているので、先に偶数バージョンのLTSへ切り替えておきます。

Claude Codeをインストールしてログインする

Claude Codeがまだ無い場合は、ネイティブインストーラーでセットアップします。

curl -fsSL https://claude.ai/install.sh | bash
claude --version

インストール後に新しいターミナルを開いてclaude --versionを実行すると、バージョン番号が表示されます。v2.1.289で実行した出力は次のとおりです。

2.1.289 (Claude Code)

claudeコマンドが見つからない場合は、インストール先がPATHに入っていません。初回のclaude起動ではブラウザでのログインを求められ、Pro・Max・Team・EnterpriseのいずれかのサブスクリプションかConsole(API)アカウントで認証します。OSごとの詳しい手順はClaude Code install完全ガイドにあります。ログイン方式の違いはClaude Codeログイン方法3種の使い分けが参考になります。

ウィザードか手動セットアップか — 状況別の選び方

Astroの立ち上げ方は大きく2種類あり、どちらもClaude Codeのターミナルから実行できます。

手動の場合、公式ガイドは空のディレクトリを作って移動し、npm init --yesでpackage.jsonを作ってからAstroを入れる順序を示しています。ここから先の手順は、どちらの方法で作ったプロジェクトでも共通です。

create astroでプロジェクトを作成する

create astroはどこで実行してもよく、空のディレクトリを事前に用意する必要はありません。空のディレクトリがなければ、ウィザードが作成を手伝います。

npm create astro@latest

対話式のウィザードが、プロジェクト名やテンプレート、依存関係のインストール、Gitリポジトリの初期化などを順に尋ねます。成功すると成功メッセージと次のステップが表示されます。

選択式の画面は対話入力を前提としています。Claude Codeのセッション内で入力しづらいときは、自分のターミナルで直接実行し、できあがったディレクトリにcdしてからClaude Codeへ引き継ぎます。

ウィザードの種類によっては、AIエージェント向けのファイルが作られることがあります。作りたくない場合は--no-aiを付けます。このフラグはAstro公式ドキュメントのCLIページではなく、create-astroのREADMEに載っています。生成直後にプロジェクト直下のファイル一覧を見ておくと、Claude Codeが読むファイルを把握できます。

全質問に既定値で答えたい場合は--yes(-y)を付けます。Gitの初期化は--gitと--no-git、依存関係のインストールは--installと--no-installで選べます。ReactやPartytownなどの統合を最初から入れたいときは--addが使えます。

npm create astro@latest -- --add react --add partytown

GitHub上の既存テーマを土台にするなら--templateに<GitHubユーザー名>/<リポジトリ名>を渡します。既定ではそのリポジトリのmainブランチが使われ、別ブランチは<GitHubユーザー名>/<リポジトリ名>#<ブランチ名>の形式で指定します。

npm create astro@latest -- --template <github-username>/<github-repo>

Claude Codeに最初のブログページを作らせる

プロジェクトができたら、ディレクトリにcdしてClaude Codeのセッションを開始します。

cd my-astro-blog
claude

最初は、コードを触る前に「このプロジェクトの構成を説明して」「ページはどこに置く?」と聞いてみます。生成直後の空のプロジェクトでも、どこに何を書けばよいかがすぐ分かります。Claude Codeはプロジェクトのファイルを自分で読み込むので、内容を貼り付ける必要はありません。

Astroのページはsrc/pages/配下のファイルがそのままルーティングになります。Astro公式の手動セットアップが示すsrc/pages/index.astroは、シンプルな1ファイルです。---で囲んだフロントマター部分(ビルド時にのみ実行されるコード)と、その下のHTMLテンプレートで構成されます。ウィザードで選んだテンプレートによっては中身が異なるため、最初にファイルを開いて確かめます。この構造を土台に、自然言語でページ追加を指示します。

src/pages/blog/にmy-first-post.astroという新しいページを作って。
index.astroと同じ構造で、見出しと本文の段落を1つ持たせて。

Claude Codeは対象ファイルを探し、変更内容を提示します。変更を承認するかどうかは、セッションの権限モードで決まります。

v2.1.283以降では、対話式のターミナルセッションの既定がauto modeです。分類器が操作を審査し、多くのファイル編集やコマンド実行は確認なしで進みます。それより前のバージョンでは、auto modeが既定になるのはPro・Max・Teamプランで、機能フラグを取得するセッションに限られていました。

claude --helpには、--permission-modeで指定できる値が次のように表示されます。

--permission-mode <mode>   Permission mode to use for the session
                           (choices: "acceptEdits", "auto",
                           "bypassPermissions", "manual",
                           "dontAsk", "plan")

モードはShift+Tabでセッション中にも切り替えられます。最初の1回だけ慎重に進めたいなら、claude --permission-mode manualで起動する方法があります。manualは、ファイル編集やシェルコマンドの実行、ネットワークへのアクセスといった操作の前に承認を求めるモードで、ファイルの読み取りは承認なしで進みます。manualの指定にはClaude Code v2.1.200以降が必要です。

フラグの使い分けはClaude Codeの--permission-modeフラグに詳しくあります。auto modeが何を止めるかは、Claude Codeのauto mode分類器は何を止めているかにまとまっています。

あとからインテグレーションを追加する

作成時に--addを付け忘れても、後から足せます。Claude Codeに「Reactを使えるようにインテグレーションを追加して」と伝えるか、既存プロジェクトのディレクトリでastro addを直接実行します。--addは公式・コミュニティ双方のインテグレーションのうち、astro addに対応したものを扱います。

npx astro add react

依存関係のインストールと設定ファイルへの反映が1コマンドで済みます。Claude Codeのセッション内で実行させれば、astro.config.mjsへの追記まで含めて結果を見ながら進められます。

プロジェクトの規約をCLAUDE.mdに固定する

セッションをまたいで同じ指示を繰り返さないために、プロジェクト直下で/initを実行してCLAUDE.mdを生成します。

/init

Claude Codeがコードベースを解析し、ビルドコマンドやテスト方法、見つかった規約を含むCLAUDE.mdを作ります。すでにCLAUDE.mdがある場合、/initは上書きせず改善案を提示します。

環境変数CLAUDE_CODE_NEW_INITを1にしてから/initを実行すると、対話式の流れになります。CLAUDE.mdに加えてスキルやフックも作るかを尋ね、コードベースを調べたうえで、ファイルを書く前に提案を見せてくれます。

生成直後のAstroプロジェクトはファイル数が少ないので、/initが拾う規約はまだ薄めです。次の内容を手で書き足しておくと、以降のセッションで指示がぶれにくくなります。

• npm run dev・npm run build・npm run previewの役割
• ページを追加する場所(src/pages/配下)
• インテグレーションはastro addで入れるという方針

CLAUDE.mdの書き方を型にした記事はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンです。

ビルドしてローカルプレビューする

Astroの標準的なpackage.jsonには、dev・build・previewの3つのスクリプトが入ります。

npm run dev

開発サーバーを動かしているターミナルでは、o+Enterでブラウザが開き、q+Enterで終了します。s+Enterはコンテンツレイヤーのデータ(コンテンツと型)を同期します。ポートを変えるときは、スクリプトの後ろに--を挟んでフラグを渡します。

npm run dev -- --port 8080
npm run build -- --verbose

2行目のように、ビルドに--verboseを付けるとログが詳しくなります。Claude Codeにページを追加させたあとは、「npm run buildを実行してエラーが出ないか確認して」と伝えると、ビルドの成否まで任せられます。ページ追加のたびにこの確認を挟めば、壊れたページに気づかないまま進むことを防げます。

よくあるつまずき

Node.jsの奇数バージョンを使っている

v23のような奇数バージョンのNode.jsは、Astroが非対応としています。node -vで確認し、v22.12.0以上の偶数系LTSに切り替えます。

Astroをグローバルインストールしてしまう

手動セットアップでは、npm install astroのようにプロジェクトのローカルへ入れるのが公式の手順です。npm install -g astroのようなグローバルインストールは避けます。

ウィザードで依存関係のインストールをスキップした

「Install dependencies?」で「いいえ」を選んだ場合は、依存関係が入っていない状態です。npm install(pnpm・yarnならそれぞれのコマンド)を別途実行してからnpm run devを試します。

--templateのブランチ指定を忘れる

GitHubリポジトリをテンプレートに使うと、既定ではmainブランチが対象になります。別ブランチを使うときは<github-username>/<github-repo>#<branch>のように#でブランチ名を続けます。

まとめ

Astroブログの土台はnpm create astro@latestで作り、ページ追加とビルド確認をClaude Codeに任せる分担が最短です。作業が2回目以降のセッションに入る前に、/initで作ったCLAUDE.mdへスクリプトの役割とページの置き場所を書いておくと、同じ説明を繰り返さずに済みます。