Claude Codeで2サイト構築を始めた理由
2024年、私は個人ブログ urinosuke.com と法人サイト urisol.com の2つを同時に立ち上げた。どちらも Astro + Cloudflare Pages の構成で、記事の自動投稿には GitHub Actions + Anthropic API を使っている。
Claude Code を導入したのは、サイト構築の初期段階で「毎回同じ説明を繰り返すのが非効率」と感じたからだ。記事生成・画像最適化・デプロイ自動化といった一連の流れを、一度設計すれば再利用できるツールとして期待していた。
実際、Claude Code は期待どおり機能した部分もある。だが同時に、.cursorrules に書いたプロンプトがまったく効かない場面も何度も経験した。この記事では、私が実際に失敗した3つの実例を通じて、サブエージェント設計の限界と、実際に機能したプロンプト設計の実話を記録する。
失敗1: .cursorrulesに書いたディレクトリ構造の指示が無視された
最初の失敗は、ディレクトリ構造の指示だった。
私は .cursorrules に次のような指示を書いていた：
記事は
src/content/blog/に配置する。画像はpublic/images/blog/に配置する。
これは Astro の Content Collections の標準的な構造だ。だが Claude Code は、何度指示しても src/posts/ や public/assets/ といった独自のディレクトリを作ろうとした。
原因は、.cursorrules が「設計思想を伝える文書」としては機能するが、「毎回必ず守らせる強制力」を持たないことだった。Claude Code は過去の会話履歴や、そのときのタスク文脈のほうを優先する。.cursorrules の指示は「参考情報」の一つに過ぎない。
結局、ディレクトリ構造に関する指示は、.cursorrules から削除し、毎回のタスク開始時に「今回は src/content/blog/ に配置してください」と明示的に伝える運用に切り替えた。
失敗2: サブエージェントに「記事の事実確認」を任せた結果、未読書籍が記事に混入した
次の失敗は、記事生成のサブエージェントに「事実確認」を任せようとした場面だ。
私は、記事生成のプロンプトに次のような指示を書いていた：
書籍を引用する場合は、必ず「うりさんが読了した書籍リスト」から選ぶこと。未読書籍の引用は厳禁。
だが実際には、記事に未読書籍が混入することが何度もあった。サブエージェントは、書籍リストを「参考情報」として読み込むものの、記事のテーマに沿った書籍を優先する傾向があった。リストに載っていない書籍でも、タイトルやテーマが合っていれば「これは適切な引用だ」と判断して記事に入れてしまう。
この問題を解決するために、私は記事生成プロンプトに「書籍リストにない書籍を引用した場合、その記事は不採用とする」という評価基準を明示した。さらに、記事生成後に自分で書籍タイトルをリストと突き合わせる確認フローを追加した。
サブエージェントに「事実確認」を任せる設計は、理想的だが現実的ではない。最終的な事実確認は人間が担うしかない。
失敗3: 「記事の重複チェック」をサブエージェントに任せた結果、似た切り口の記事が量産された
3つ目の失敗は、記事の重複チェックをサブエージェントに任せた場面だ。
私は、記事生成プロンプトに「直近7本のタイトルと被らない記事を作成する」という指示を書いていた。だが実際には、タイトルは異なるものの、切り口や具体例が似た記事が連続して生成されることがあった。
例えば、「マネーフォワードMEの家計管理術」というテーマで記事を生成したとき、次の記事でも「マネーフォワードMEの資金繰り設計」という似た切り口が提案された。タイトルは異なるが、読者にとっては「また同じツールの話か」と感じる内容だ。
この問題の原因は、サブエージェントが「タイトルの文字列」だけを重複判定の基準にしていたことだった。記事の「切り口」や「具体例の重複」は、文字列比較では検出できない。
結局、記事の重複チェックも人間が最終判断するしかない。私は、記事生成後に自分で「この切り口は直近の記事と似ていないか」を確認する運用に切り替えた。
実際に機能したプロンプト設計の3つの原則
これらの失敗を経て、私が実際に機能させたプロンプト設計の原則は次の3つだ。
1. 「強制力」が必要な指示は、.cursorrulesではなくタスク開始時に明示する
ディレクトリ構造・ファイル命名規則・出力形式など、「必ず守ってほしい」指示は、.cursorrules に書いても効かない。毎回のタスク開始時に、具体的に指示する。
2. 事実確認・重複チェックは人間が担う
サブエージェントに「事実確認」や「重複チェック」を任せる設計は、理想的だが現実的ではない。最終的な確認は人間が担う前提で、プロンプトを設計する。
3. 「評価基準」を明示する
「良い記事」「適切な引用」といった曖昧な指示ではなく、「書籍リストにない書籍を引用した場合は不採用」「直近7本と切り口が似ている場合は不採用」といった具体的な評価基準を明示する。
まとめ: サブエージェント設計は「自動化」ではなく「作業の型」を作る道具
Claude Code でサイト構築を進めて気づいたのは、サブエージェント設計は「自動化」のためのツールではなく、「作業の型」を作るツールだということだ。
.cursorrules に書いた指示がそのまま機能することは少ない。だが、指示を書く過程で「自分がどういう判断基準で作業しているか」を言語化できる。その言語化が、次のタスクの指示を明確にし、作業の再現性を高める。
失敗を経て、私は「サブエージェントに任せる範囲」と「人間が最終判断する範囲」の線引きを、実務の中で学んだ。この線引きが、Claude Code を実務で使い続けるための前提条件だと思う。
参考
関連書籍
実践Claude Code入門——現場で活用するためのAIコーディングの思考法
チーム導入・Claude.md 運用・サブエージェント設計の実務論点がまとまっている。失敗事例の言語化が参考になった。
LLMのプロンプトエンジニアリング
GitHub Copilot設計者のプロンプト設計論。コンテキスト・スカフォールディング・テンプレート化の概念地図がClaude Code運用にそのまま応用できる。
関連記事
- 38歳個人事業主が『LLMのプロンプトエンジニアリング』を読んで設計した業務用テンプレート3段階：コンテキスト・スカフォールディング・評価設計の実務応用
- マネーフォワードクラウドで個人事業と法人の「試算表→キャッシュフロー」を毎月見る習慣が、3財布の資金繰り設計を機能させた実話
- Claude Codeで「検査記録の自動分類スクリプト」を作ったら、年間40時間の整理作業が消えた話
まとめて読む: AI活用・自動化