Claude Code や Cursor にバグ修正を任せてみて、「思ったのと違う修正が返ってきた」「見当違いのファイルを触られた」という経験はないでしょうか。多くの場合、原因は指示文の書き方ではありません。エージェントに渡した情報の粒度が足りていないことが原因です。

指示文より情報が成否を決める

人間のエンジニアは、曖昧なバグ報告を受け取っても「たぶんこのあたりだろう」と経験で補完できます。AIエージェントはこの補完が苦手です。渡された情報の中だけで仮説を立てるため、情報が足りないと存在しない原因を探して無関係なファイルを編集し始めます。

つまり指示文を凝ることよりも、「一発で通る情報セット」を毎回同じ形で渡す仕組みを作るほうが効果があります。

一発で通る情報セット・5点

1. 再現手順

「どの画面で」「何を」「どの順番で」操作したかを番号付きで書きます。「ログイン後、プロジェクト一覧からカンバンを開き、カードをドラッグする」のように、エージェントがそのままなぞれる粒度にします。

2. 期待と実際の差分

「期待: ステータスが In Progress に変わる」「実際: カードが元の列に戻る」のように一文ずつ対比させます。ここが曖昧だと、エージェントは「バグの定義」自体を推測することになります。

3. 該当画面・該当コード箇所

URLやコンポーネント名、可能ならファイルパスまで含めます。「カンバンのどこか」ではなく「frontend/components/kanban/BugReportCard.tsx 周辺」まで絞れると、探索コストがゼロに近づきます。

4. エラーログ・スタックトレース

コンソールエラーやネットワークエラーの生ログをそのまま貼ります。要約してしまうと、エージェントが手がかりにするはずのスタックトレースの行番号やエラーコードが失われます。

5. 受入条件

「何が起きれば直ったと言えるか」を Given/When/Then 相当で書きます。受入条件がないと、エージェントは自分で「直った」と判断してしまい、実際にはユーザーが期待する状態と食い違うことがあります。

渡さないとどう迷走するか

実際によくあるパターンを挙げます。

再現手順が無い → エージェントが関連しそうな複数のコンポーネントを総当たりで修正し、無関係な箇所までdiffが膨らむ
期待と実際の区別が無い → 「〇〇がおかしい」だけを渡すと、見た目の些細な違いを直して本質的なロジックのバグを見逃す
エラーログを要約して渡す → 「Network error が出ています」だけでは、408なのか500なのか、どのAPIなのかが分からず、当てずっぽうの例外処理を追加される
受入条件が無い → 修正はされたがテストが無いままPRが作られ、レビューで同じ指摘を繰り返すことになる

情報を集めるチェックリスト

バグ報告を受け取った時点で、以下が揃っているか確認してからエージェントに渡すと手戻りが減ります。

□ 再現手順が番号付きで書かれているか
□ 期待と実際が別の文で書き分けられているか
□ 該当画面のURLまたはコンポーネント名があるか
□ コンソール／ネットワークのエラーが生ログで貼られているか
□ 「直った」と判定できる受入条件があるか

この5点が揃わない報告は、エージェントに渡す前に一度差し戻すほうが結果的に早く終わります。

Bugoon での実践

Bugoonでは、報告フォームでスクリーンショット＋アノテーションと操作ステップの記録を組み合わせることで、上記5点セットのうち「再現手順」「該当画面」を報告時点である程度自動的に埋められます。バグレポートはGitHub Issue連携でそのままIssue化されるため、再現手順・スクリーンショット・操作ステップが1つのIssueに集約された状態でエージェントに渡せます。

さらにBugoon MCP サーバーを使うと、Claude CodeやCursorから直接バグレポートの詳細（アノテーション画像やステータス）を取得できます。人が情報をコピー＆ペーストする工程を挟まずに、上記5点セットに近い情報をエージェントへそのまま渡せるのが実務上の利点です。

AIエージェントの修正精度を決める情報設計