はじめに

普段は業務アプリから SaaS まで幅広く Web 開発をしており、個人的にヘルスケアアプリなどを Claude Code や Cursor を使って開発しています。

AI駆動開発におけるQA -> AIに修正させるまでが大変すぎたのでサイトに JavaScript タグを1行貼るだけで、誰でもスクショ付きでバグ報告ができて、GitHub Issue 作成から AI 自動修正まで繋がるツール 「Bugoon（バグーン）」 を作りました。

なぜ作ったか

バグ報告が面倒すぎる問題

QA やバグ報告のフローは、大体こうなります。

スクリーンショットを撮る
画像をどこかに貼り付ける
バグの内容を説明する
再現手順を書く
ブラウザや OS の情報を調べて書く
チケットを起票する

手順が多すぎます。

しかも非エンジニアからの報告は「動きません」の一言だったりします。ブラウザのバージョンもコンソールエラーも再現手順もありません。

AI 時代の新しい課題

Cursor や Claude Code で GitHub Issue からバグを自動修正できる時代になりました。しかし AI がちゃんと動くには、環境データ付きの構造化された Issue が必要です。

「動きません」では AI も困ります。

Bugoon の目標

「報告の敷居を下げつつ、AI が食える形式のデータを自動で作る」

これが Bugoon のコンセプトです。

Bugoon でできること

ワンクリックでスクショ & 注釈

ウィジェットのボタンをクリックするだけでページをキャプチャ。丸印で問題箇所をハイライトできます。

専用のChrome 拡張と組み合わせれば、chrome.tabs.captureVisibleTab によるピクセルパーフェクトなスクリーンショットも撮れます。（※拡張機能なしだと、canvas化したのものを画像化するので、要素ないスクロールの位置とかがズレる場合がある）

環境データの自動収集

以下のデータを自動で収集します。

ブラウザ / OS / ビューポートサイズ
コンソールエラー
ネットワークエラー
ユーザー操作の記録（クリック、入力、ページ遷移）
ページ URL

報告者は何も意識する必要がありません。

GitHub Issue の自動作成

バグレポートは、ラベル付きで構造化された GitHub Issue に自動変換されます。Issue には環境データやスクリーンショットがすべて含まれるので、Cursor や Claude Code がそのまま取り込んで修正に着手できます。

ステータス管理

ダッシュボードでバグレポートのステータスを管理できます。

triage → open → in_progress → resolved → closed

GitHub Issue のステータスと連動し、close したら、bugoon側も closed に、reopen したら open ステータスに戻ります。

流れ

ダッシュボードで、 open にしたら、Github Issue に登録される
Cursor, ClaudeCodeが修正しPR作成、PRコメントにref: #??? が付き、Github Issueと連携されてる
PRをmerge / closeしたら、Github Issue 側も close され
bugoon側でも closedになる

技術スタック

レイヤー	技術
Backend	Ruby on Rails 8 (API mode) + Ruby 3.4
Frontend	Next.js 15 (App Router) + React 19 + TypeScript
UI	shadcn/ui + Tailwind CSS
Widget	TypeScript + Vite（13KB gzip）
認証	Firebase Authentication (Google / GitHub OAuth)
DB	PostgreSQL 15 (Cloud SQL)
ストレージ	Firebase Storage
インフラ	GCP Cloud Run + Cloud Load Balancer + Cloud CDN
IaC	Terraform
CI/CD	GitHub Actions
ジョブキュー	Solid Queue
多言語対応	next-intl（日本語 / 英語）

アーキテクチャ

パスベースルーティング

1つのドメイン（bugoon.com）でパスによってバックエンドを振り分けています。

                bugoon.com
                    │
               [Cloud CDN]
                    │
           [Cloud Load Balancer]
          ┌────────┼────────────┐
          │        │            │
      /api/*   /widget/*       /*
          │        │            │
     [Cloud Run] [GCS]    [Cloud Run]
     (Rails API)  (JS)    (Next.js)
          │                     │
     [Cloud SQL]       [Firebase Storage]

/api/* → Rails API（Cloud Run）
/widget/* → ウィジェット JS（Cloud Storage + CDN キャッシュ）
/* → Next.js ダッシュボード（Cloud Run）

Widget のデータフロー

[ユーザーのブラウザ]
  │
  ├─→ スクショをFirebase Storageに直接アップロード
  │
  └─→ バグレポートをAPI送信（スクショのパスだけ含む）
        │
        └─→ [Rails API] 非同期ジョブでGitHub Issue作成

画像を Rails API 経由にしなかったのは、API サーバーの帯域とメモリを使わないためです。Firebase Storage に直接アップロードし、API にはパスだけ保存します。

技術的に工夫したポイント

1. Widget を Shadow DOM で隔離

ウィジェットは任意のサイトに埋め込まれるので、親サイトの CSS と干渉しないことが重要です。Shadow DOM で完全に隔離しました。

<!-- サイトオーナーが貼るタグはこれだけ -->
<script
  src="https://bugoon.com/widget/v1/bugoon.js"
  data-api-key="YOUR_API_KEY"
></script>

ウィジェット内部で Shadow Root を作り、そこにスタイルと DOM を閉じ込めています。バンドルサイズは Vite の tree shaking で 13KB gzip に抑えました。

2. CORS の動的検証

ウィジェットは任意のドメインから API を叩くため、CORS の制御が必要です。

ダッシュボード: 固定オリジン（bugoon.com）を許可
ウィジェット: プロジェクトごとに allowed_origins を DB に保存し、単一 SQL クエリで動的検証

# リクエストのOriginとAPI KeyからプロジェクトをDBで検索
# マッチすればCORSを許可、しなければ拒否
Project.exists?(api_key: api_key, allowed_origins: origin)

プロジェクト設定画面で許可オリジンを追加するだけで、そのドメインからのバグ報告が有効になります。

3. Solid Queue で Redis 不要

GitHub Issue の作成は外部 API 呼び出しを含むため、非同期ジョブで処理しています。

Rails 8 標準の Solid Queue を採用しました。Active Record ベースのジョブキューなので、Redis を立てる必要がありません。

# 本番: solid_queue（DBベース）
# 開発: async（インメモリ）
# テスト: test（同期実行）

GCP で Redis インスタンス（Memorystore）を立てると月数千円かかるので、個人開発ではこの差は大きいです。

4. GitHub App 方式の Issue 作成

GitHub 連携は Personal Access Token ではなく GitHub App 方式を採用しました。

Installation Token を自動発行・自動更新
リポジトリ単位のスコープ制御が可能
ユーザーの PAT を預からないのでセキュリティ面で安心

[バグレポート作成]
  → [非同期ジョブ]
    → [GitHub App Installation Token取得]
      → [GitHub API: Issue作成]
        → [ラベル付与（severity + 自動生成タグ）]

開発プロセス

Claude Code を使ったフェーズ管理

サクッと作りたかったので開発は Claude Code を活用し、以下の 4 フェーズで進めました。

フェーズ	内容
Phase A	要件定義・設計（SPEC.md、TASKS.md、ADR）
Phase B	実装: 骨格（API、DB、認証、基本UI）
Phase C	実装: 仕上げ（i18n、Widget、E2E テスト）
Phase D	レビュー・品質確認

各フェーズにゲート条件を設け、条件を満たさないと次に進めない運用にしました。設計判断は ADR（Architecture Decision Record）として都度記録しています。

テスト

RSpec: 106 examples, 0 failures
RuboCop: 52 files, 0 offenses
Frontend: TypeScript + ESLint clean
Widget: TypeScript clean, 13KB gzip

無料のローカル版も公開

外部サービス不要で docker compose up だけで動く OSS 版 bugoon-local も公開しています。

Firebase なし、認証なし、SQLite で完結
社内ネットワークなどインターネット接続なしの環境でも使える
ウィジェットは共通（firebaseBucket 未設定で Local モードに自動切替）

今後やりたいこと

画面録画対応: スクリーンショットだけでなく、操作の録画も添付できるようにする
Slack / Discord 連携: バグ報告時にチャットツールへ自動通知
チーム機能: 複数メンバーでのプロジェクト共同管理
AI サマリー: バグレポートの内容を AI が要約し、より精度の高い Issue を自動生成
Jira / Linear 連携: GitHub 以外のプロジェクト管理ツールへの対応

おわりに

「バグ報告が面倒」「AI に修正させたいけど Issue の質が低い」という課題を解決するために Bugoon を作りました。

JavaScript タグを1行貼るだけで使えるので、ぜひ試してみてください。フィードバックも歓迎です。

サービス: https://bugoon.com
ローカル版 (OSS): https://github.com/ruby-inc/bugoon-local

採用情報

ルビージョブス株式会社では、Claude Code や Cursor などを活用した AI 駆動開発による受託開発を一緒に進めていただける PM・エンジニアの方を業務委託・正社員など問わず募集しています。興味のある方はぜひご連絡ください。