エラーを、観察できる依頼に変える

検索を付けたのに、ある言葉だけ見つからないことがあります。そんなときに「バグを全部直して」と頼むと、表示まで作り直されることがあります。

この回では、変更を始める前に症状を絞ります。題材は、ナレッジデスクの検索です。再現条件を残せば、修正後も同じ条件で判断できます。

この回で残すのは、再現手順と、その症状を確かめるテストです。機能は増やしません。

図を拡大 ↗

症状：まず同じ状態を作る

完成見本では、検索欄に半角の onboarding でも全角の ＯＮＢＯＡＲＤＩＮＧ でも同じ資料が1件出ます。自分の実装で結果が違うなら、表記の揃え方を調べる題材になります。

正しく動いている場合は、わざと壊す必要はありません。次の報告を「仕様の確認」として使い、既存テストに同じケースがあるか確かめてください。

「時々おかしい」では、直ったかどうかを確かめられません。どの入力、どの操作順で起きるのかを残します。

依頼：編集の前に、原因を説明してもらう

次の指示では、実際に観察した結果を入れます。存在しないエラーをそのまま送らないでください。

ナレッジデスクの検索を調べてください。まだ編集しないでください。

再現: index.htmlを開き、カテゴリ「すべて」で
検索欄に全角のＯＮＢＯＡＲＤＩＮＧを入力します。
期待: 新入社員の資料が1件。
実際: [自分が観察した結果を記入]

data.js、domain.js、app.js、tests/search.test.mjsを読み、
入力から結果表示までを追ってください。
分かった事実、原因の仮説、仮説を確かめる最小のチェックを
分けて報告してください。新しいライブラリは追加しないでください。

原因の仮説が「全角と半角の違い」なら、domain.js の正規化処理を確認します。完成見本は normalize("NFKC") で文字の表記を揃えています。さらに大文字小文字と前後の空白を揃え、検索語を比較します。

別の原因が考えられるなら、その証拠に合わせて調査を変えます。たとえば、検索関数のテストは通るのに画面だけ違うなら、イベント処理や読み込んだファイルを調べます。

修正：期待値を変えずに確かめる

症状を示すテストが失敗するところまで確かめてから、原因に関係する部分を修正します。テストを通すために「期待は0件だったことにする」のは、問題を隠す変更です。

報告した原因を、小さなテストで再現してください。
先にそのテストが意図した理由で失敗することを確認し、
原因に関係する部分だけを修正してください。

修正後は新しいテストと既存の検索テストを実行し、
実行コマンド、終了結果、変更ファイルを示してください。
期待する件数や既存のテストを、都合よく変更しないでください。
最後にブラウザで確認する操作を教えてください。

テストが通ったら、ブラウザで同じ入力を試します。空の検索、該当する資料がない検索、カテゴリとの組み合わせも確認します。関係する動作が崩れていないかを見るためです。

つまずき：同じ修正を繰り返している

直したはずなのに画面が変わらないときは、まず開いているフォルダを確認します。別の index.html を開いている、ブラウザの再読み込みが必要、スクリプトにエラーがある。原因はコードの中に限りません。

コンソールのエラーを渡すときは、関係する数行だけを選びます。会社のURLや個人データ、認証情報が混ざっていないかを確認してください。

同じ仮説で何度も失敗したら、いったん止めます。症状、試したこと、残った仮説をファイルにまとめ、新しい会話でその記録から調査します。Terminalの /clear は会話の文脈を切る操作で、コードを戻す操作ではありません。

完成条件：修正の根拠が揃った

• 再現手順を別の人が読んでも同じ操作をできる。
• 仮説を確かめるチェックと、その結果が残っている。
• 同じ操作で期待する結果になり、既存の検索とカテゴリも動く。
• 変更が原因に関係する範囲に収まり、未確認のことが分かる。

今日のまとめ

• 症状を、操作・期待・実際の結果に分けると調査を始められます。
• 原因の仮説を、小さなテストで確かめてから修正します。
• 自動テストが通っても、実際の画面で同じ操作を確認します。

次は権限を決めて、繰り返しを減らすへ進みます。

参考・出典

• Anthropic：Best practices（検証条件と原因の調査）
• Anthropic：Debugging workflow
• MDN：String.prototype.normalize