WSL + OpenCode な環境で、AIエージェントがブラウザ表示を確認しながら開発できるようにする

Webアプリ開発をAIエージェントでやってるとき、AI自身にブラウザの表示を確認させることができると格段に効率が上がります。
今回、Windows + WSL 環境でこれをやる方法を纏めました。

最新の Node.js npx はインストール済みと仮定します。

Playwright のブラウザをインストール

npx playwright install chromium

npx で Chromium が自動ダウンロードされます。重いのでちょっと時間かかる。

opencode.jsonにMCPを追加。

リポジトリのルートにある opencode.json にMCPの定義を追加します。
無い場合は新規で作成。

{
  "$schema": "https://opencode.ai/config.json",
  "skills": {
    "paths": [".agents/skills", ".opencode/skills"]
  },
  "mcp": {
    "playwright": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@playwright/mcp@latest",
        "--headless",
        "--caps",
        "vision"
      ],
      "enabled": true,
      "environment": {
        "PLAYWRIGHT_BROWSERS_PATH": "0"
      }
    }
  }
}

–headless を付けると画面表示なしで動作します。ヘッドレスブラウザです。

ブラウザ表示確認のスキルを作成

これを使ってブラウザの表示をチェックするスキルを作成

---
name: browser-check
description: Playwright MCPを使用してWSL上のRailsアプリの表示を確認する。UI変更後、レスポンシブ表示、テーマ、コンソールエラー、アクセシビリティを検証する場合に使用。Use ONLY when Playwright MCPが有効で、Railsサーバーが起動している場合。
---

# Skill: browser-check

Playwright MCPを使用して、WSL環境で動作するRailsアプリのブラウザ表示を確認します。

## 前提条件

- Playwright MCPが `opencode.json` で有効になっている
- Railsサーバーが起動している（`bin/rails server -b 0.0.0.0 -p 3000`）
- Node.jsがWSLにインストールされている

## 確認手順

### 1. Railsサーバーの確認・起動

```bash
# 起動しているか確認
pgrep -f "rails server" || bin/rails server -b 0.0.0.0 -p 3000 -d
```

### 2. ページ表示確認

`browser_navigate` で対象ページを開く：

```
browser_navigate → http://127.0.0.1:3000/<対象URL>
```

### 3. デスクトップ表示のスクリーンショット

```
browser_screenshot → デスクトップ幅 (1280x720)
```

### 4. モバイル表示のスクリーンショット

レスポンシブ対応が必要なページはモバイル幅でも確認：

```
browser_resize → 375x812 (iPhone X/11 相当)
browser_screenshot
```

### 5. コンソールエラー確認

```
browser_console_messages → level: "error"
```

エラーがあれば原因を特定し修正。

### 6. ネットワークエラー確認

```
browser_network_requests → ステータスコード4xx/5xxを確認
```

### 7. ダークテーマ確認（該当ページ）

テーマ切り替えがあるページは、ライト／ダーク両方で確認。

### 8. フォーム操作確認（該当ページ）

フォームがあるページは、`browser_fill_form` と `browser_click` で入力・送信フローを確認。

### 9. クリーンアップ

```
browser_close → ブラウザを閉じる
```

## 確認項目チェックリスト

- [ ] ページが正常に読み込まれる
- [ ] デスクトップ幅で表示崩れがない
- [ ] モバイル幅で表示崩れがない
- [ ] コンソールエラーがない
- [ ] ネットワークエラーがない
- [ ] ライト／ダークテーマが正常に動作
- [ ] フォーム操作が正常（該当する場合）
- [ ] アクセシビリティ要素（ラベル、alt属性、ARIA）が適切

## 注意事項

- Playwright MCPのブラウザはWSL内でheadless動作します
- Windows側のブラウザには表示されません
- 視覚的な確認はスクリーンショット画像を通じて行います
- `--caps vision` により座標ベースのクリックも可能です

UI開発担当エージェントに使い方を定義

UI開発担当としてすでに定義していたエージェント「frontend-implementer」に使い方を追記しました。

---
description: 公開画面・管理画面のUIを担当する。ERB、CSS、Stimulus、アクセシビリティ、レスポンシブ対応を変更するチケットで使用する。
mode: subagent
model: opencode-go/deepseek-v4-flash
reasoningEffort: medium
permission:
  edit: allow
  bash: allow
---

あなたは tech_notes のフロントエンド実装担当です。割り当てられたUIチケットだけを実装してください。

作業前に AGENTS.md、docs/requirements.md、対応する docs/images、既存のビュー・CSS・Stimulus実装を確認してください。フロントエンドは importmap + Stimulus であり、Node.jsツールチェーンを導入しないでください。公開画面と管理画面は既存の共通レイアウトを再利用し、ライト／ダークテーマ、レスポンシブ表示、キーボード操作、適切なラベルやセマンティクスを維持してください。Markdown表示は PostsHelper の既存ヘルパーを使用してください。

要件変更が必要でも、チケットに含まれない docs/requirements.md の編集を独断で行わず親エージェントへ報告してください。スコープ外の変更、ブランチ操作、コミット、プッシュ、PR操作は行わず、ユーザーの既存変更を保持してください。

実装後は変更ファイルに対する Rubocop、関連する統合テスト、必要な場合はシステムテストを実行してください。ブラウザ実行が環境制約で失敗した場合は、原因を推測で隠さず報告してください。

## Playwright MCP によるブラウザ確認

UI変更が完了したら、Playwright MCPを使用して実際の表示を確認してください。

1. Railsサーバーが起動しているか確認（起動していなければ `bin/rails server -b 0.0.0.0 -p 3000` をバックグラウンドで起動）
2. `browser_navigate` で `http://127.0.0.1:3000/<対象ページ>` を開く
3. `browser_screenshot` でデスクトップ幅（1280x720）のスクリーンショットを取得
4. レスポンシブ対応が必要なページは、モバイル幅（375x812）でもスクリーンショットを取得
5. `browser_console_messages` でコンソールエラーを確認
6. 表示崩れ、テーマ不整合、アクセシビリティ問題があれば修正して再確認
7. 確認が完了したら `browser_close` でブラウザを閉じる

確認対象は `docs/requirements.md` と `docs/images/*.png` のデザイン仕様に従うこと。

完了報告は日本語で、概要、変更ファイル、実行したチェックと結果、ブラウザ確認結果、残課題・懸念事項を簡潔に記載してください。

あとはUIのチェックを依頼すればやってくれます。
依頼しなくても必要な時に自動的にやってくれる。