はじめに

夢占いサイト「Yume Insight」の SEO 改善を週次で回すために、
Claude Code の Skill 機能を使って /seo-run コマンドを実装しました。

最初は Gemini API を組み合わせた構成を考えていました。
最終的には Claude のみ の構成に落ち着きました。
その経緯と実装をまとめます。

夢占いサイト「Yume Insight」を開発中です。
ぜひ使ってみてフィードバックいただけたら喜びます。

システム構成

/seo-run 実行
  ↓
fetch_data.py（Python）
  └─ Search Console + GA4 からデータ取得
  └─ 分析・カテゴリ分け
  └─ reports/latest_data.json に保存
  ↓
Claude が latest_data.json を読み込み
  └─ データを直接分析・判断
  └─ 改善案を優先度付きでユーザーに提示
  ↓
ユーザーが承認
  ↓
Claude が対象ファイルを直接修正
  └─ MDXフロントマター（title / description）
  └─ page.tsx の metadata
  └─ コンテンツ本文も対象
  ↓
PR作成（ベース: stage）→ 手動マージ

使用するAPIは Google OAuth（データ取得） と Claude Code（分析・修正） のみです。

最初の設計：Gemini API を挟む構成

当初は以下の構成を考えていました。

fetch_data.py
→ Gemini API
→ 改善提案JSON
→ apply_changes.py
→ claude サブプロセス
→ PR

analyze.py が Search Console と GA4 のデータを Gemini API に投げ、構造化された改善提案 JSON を生成。
それを apply_changes.py が読み込んで claude コマンドをサブプロセスとして起動し、ファイルを修正する設計です。

なぜやめたか

実際に動かしてみると、いくつかの問題が出ました。

① apply_changes.py がmax turnsエラーで失敗した

claude --max-turns 20 でサブプロセスを起動していましたが、ターン数制限に引っかかって途中で止まりました。

② Gemini が生成した文言をそのまま書き込むだけで、Claude の判断は不要だった

title_suggestion / description_suggestion をファイルの該当箇所に書き込むだけなので、Claudeの能力は活かされていませんでした。

③ 管理するAPIキーが増える

Gemini API キーが増えると、セキュリティ管理の手間も増えます（後述）。

シンプルな構成への移行

「Claudeに直接データを渡して考えさせればいい」と気づき、構成を整理しました。

analyze.py（Gemini呼び出し込み）→ 削除
apply_changes.py（claudeサブプロセス）→ 削除
fetch_data.py（データ取得のみ）→ 新規作成
Claude Code が直接データを読んで分析・修正・PR作成

Gemini を廃止したことで、APIキーの管理も1つ減りました。

セキュリティ対応で学んだこと

実装中に APIキーのセキュリティ管理でいくつかハマりました。

① inline export でシェル履歴にAPIキーが残る

スクリプトを動かすために以下のように実行していました。

export GEMINI_API_KEY=AIzaSy... && python3 analyze.py

これは ~/.zsh_history にAPIキーがそのまま残ります。
しかも Claude Code との会話コンテキストにも乗るため、Anthropic のサーバーを経由することになります。

対応：python-dotenv を使い、スクリプト側で .env.local を自動読み込みする形に変更。

from dotenv import load_dotenv
load_dotenv(os.path.join(os.path.dirname(__file__), '../.env.local'), override=False)

GEMINI_API_KEY = os.environ.get("GEMINI_API_KEY", "")

これにより export なしでそのまま実行できます。

② コードにIDをハードコードしていた

analyze.py に GA4 プロパティ ID をハードコードしていました。

GA4_PROPERTY_ID = "properties/123456789"

対応：これも .env.local に移動。

# .env.local
GA4_PROPERTY_ID=properties/123456789
SEARCH_CONSOLE_SITE_URL=sc-domain:example.com

GA4_PROPERTY_ID = os.environ.get("GA4_PROPERTY_ID", "")
SITE_URL = os.environ.get("SEARCH_CONSOLE_SITE_URL", "")

③ seo-automation/ をディレクトリごと gitignore に追加

credentials.json（OAuth認証情報）や token.json（OAuthトークン）が含まれており、スクリプト自体も Vercel へのデプロイには不要なため、ディレクトリごと除外しました。
色々試したけど、結局全除外。

# SEO automation（ローカル実行スクリプト。デプロイ不要）
seo-automation/

④ フックによる pip install ブロックが広すぎた

Claude Code にはコマンド実行前にフックでバリデーションをかけており、グローバルな pip install をブロックしていました。

# 変更前：pip install を全てブロック
echo "$COMMAND" | grep -qE 'pip\s+install|pip3\s+install' && block "..."

しかしこの正規表現は ./venv/bin/pip install もブロックしてしまいます。
venv 内のインストールはグローバル環境を汚染しないので許可しました。

# 変更後：/を含むパス経由（venv）は許可
echo "$COMMAND" | grep -qE '(pip|pip3)[[:space:]]+install[[:space:]]' && \
  ! echo "$COMMAND" | grep -qE '/(pip|pip3)[[:space:]]+install' && \
  block "..."

SKILL.md の内容

# Yume Insight SEO週次分析

## 前提条件チェック
1. seo-automation/ が存在するか
2. token.json が存在するか
3. .env.local に SEARCH_CONSOLE_SITE_URL と GA4_PROPERTY_ID があるか

## 実行手順

### ステップ1：データ取得
cd ~/project/dream-analysis-app/seo-automation && ./venv/bin/python3 fetch_data.py

### ステップ2：Claudeがデータを分析
reports/latest_data.json を読み込み、以下を判断：
- クイックウィン（1〜10位 & CTR低）
- タイトル改善候補（高インプレッション & 低CTR）
- コンテンツ強化候補（11〜20位）
- GA4 エンゲージメント改善

### ステップ3：ユーザーに改善案を提示して承認を得る

### ステップ4：ファイルを直接修正
- /dictionary/[category]/[slug] → content/dictionary/[category]/[slug].mdx
- /column/[slug] → app/column/[slug]/page.tsx

### ステップ5：PR作成
git checkout -b seo/weekly-YYYYMMDD
git add [変更ファイルを個別に指定]
git commit -m "SEO: 週次改善 YYYY-MM-DD"
gh pr create --title "SEO: 週次改善" --base stage

まとめ

	当初構成	最終構成
データ取得	Python	Python
分析・提案生成	Gemini API	Claude Code
ファイル修正	claudeサブプロセス	Claude Code（直接）
APIキー	Gemini + Google OAuth	Google OAuth のみ
管理コスト	高	低

基本的にはClaude Codeが生成してくれています。
それでも、セキュリティ面においては、人間のチェックをしないとダメですね。
指示の出し方など、セキュリティリスクを低下させる工夫はもちろんできます。
しかし、その指示が届いていないパターンも存在するので、注意が必要です。

スクリプトで取ってきたデータを Claude に渡して「考えさせる」だけで、title/description の改善からコンテンツ本文の修正まで対応できるようになりました。
週次 SEO 改善の自動化に Claude Code の Skill は思ったより使いやすそうです。
今後、使ってみて実際にSEO改善になるので数値を追っていきたいと思います。