Claude Code実践ガイド｜静的サイト運用で学んだAI駆動開発の設計パターン

Claude Codeのインストール方法や基本コマンドは、すでに多くのガイドが存在する。本記事では、Astroベースの静的サイト（月間170記事超）をClaude Codeで実際に運用する中で得た設計パターンと運用ノウハウに焦点を当てる。

この記事の前提: Claude Codeの基本操作を理解していることを前提とする。インストールから始めたい場合はClaude Code完全ガイドを、ショートカットやコマンドを知りたい場合はClaude Code実践Tips集を先に参照されたい。

CLAUDE.mdは「組織の記憶」として設計する

CLAUDE.mdはプロジェクトの説明書ではない。AIエージェントが自律的に判断するための意思決定フレームワークである。「何を書くか」以上に「何を書かないか」が重要になる。

設計原則：3層構造

実運用で効果的だったのは、CLAUDE.mdを以下の3層に分ける構造である。

層	配置	内容	読み込み
グローバル	`~/.claude/CLAUDE.md`	全プロジェクト共通の行動規範	常時
プロジェクト	`CLAUDE.md`（ルート）	アーキテクチャ、ビルドコマンド、運営方針	常時
ワークスペース	`1_article-writing/.claude/CLAUDE.md`	用途別のコマンド・エージェント定義	該当WS内のみ

注意点: CLAUDE.mdは最初の200行のみが自動ロードされる。200行を超える場合は、コアな指示を上部に配置し、詳細はdocs/や.claude/rules/に分離してリンクする。

「やらないこと」リストの威力

CLAUDE.mdに最も効果があったのは、禁止事項の明示である。AIエージェントは「良かれと思って」不要な変更を行うことがある。以下のような記述が無駄な修正を防ぐ。

## やらないこと
- 新セクションの追加
- URL体系やルーティングの変更
- 技術スタックの変更（Astro/React/Tailwind）

「やること」だけを書いた場合、AIは記述されていない領域を自由に解釈する。「やらないこと」を明示することで、行動の境界が定まり、意図しない変更が激減した。

`.claude/rules/`による関心の分離

CLAUDE.mdが肥大化すると、すべての指示が常時読み込まれてコンテキストを圧迫する。.claude/rules/ディレクトリにルールファイルを分離すれば、パスベースで条件付き読み込みが可能になる。

.claude/rules/
├── architecture.md    # 依存関係ルール（全ファイル対象）
├── deployment.md      # デプロイ手順（CI/CD変更時のみ）
├── image-policy.md    # 画像使用方針（記事・画像変更時のみ）
└── mcp.md             # MCP設定ガイド

各ファイルの先頭でpaths:を指定すると、該当パスのファイルを操作する場合にのみルールが読み込まれる。170記事分の画像ポリシーを常時ロードする必要はない。

カスタムコマンドでパイプラインを構築する

Claude Codeの.claude/commands/にMarkdownファイルを配置すると、スラッシュコマンドとして呼び出せる。これを応用して、記事制作の全工程を自動化するパイプラインを構築した。

`/pipeline`コマンドの設計

/pipeline [slug]        # 指定記事を執筆
/pipeline --auto        # 完全自律モード
/pipeline --batch       # 複数記事を連続実行

パイプラインの処理フローは以下の8ステップで構成される。

Step	処理	自動化レベル
0	企画選定（backlog.yamlから優先度順に選択）	完全自動
1	執筆タイプ判定（standard / dialogue / book-review）	完全自動
2	執筆（researcher → writer → editor の3エージェント）	半自動
3	品質ゲート（lint + スコアリング）	完全自動
4	バックログ更新	完全自動
5	サムネイル生成（Replicate API経由）	完全自動
6	SEO最適化（メタデータ検証 + 内部リンク強化）	完全自動
7	ビルド検証 + デプロイ（GitHub Actions）	完全自動

設計のポイント: 各ステップは独立しており、途中で失敗しても前ステップの成果物は保存済みである。Step 3の品質ゲートで不合格になっても記事ファイルは残り、手動修正後に再実行できる。

コマンドファイルの構造

コマンドファイルは単なるプロンプトテンプレートではなく、判断ロジックを含む設計書として記述する。

## Step 3: 品質ゲート

### 判定ロジック
- lint合格 + score 70点以上 → Step 4へ
- lint不合格 → 自動修正して再保存、再lint
- score 70点未満 → /improve-article で改善試行（最大2回）
- 2回改善しても70点未満 → ユーザーに報告

AIエージェントはこのロジックに従って自律的に判断し、人間の介入なしにパイプライン全体を完走できる。

Hooksで品質ゲートを自動化する

Hooksは、ツール実行の前後にシェルコマンドを挿入する仕組みである。.claude/settings.jsonに定義する。

実運用で効果的なHooks

タイミング	Hook	目的
PostToolUse（Edit）	`prettier --write`	編集後にコードを自動フォーマット
PostToolUse（Edit）	`console.log検出`	デバッグ用ログの残存を警告
PreToolUse（Write）	`.md作成ブロッカー`	不要なドキュメントファイルの生成を防止
PreToolUse（Bash:git push）	`ビルド検証チェック`	`.build-verified`ファイルの存在を確認
Stop	`console.logの全ファイル監査`	セッション終了時に変更ファイル全体をチェック

Push前のビルド検証は特に重要である。pre-pushフックで.build-verifiedファイルの存在を確認し、ビルド未実行のままプッシュすることを防いでいる。Claude Codeはビルド成功後に自動でtouch .build-verifiedを実行するため、人間が手動で確認する必要はない。

Hooksの設計指針

Hooksは「警告」と「ブロック」の2段階で設計する。

警告（exit 0）: 情報を表示するが処理は続行する（例: console.log検出）
ブロック（exit 2）: 処理を中断する（例: 未ビルドでのpush防止）

ブロックHooksを多用するとワークフローが止まりやすくなる。本当に防ぐべきミスに限定し、それ以外は警告に留めるのが実用的である。

MCPサーバーで外部連携を構築する

MCP（Model Context Protocol）を使えば、Claude Codeから外部ツールやデータソースに接続できる。

実運用で使用しているMCPサーバー

サーバー	用途	活用例
`filesystem`	ファイル操作	記事一覧取得、画像ディレクトリ探索
`memory`	知識永続化	セッション間での学習事項の引き継ぎ
`sequential-thinking`	段階的推論	複雑なリファクタリングの計画
`playwright`	ブラウザ操作	デプロイ後のスクリーンショット取得、コントラスト検証
`tavily`	Web検索	記事執筆時の最新情報調査

MCPの設計上の注意点

MCPツールの説明文はコンテキストウィンドウを消費する。多数のMCPサーバーを接続すると、ツール説明だけでコンテキストの10%以上を占有するケースがある。Claude CodeのTool Search機能（Sonnet 4以降対応）を活用し、必要なツールだけを動的にロードする設計が推奨される。

また、MCPサーバーのスキーマがoneOf/allOf/anyOfを含む場合、Claude Codeとの互換性問題が発生することがある。接続前にスキーマの互換性を確認し、問題がある場合はBash経由でAPIを直接呼び出す方が安定する。

マルチエージェント構成の実践

Claude CodeのTaskツールを使えば、特定の役割を持つサブエージェントを並列実行できる。

記事制作の3エージェント構成

[researcher] → [writer] → [editor]
   調査            執筆        推敲
  (sonnet)       (sonnet)    (sonnet)

エージェント	モデル	役割	コンテキスト消費
researcher	Sonnet	Web検索・既存記事分析・競合調査	15-20%
writer	Sonnet	骨格設計 + 本文執筆	25-35%
editor	Sonnet	推敲・品質チェック・SEO調整	10-15%

設計のポイント: 各エージェントは独立したコンテキストウィンドウで動作するため、メインの会話コンテキストを圧迫しない。researcherが収集した情報は返り値としてメインに戻り、writerへの入力となる。

モデル選択の使い分け

モデル	用途	コスト目安
Opus 4.6	複雑なアーキテクチャ判断、大規模リファクタリング	高（入力$5/M + 出力$25/M）
Sonnet 4.5	日常の開発・記事執筆・コードレビュー	中（入力$3/M + 出力$15/M）
Haiku 4.5	軽量タスク（lint、フォーマット、簡単な検索）	低（Sonnetの約1/3）

日常の記事制作にはSonnetで十分であり、Opusは「設計判断を間違えると手戻りが大きい」場面に限定するのが費用対効果として合理的である。月間のAPI利用コストは、Sonnet中心の運用で**$50〜80程度**に収まっている。

コンテキスト管理の実践戦略

Claude Codeのコンテキストウィンドウは有限であり、長時間の作業ではコンパクション（自動要約）が発生する。コンパクション時に重要な情報が失われると、同じ作業の繰り返しやミスの原因となる。

Auto Memoryの活用

Claude Codeは~/.claude/projects/<project>/memory/MEMORY.mdにプロジェクト固有の記憶を自動保存する。セッション間で以下の情報を引き継げる。

プロジェクト構造とアーキテクチャの要点
過去の作業で発見したGotchas（落とし穴）
ビルドコマンドとデプロイ手順
命名規則やコーディングパターン

運用のコツ: MEMORY.mdも200行制限があるため、詳細なトピック別ファイル（debugging.md、patterns.md等）を作成し、MEMORY.mdからリンクする構成が効果的である。

コンパクションへの備え

Claude Codeはコンテキストの75%に達した時点でコンパクションを発動する。以下の対策で情報損失を最小化できる。

重要な決定事項はファイルに書き出す — コンテキスト内の発言は消えるが、ファイルは残る
TodoWriteツールで進捗を追跡する — コンパクション後もTODOリストは保持される
/compactで手動コンパクションを実行する — 保存すべき情報を指定できる
1タスク完了ごとにコミットする — Git履歴が最も信頼できる「記憶」である

よくある質問

Claude Codeは個人開発者にも必要か？

プロジェクトの規模と複雑さによる。 単一ファイルのスクリプトなら不要だが、10ファイル以上のプロジェクトでは、CLAUDE.mdによるコンテキスト提供だけで生産性が大幅に向上する。インストールは無料であり、APIコストも小規模なら月$10〜20程度に収まる。

CursorとClaude Codeはどちらを選ぶべきか？

併用が最も効率的である。 Cursorはリアルタイムのコード補完とインタラクティブな編集に優れ、Claude Codeは自律的なマルチステップタスク（リファクタリング、テスト生成、ドキュメント作成）に強い。両者の詳細な比較はCursor vs Claude Code徹底比較を参照されたい。

CLAUDE.mdが長くなりすぎた場合はどうするか？

200行以内に収めるのが鉄則である。 200行を超えた部分は自動ロードされない。超過する場合は.claude/rules/にルールファイルを分離し、CLAUDE.mdにはプロジェクトの概要・ビルドコマンド・運営方針のコアだけを残す。

API利用コストを抑えるには？

モデル選択とサブエージェントの活用が鍵である。 日常の開発はSonnet、軽量タスクにはHaikuを使い分ける。サブエージェントを活用すれば、メインコンテキストの圧迫を防ぎつつ並列作業が可能になる。Batch APIを使えば非同期処理で50%のコスト削減も可能である。

Claude Code完全ガイド2026 — インストールから基本操作までの入門
Claude Code実践Tips集2026 — ショートカット・コマンド・プロンプト設計
Cursor vs Claude Code徹底比較2026 — アーキテクチャ・料金・用途別の選択指針
Claude Codeの設定を極める — ハッカソン優勝者の設定集を解説
ボクと相棒の開発日記 — AI × 人間の協働ワークフローを対話形式で
GitHub Copilot実践Tips 2026 — Agent ModeからPR自動化まで
プロンプトエンジニアリング実践ガイド — Claude・GPT・Geminiで使える技術

※ 本記事は2026年2月時点の情報に基づく。Claude Codeの機能・料金は頻繁に更新されるため、最新情報は公式ドキュメントを確認されたい。