Claude Codeとブラウザ自動化（Playwright）を組み合わせる時に踏んだ落とし穴

はじめに

Claude Codeを使いながらPlaywrightでブラウザ操作を自動化するスクリプトを書いていると、いくつかの落とし穴にはまった。

「AIが書いてくれたコードをそのまま実行する」という流れが定着しつつある中で、ブラウザ自動化は特有のハマりポイントがある。

本業でCopilot StudioやPower Automateを扱っている立場から言うと、エンタープライズ環境でも個人の自動化でも、この類の問題は構造的に似ている。整理しておく。

1. セッション管理を「コードの外」に出す

Claude Codeに「ログインしてデータを取得するスクリプトを書いて」と頼むと、メールアドレスとパスワードをコード内にハードコードするか、環境変数から読む形で書いてくれることが多い。

しかし実運用で問題になるのは、一度取得したセッションをどう保持するかだ。

毎回ログインするとボット検知に引っかかりやすい。かといってセッションを安全に管理する方法は、ページの構造や認証方式によってまったく異なる。

落とし穴：

• localStorage / sessionStorage / cookie のどれを保存すればいいかはサイトによって異なる
• cookieをJSONに書き出して次回読み込む方式が定番だが、httpOnly フラグのついたcookieはJavaScript経由では取得できない
• page.context().storageState() でまとめて取るのが現実的だが、Playwrightのバージョンによって挙動が変わる

Claude Codeに「セッションをauth.jsonに保存して次回使い回す実装を書いて」と明示的に伝えると、browserContext.storageState()を使った実装を提案してくれる。ただしそのファイルをどこに置くか・いつ更新するかという運用設計は自分で決める必要がある。

2. headlessかheadedかで挙動が変わるサイトがある

Playwrightのデフォルトはheadless（ブラウザウィンドウを表示しない）。速くて便利だが、一部のサービスはheadless環境を検知して動作を変える。

// headlessで弾かれる場合はheaded（headless: false）に変更
const browser = await chromium.launch({ headless: false });

経験的に注意が必要なケース：

• Googleアカウント経由のOAuth（「ロボットによる操作です」と判定されやすい）
• CAPTCHAが出るログインページ
• Xのような積極的にボット対策を強化しているプラットフォーム

headedにしても解決しないことがある。その場合は人間が一度手動でログインしてセッションを保存し、そのセッションを使ってスクリプトを動かすというハイブリッド運用が現実的な落とし所になる。

「ボット検知を回避する技術的工夫」の方向に進むのは、プラットフォームの利用規約上のグレーゾーンに踏み込む可能性があるため、個人的には避けている。

3. Claudeへの指示と実際の画面構造のズレ

Claude Codeに「このページのXXボタンをクリックして」と頼む時、Claudeはスクリーンショットやコードの断片から推測してセレクタを提案する。

しかしWebアプリは定期的に画面構造が変わる。特にid属性やclass名に意味のない文字列（ハッシュ値）を使っているサービスは、デプロイのたびに変わることがある。

堅牢なセレクタの優先順位（Playwrightのおすすめに概ね準拠）：

1. data-testid や aria-label など意味のある属性
2. テキスト内容（text='保存する'）
3. placeholder 属性
4. classやidへの依存は最後の手段

Claude Codeに「壊れにくいセレクタを使って」と伝えると、意識してくれるが完全ではない。定期実行するスクリプトほど、セレクタの見直しタイミングを明示的にスケジュールに入れる必要がある。

4. エラーハンドリングを「ログ残し」まで含めて設計する

Claude Codeが生成するスクリプトは、動くケースのコードは書いてくれるが失敗した時のログが薄いことが多い。

自動化スクリプトをタスクスケジューラやcronで定期実行する場合、失敗したことに気づかないまま数日経つというケースが起きやすい。

最低限入れておきたいもの：

try {
  // メインの処理
} catch (e) {
  fs.appendFileSync('error-log.txt', `[${new Date().toISOString()}] ${e.message}\n`);
  process.exit(1); // 終了コードで失敗を明示
}

終了コードを正しく返すことで、タスクスケジューラ側で失敗を検知できる。エラーログはローテーションしないとファイルが肥大化するため、その設計も最初から入れておくと後で楽になる。

Claude Codeに「タスクスケジューラから実行することを前提に、失敗をログに残す設計にして」と最初から伝えておくと、こういった考慮が入った実装を提案してくれることが多い。

まとめ

Claude Codeはコードを書く部分ではかなり使えるが、運用設計の部分は人間が考える必要がある。

• セッションをどう保持・更新するか
• headless/headed、ボット検知への対応方針
• セレクタをどう壊れにくくするか
• 失敗をどう検知・記録するか

AIに「コードを書いてもらう」という作業と、「それを長期的に維持できる設計にする」という作業は別物。後者は今のところ人間が担う部分が大きい。

より詳しい内容はnoteに書いています：Claude Codeとブラウザ自動化ツールを組み合わせる時の注意点