非エンジニアがClaude Codeでコーポレートサイトを作って運用している話

こんにちは、HRdevの永井です。

HRdevのコーポレートサイト（hrdev.jp）は、Next.js（Webサイト構築用のフレームワーク）で構築しています。デザイン、実装、テスト、デプロイまで、Claude Codeと一緒に作りました。

「AIにサイトを作らせた」と書くと簡単に聞こえるかもしれません。実際には、MDX（Markdownの拡張版）の構文エラーが12記事に波及した事故も、手元のPCでは動くのにVercel（Webサイトを公開・運用するサービス）で落ちるビルドエラーとの格闘もありました。うまくいった話だけでなく、ぶつかった壁と、それをどう乗り越えたかを書きます。

正直に言うと、始める前も今も、『WordPressやnoteで十分だったのでは』と何度も思いました。コーポレートサイトもブログも、既存のSaaSを使えば半日で立ち上がるし、コストも時間も圧倒的に少ない。車輪の再発明という言葉がずっと頭をよぎります。それでも続けているのは、AIで開発プロセスを組み直すこと自体に興味があったからです。（楽しい）

サイト構築の全体像

hrdev.jpはNext.js 14で構築しています。ブログ記事はMDX形式で管理し、コンテンツの執筆はhrdev-blogリポジトリ（ファイル管理の倉庫）で行い、GitHub Actions（GitHubに付属する自動化機能）で自動的にコーポレートサイトに同期される仕組みです。

この「記事を書いたら自動でサイトに反映される」パイプラインの構築に、Claude Codeが全面的に関わっています。

具体的にClaude Codeが担当した領域を挙げると、Next.jsのプロジェクトセットアップ、MDXコンポーネントの設計、ブログ一覧・記事詳細・タグページの実装、GitHub Actionsによる記事自動同期スクリプトの作成、Playwright（ブラウザ操作を自動化してテストするツール）を使ったE2Eテスト（利用者の操作を模擬して動作を確認するテスト）の導入、Vercelへのデプロイ（サイトを公開する作業）設定と問題解決です。

自分が担当したのは、要件の定義、デザインの方向性の指示、レビューと最終判断。コードを直接書いたのはほぼClaude Codeです。

「PRDを先に書く」ルールが機能した

Claude Codeとの開発で最初に決めたルールがあります。コードを書く前に、必ずPRD（Product Requirements Document、要件定義書）を作成すること。

PRDといっても大げさなものではありません。目的（なぜやるのか）、スコープ（何をやるか・やらないか）、受け入れ条件（完了の定義）、影響範囲（既存機能への影響）。この4つを書き出してから、実装に入ります。

たとえばブログのタグ機能を作るとき、こう書きました。目的はカテゴリごとに記事を絞り込めるようにすること。スコープはタグ一覧ページとタグフィルタの実装。やらないことはタグの階層構造やタグの編集UI。受け入れ条件はタグをクリックすると該当記事だけが表示されること。影響範囲は記事一覧ページのレイアウトに変更あり。これだけ書いておけば、AIが勝手にタグの管理画面まで作り始めることはありません。

なぜこのルールを入れたかというと、「AIにお願い」するだけだと意図しない変更が入りやすいからです。「ブログページを作って」と言えば作ってくれますが、タグ機能もページネーション（ページ送り機能）も関連記事も、聞いていない機能を勝手に足してくることがあります。スコープを事前に定義しておかないと、レビューで「これは頼んでいない」と差し戻す手間が増える。

PRDを書く作業そのものが、自分の要件を整理する時間になっています。「何がほしいか」を曖昧なまま伝えると、AIは曖昧なものを返してくる。当たり前の話ですが、やってみて痛感しました。

コミット前に4つのチェックを必ず通す

Claude Codeでの開発は速い。速いからこそ、品質のゲートを厳格に設けています。

HRdevでは、開発に関わるコミット（変更内容を手元の履歴に保存する操作）を作成する前に4つのチェックを必ず通します。

1つ目はビルド確認。npm run build（公開用のファイルを生成するコマンド）が通ること。2つ目は手元のPCでの動作確認。開発用サーバーを起動して、変更した機能がブラウザで正しく動くことを目視で確認。3つ目はE2Eテスト。Playwrightで書いたテストを全件実行し、1件でも落ちたらコミットしない。4つ目はレビュー。これは後述します。

この4つを全部パスしてから、はじめてコミットします。Claude Codeは速くコードを書いてくれますが、速く壊すこともできる。ゲートを設けることで、壊れた状態がリポジトリに入り込むのを防いでいます。

E2Eテストの導入は早い段階で入れました。コーポレートサイトのブログ機能に対して、記事一覧の表示、記事詳細ページの表示、タグによるフィルタリングなどをPlaywrightで検証しています。

AIが生成したコードは「動く」けれど、表示崩れやリンク切れなど「目で見ないとわからない」不具合を見落とすことがあります。E2Eテストは、その見落としを機械的に検出するための仕組みです。

自動syncで12記事に構文エラーが波及した事故

ブログ記事はhrdev-blogリポジトリで執筆し、GitHub Actionsでcorporate-nextリポジトリに自動同期しています。記事を書いてpushすれば、コーポレートサイトのブログに自動反映される。便利な仕組みですが、ここで事故が起きました。

MDXの記事内に[お問い合わせページURL]というプレースホルダーが残ったまま同期されてしまい、MDXの構文エラーとしてビルドが落ちました。しかもこのプレースホルダーは12記事すべてに含まれていたため、エラーが12記事に一気に波及しました。

全12記事の[お問い合わせページURL]を正しいリンクに一括置換して解決しましたが、自動同期の便利さの裏に「エラーも自動で伝播する」リスクがあることを思い知らされました。

この経験から、同期スクリプトにfrontmatter（ファイル先頭に書く設定情報）のバリデーション処理を追加しました。必須項目の欠落やMDX構文の基本的なエラーは、同期時点で検出して止めるようにしています。

Vercelデプロイで3回落ちた

今度はローカルでは問題なく動くのに、Vercelのビルドで落ちる。この問題に3回ぶつかりました。

1回目はprebuildスクリプトの問題。手元のPCのNode.js（サーバー側でJavaScriptを動かす実行環境）では動くスクリプトが、Vercelのビルド環境では動かなかった。prebuildスクリプト自体を削除して解決しました（コミットba2bb17）。

2回目はimport.meta.dirname（ファイルの場所を取得する機能）のNode互換性。sync-blog.mjsで使っていたimport.meta.dirnameがVercelのNode.jsバージョンでサポートされていなかった。fileURLToPathという別の取得方法に書き換えて対応しました（コミット922e5e2）。

3回目はドメイン設定。wwwありとwwwなしの統一、リダイレクト設定の不備（コミット3df931d）。

3回とも、Claude Codeと一緒にデバッグしました。ただし、AIにデプロイ環境の差異を最初から完璧に考慮させるのは難しい。手元のPCとVercelではNode.jsのバージョン、利用可能なAPI（プログラムが呼び出せる機能）、ファイルシステムの挙動が異なります。この差異をAIが事前に網羅するのは現実的ではありません。

「デプロイで落ちたら素早く直す」サイクルを速く回す設計のほうが現実的でした。ビルドログを読んで、Claude Codeにエラーメッセージを渡して、修正案を出してもらい、手元のPCで検証してからPush（変更をリポジトリに送信して反映する操作）。このサイクルを30分以内に回せる体制を整えたことで、デプロイエラーへのストレスは大きく減りました。

複数エージェントでレビューを回す

コミット前の4つ目のチェック「レビュー」について補足します。

HRdevでは、コードのレビューを「複数の専門家に並列で見てもらう」形式で実施しています。Claude Codeのサブエージェント機能（複数のAIに役割を分けて並行作業させる仕組み）を使い、code-reviewer（品質・バグ）、security-reviewer（セキュリティ）、architect（設計）といった役割を割り当てた複数のAIに同時にレビューを依頼します。

各専門家が100点満点で採点し、全員のスコアが90点以上になるまで改善と再評価を繰り返します。最初のスコアが52点だったものが、3回の改善ループで90点を超えた経験もあります。

注意点として、複数エージェントのレビューは「全員が90点」を目指すと収束しないことがあります。あるエージェントの指摘を反映すると、別のエージェントの評価が下がるケースです。HRdevでは、3イテレーションで収束しなければ人間に戻す設計にしています。最終判断は人間がする。AIはあくまで多角的な視点を提供するツールです。

Claude Codeで開発を回す際の落とし穴

コーポレートサイトの開発・運用を通じて、いくつかの落とし穴がありました。

コンテキストウィンドウ（AIが一度に記憶できる情報の上限）の管理です。サイト全体のコンポーネント、CSS、MDXファイル、設定ファイルを一度に扱うと、AIのコンテキストが溢れます。コンテキストの最後の20%に入ると、出力の精度が目に見えて下がります。HRdevではpre-compact hook（コンテキストが圧縮される直前に自動で処理を走らせる仕組み）を設定し、コンテキストが一定量に達したら自動でコミット（チェックポイント作成）→文脈をリセットする運用にしています。

Hooks（特定のタイミングで自動で処理を走らせる仕組み）の入れすぎにも注意が必要です。ファイル変更後に自動Prettier（コード整形ツール）を走らせる、console.log（デバッグ用の出力）を検出して警告を出す、git push前に確認を挟む。1つひとつは便利ですが、過剰に入れると開発体験が悪化します。「50回のツール呼び出しでコンテキスト圧縮を提案する」など、閾値の調整に試行錯誤がありました。

非エンジニアがAIでサイトを運用する場合、「何を聞けばいいかわからない」が最大の壁です。エラーが出たとき、エラーメッセージの意味がわからなければ、AIに何を聞けばいいかもわからない。PRDを先に書く運用にしたことで、少なくとも「何をやろうとしていたか」は常に明確になっています。AIへの指示が構造化されるので、意図しない変更が入りにくくなりました。

Claude Codeで作ってみて気づいたこと

hrdev.jpのコーポレートサイトは、Claude Codeなしでは作れませんでした。と同時に、Claude Codeだけでも作れませんでした。

AIを使って開発するということは「コードを書く作業を委託する」ことではありません。「開発プロセスを設計する」ことだと感じました。（開発のサイズによりますが）PRDを書いてもらう、コミット前チェックを設ける、E2Eテストを入れる、レビュープロセスを組む。これらはすべて、AIが生成したコードの品質を担保するために欠かせないプロセスだと思っています。

AIは速く走ってくれます。ただ、プロセスの設計ががない状態で速く走らせると、その速さはそのまま事故になる。逆に一定しっかりとした設計があれば、多少雑に走らせても致命的なミスにはならない。AIの速さを活かすためには、先にしっかりとした設計をするほうが大事です。

最初から完璧でなくて良いので、セッションのたびに、詰まったポイントをルールに追記する。同じ失敗を二度しないための仕組みを、少しずつ厚くしていく。この積み重ねが、少しずつ質を高めていってくれました。

エンジニア採用の仕事と同じ構造だと思っています。

例えばスカウトを1通送るのは誰でもできる。でも、返信率を安定して出し続ける仕組みを設計するのは別の能力が必要です。

再現性のあるプロセスを設計すれば、コードが書けなくてもサイトを運用できる場面はある。属人的な技術力に頼らず、仕組みで品質を保つ。

それが、Claude Codeでコーポレートサイトを作ってみて得た、いちばん大きな学びでした。

AI利活用に興味ありましたらぜひお話させてください！FacebookやXのDMお気軽にお声がけいただけると嬉しいです！