Claude Codeで効率的に開発を進めるために最も重要なのは「事前準備」です。AIに曖昧な指示を出すと、意図しない方向に進んでしまい、大量の修正が必要になります。
この記事では、実際のWordPressプラグイン開発を例に、Claude Codeで高品質なコードを生成するための要件定義・設計管理の具体的な手順をご紹介します。
🎯 なぜ事前準備が重要なのか？
Claude Code使用時の典型的な問題
- 曖昧な指示: 「プラグインを作って」→ 何を作るか分からない
- WordPress エラー: Fatal Error でサイトが動かなくなる
- 仕様の迷走: 途中で要件変更 → 大幅な作り直し
事前準備の効果
- ✅ 明確な指示: 具体的な仕様でピンポイントな実装
- ✅ 一貫性: 統一された設計思想
- ✅ 品質保証: セキュリティ・パフォーマンス要件の事前定義
📁 Step 1: プロジェクト構造の準備
1.1 推奨ディレクトリ構造
[プロダクト名]/ # GitHubリポジトリルート
├── dist/ # ビルド成果物（.gitignoreで除外）
│ └── [プロダクト名]/ # プラグイン本体
│ ├── [プラグイン].php # メインプラグインファイル
│ ├── uninstall.php # アンインストール処理
│ ├── readme.txt # WordPress.org用README
│ ├── LICENSE # GPLv2ライセンス
│ ├── includes/ # 内部処理クラス
│ ├── admin/ # 管理画面関連
│ ├── public/ # フロントエンド関連
│ └── languages/ # 多言語対応ファイル
├── src/ # アプリケーションソースコード
├── tests/ # テストスイート
├── config/ # 設定ファイルディレクトリ
├── README.md # プロジェクト説明
├── docs/ # 開発ドキュメント
│ ├── 01_requirements.md # 要件定義書
│ ├── 02_architecture.md # システム設計書
│ ├── 03_development-workflow.md # 開発/テスト方針（段階的テストとログ記録の徹底）
│ ├── 04_database.md # データベース設計書（必要な場合）
│ ├── 05_api.md # API設計書
│ ├── 06_errors.md # エラーハンドリング設計
│ ├── 07_setup.md # 開発環境セットアップ
│ ├── 08_design.md # デザインシステム定義（必要な場合）
│ ├── 09_frameworks-guide.md # CSSフレームワーク（必要な場合）
│ └── 10_tasks.md # 開発タスク・ロードマップ
├── logs/ # 動的開発記録 + Vibe Logger
│ ├── CHANGELOG.md # 開発進捗記録
│ ├── ERRORLOG.md # エラー・問題記録
│ ├── PATTERNS.md # コーディングパターン・知見記録
│ └── vibe/ # Vibe Logger出力
│ └── vibe_20250709.log
├── CLAUDE.md # Claude Code設定（統括ファイル）
├── .claude/ # Claude Code設定（Git管理対象外）
├── .git/ # Git管理
└── .gitignore # Git設定
重要: WordPressプラグインの場合はdist/内に配置し、隠しファイルと完全分離する
📋 Step 2: 01_requirements.md（要件定義書） の作成
2.1 現状の問題の明確化
実例）WP Analytics Tag Check Plugin
何が不便か？
- WordPressプラグイン「ExUnit」等は1つのタグしか設定できない
- 自社と広告代理店等の複数タグ管理に別途システムが必要
- タグの発火状況を手動確認する必要があり、問題発見が遅れる
2.2 解決したい範囲を決める
対象機能（スコープ内）
- 複数アナリティクスタグの一元管理
- 自動監視システム（デフォルト AM3:00実行）
- 問題検出時の自動メール通知
- WordPress設定「検索エンジンがサイトをインデックスしないようにする」の監視
- タグが1つもない状態ではないか（タグ設定のリセット・設定し忘れ等）の監視
対象外（スコープから除外）
- 個別ページのNoindex設定監視
- Google Analytics API連携による詳細分析
- 複数サイト一括管理機能
WordPressプラグイン開発での実装例：
# 01_requirements.md（要件定義書）
## 1. プロジェクト概要
### 1.1 プロダクト名
**WP Analytics Tag Check**
### 1.2 概要
複数のアナリティクスタグを一元管理し、タグの動作状況とサイトのNoindex設定を自動監視してメール通知するWordPressプラグイン
### 1.3 ターゲットユーザー
- 複数のアナリティクスタグを管理する必要があるWordPress管理者
- 広告代理店やマーケティング担当者
- 複数のクライアントサイトを管理するWeb制作会社
- テスト環境と本番環境を頻繁に切り替える開発者
## 2. 現状の問題と解決策
### 2.1 現状の問題
#### 問題1: 単一タグ制限
- **現状**: WordPressプラグイン「ExUnit」や多くのSEOプラグインはタグを1つしか設定できない
- **影響**: 自社と広告代理店等の複数タグ管理に別途システムが必要
- **頻度**: 日常的な運用で毎回発生
#### 問題2: 監視の手動化
- **現状**: タグが発火していない問題に気づくのに時間がかかる
- **影響**: 毎日の手動チェック作業：30分/日、問題発見の遅れ：平均24-48時間
- **頻度**: 毎日の運用作業
#### 問題3: 移行時の設定ミス
- **現状**: テスト環境から本番環境移行時のNoindex設定忘れが頻発
- **影響**: SEO効果の損失、検索エンジンでの表示機会の喪失
- **頻度**: 月1-2回発生
### 2.2 解決策
#### 対象機能（スコープ内）
- 複数アナリティクスタグの一元管理
- 自動監視システム（デフォルト AM3:00実行）
- 問題検出時の自動メール通知
- WordPress設定「検索エンジンがサイトをインデックスしないようにする」の監視
- 複数のアナリティクスタグがちゃんと出力されているかの監視
- タグが1つもない状態ではないか（タグ設定のリセット・設定し忘れ等）の監視
#### 対象外（スコープ外）
- 個別ページのNoindex設定監視
- Google Analytics API連携による詳細分析
- 複数サイト一括管理機能
- リアルタイム監視（バッチ処理のみ）
## 3. 機能要件
### 3.1 MVP（最小機能プロダクト）要件
#### 1. タグ管理機能
- **タグタイプ**: Google Analytics（gtag）、Google Tag Manager、カスタムスクリプト
- **基本操作**: タグの追加・編集・削除・有効/無効切り替え
- **入力形式**: <script>〜</script> 形式での完全タグ入力
- **出力制御**: wp_head または wp_footer での出力位置選択
#### 2. 基本監視機能
- **タグ存在確認**: 設定したタグがページ上に出力されているか（簡易版）
- **Noindex監視**: WordPress設定の「検索エンジンがサイトをインデックスしないようにする」チェック
- **監視スケジュール**: WordPress Cron使用、デフォルト毎日AM3:00
#### 3. メール通知機能
- **通知先**: 管理者メール（admin_email）
- **通知条件**: タグなし、タグ出力エラー、Noindex有効
- **メール内容**: 問題の種類、発生時刻、確認方法
### 3.2 将来機能（MVP後の拡張）
- 高度な監視（タグの発火確認、詳細なエラー分析）
- 複数メール通知先設定
- 詳細ログ履歴・エクスポート機能
- 監視頻度のカスタマイズ
- API連携機能
## 4. 非機能要件
### 4.1 パフォーマンス要件
- **ページ読み込み**: フロントエンドへの影響1秒以内
- **管理画面**: 設定画面の応答性良好
- **監視処理**: バックグラウンド実行でサイトに影響なし
- **メモリ使用**: 追加使用量16MB以下
### 4.2 互換性要件
- **WordPress**: 5.0以上
- **PHP**: 7.4以上
- **ブラウザ**: モダンブラウザ対応（Chrome、Firefox、Safari、Edge）
- **プラグイン**: 主要SEO・キャッシュプラグインとの共存
### 4.3 セキュリティ要件
- **WordPress.org準拠**: 完全なガイドライン遵守
- **XSS対策**: 全出力のエスケープ処理
- **CSRF対策**: nonce による操作確認
- **SQLインジェクション対策**: prepared statement使用
- **権限管理**: manage_options capability必須
### 4.4 ユーザビリティ要件
- **学習コスト**: 5分以内での基本操作習得
- **直感的操作**: 説明不要の分かりやすいUI
- **エラー対応**: 明確なエラーメッセージと解決方法の提示
- **テスト駆動開発の徹底**: 具体的で明確なテストを書くこと
## 5. UI/UX設計
### 5.1 管理画面構成
#### タブ構成
1. **タグ管理**: メインのタグ設定画面
2. **監視設定**: 監視条件・通知設定
3. **ステータス**: 現在の状況・ログ表示
#### タグ管理画面レイアウト
┌─────────────────────────────────────┐
│ WP Analytics Tag Check │
├─────────────────────────────────────┤
│ [タグ管理] [監視設定] [ステータス] │
├─────────────────────────────────────┤
│ 登録済みタグ一覧: │
│ ┌─────────────────────────────────┐ │
│ │ GTM-P6H7HXM2 [有効] [編集] [削除] │ │
│ │ G-7Y97FGQ3PL [有効] [編集] [削除] │ │
│ └─────────────────────────────────┘ │
├─────────────────────────────────────┤
│ 新しいタグを追加: │
│ タグ名: [例: Google Analytics] │
│ タグコード: [<script>...</script>] │
│ 出力位置: [○ head] [○ footer] │
│ [+ タグを追加] │
└─────────────────────────────────────┘
## 6. 技術制約
### 6.1 WordPress.org制約
- **ライセンス**: GPL v2以降必須
- **外部通信**: ユーザー明示的同意のみ
- **トラッキング**: 一切のユーザートラッキング禁止
- **広告制限**: 管理画面での過度な宣伝禁止
- **コード品質**: 人間が読めるコード、WordPress標準準拠
### 6.2 セキュリティ制約
- **データサニタイズ**: 全入力データの適切な処理
- **出力エスケープ**: XSS防止の徹底
- **権限チェック**: 全操作での適切な権限確認
- **nonce検証**: CSRF攻撃防止
### 6.3 パフォーマンス制約
- **フロントエンド影響**: 最小限に抑制
- **データベース**: 効率的なクエリ設計
- **キャッシュ**: 適切なキャッシュ戦略
- **メモリ**: 省メモリ設計
## 7. 成功指標
### 7.1 機能的指標
- **問題検出率**: タグ・Noindex問題の95%以上を検出
- **通知信頼性**: 99%以上のメール送信成功率
- **処理性能**: 10個のタグ監視を3分以内で完了
### 7.2 ユーザー体験指標
- **初期設定時間**: 5分以内でのタグ設定完了
- **管理効率**: 手動チェック時間の90%削減
- **エラー対応**: 問題発生から認識まで3時間以内
### 7.3 品質指標
- **バグ報告**: 月間5件以下
- **互換性**: 主要環境での100%動作
- **セキュリティ**: 脆弱性ゼロの維持
## 8. 開発方針
### 8.1 段階的開発
- **Phase 1**: MVP機能のみ実装
- **Phase 2**: GUI改善・UX向上
- **Phase 3**: 高度な機能追加
### 8.2 品質重視
- **WordPress.org準拠**: 公式ディレクトリ掲載レベル
- **セキュリティファースト**: セキュリティを最優先
- **シンプル設計**: 必要最小限の機能に特化
この要件定義に基づき、シンプルで信頼性の高いWordPressプラグインを開発し、WordPress.org公式ディレクトリでの公開を目指します。
⚙️ Step 3: 02_architecture.md（システム設計書） の作成
WordPressプラグイン開発での実装例：
# 02_architecture.md（システム全体の設計）
## 1. 技術スタック
### 1.1 開発環境
- **PHP**: 7.4以上（WordPress 5.0+の要件）
- **WordPress API**: Hook、Database、Admin Menu API
- **jQuery**: WordPress標準搭載版（依存関係なし）
- **MySQL/MariaDB**: WordPress標準データベース
### 1.2 選択理由
- **PHP**: WordPressの標準言語、豊富なAPI
- **WordPress API**: セキュリティ・互換性の確保
- **jQuery**: 追加ライブラリ不要、軽量
- **MySQL**: 既存インフラの活用
## 2. プロダクト命名規則
### 2.1 正式名称
**WP Analytics Tag Check**
### 2.2 ファイル・コード命名規則
ディレクトリ名: [プロダクト名] (ハイフン区切り)
メインファイル: [プロダクト名].php
クラス名: WP_Analytics_Tag_Check (アンダースコア、WordPress標準)
関数プレフィックス: wp_analytics_tag_check_ (アンダースコア区切り)
DBテーブル: wp_analytics_tag_check_ (プレフィックス)
JavaScript: wpAnalyticsTagCheck (キャメルケース)
CSS: .[プロダクト名] (ハイフン区切り)
### 2.3 UI用語統一
日本語UI用語:
- タグ (アナリティクスタグ、トラッキングコード)
- 監視 (チェック、モニタリング)
- 通知 (アラート、お知らせ)
- 設定 (オプション)
- ログ (履歴、記録)
内部英語用語:
- tag (アナリティクスタグ)
- monitor/check (監視機能)
- notification (通知機能)
- settings (設定)
- logs (ログ)
✨ ワークフローの効果
- Claude Codeへの明確な指示: 曖昧さを排除した具体的な仕様
- 手戻りの大幅削減: 事前に決めた仕様に沿った一貫した開発
- 品質の保証: セキュリティ・パフォーマンス要件の事前定義
- 開発効率の向上: 迷いのない段階的な実装
事前準備に時間をかけることで、Claude Codeでの実装フェーズが劇的に効率化されます。設計書作成は面倒に感じるかもしれませんが、この投資が後の大幅な時間短縮につながります。
🚀 次のステップ
この準備編1で要件定義・設計管理の基盤を作ったら、次は準備編2でデバッグ環境の整備を行います。
Gemini CLI × Claude Code を併用して、効果的な設計書・CLAUDE.mdを作成する
Vibe Codingのワークフロー 準備編2.1 - 開発方針/テスト環境の整備
Vibe Codingのワークフロー 準備編2.2 - Vibe Logger を活用したAI駆動開発
