fix-bug

バグ修正と小規模な改善

プロジェクトに PRINCIPLES.md、AGENTS.md、CONTRIBUTING.md など、明示された原則がある場合は、すべての変更でそれらを念頭に置いてください。また、いずれの場合も次の原則に従ってください。推測する前に計測すること、コードがすでに備えている機能を優先すること、提案された仕組みではなく、達成したい結果を出発点にすること。

プロジェクトに docs/acceptances/ATTENTION.md がある場合は、それも読んでください。受け入れテストから得られた体系的な教訓が記されています。そこに記載された項目に該当するバグは、パターンの一例です。その事例を修正し、その旨を伝えて、パターンの記録に追加してください。

製品に関する判断を、決して独断で下さないでください。 どんなに小さな修正でも、お客様に見えるものや製品の動作（エラーメッセージ、例外的なケースの結果、デフォルト値など）を変える可能性があります。そうした場合は作業を止め、最終的にお客様にどのような体験を提供すべきか、ユーザーに確認してください。理由を添えて解決策を推奨し、判断はユーザーに委ねてください。

影響範囲が大きい変更も同様です。 アーキテクチャの変更、新しい依存関係、データモデルやドメインモデルの変更など、システムへの深い理解が必要で、元に戻すのに大きなコストがかかる変更は、事前に確認せずバグ修正に含めてはいけません。簡潔な言葉で確認してください。質問ごとに判断事項は一つとし、それぞれの選択肢が意味することと、推奨案を伝えてください。

永続化されるスキーマや形式の変更は、計画に組み込む前に告知してください。 永続化されるスキーマまたは形式のバージョンを上げる場合も、新しいマイグレーションを追加する場合も（データベースのスキーマ、ファイル形式、通信形式や同期形式、設定の構成など）、ユーザーに「これはデータベースのスキーマを変更します」（または「…のファイル形式を変更します」）と明確に伝え、何かがその変更に依存する前に同意を得てください。マイグレーションは、対象となるすべてのストアに変更を記録し、ロールバックされることはほとんどありません。そのため、実装時に突然明らかにするのではなく、最初に判断すべきことです。マイグレーションを伴う最初の実行の前に、使い捨てのデータ（別のデータディレクトリ、プロファイル、またはテスト用データベース）を使って実行するよう、ユーザーに念を押してください。共有データや実データには決して実行しないでください。

まず、メインの統合ブランチとの差分を確認してください。 診断は最新のコードに基づいて行う必要があります。git fetch を実行してから git log --oneline <branch>..<main> を実行するなどして、ブランチがメインの統合ブランチ（例：main や dev）からどれだけ遅れているかを確認してください。遅れている場合はその旨を伝え、取り込む前に確認してください（merge-branch を参照）。マージはブランチを変更し、独自のレビュー承認が必要です。どちらにしても、ブランチの乖離は重要です。バグはすでに修正されている可能性も、該当コードが移動している可能性も、すでに変更されたコードが原因である可能性もあります。そのため、古いコードを黙って調査してはいけません。

バグを修正するとき

1. 原因を説明してください。 修正を書く前に、何が実際に起きたのか、なぜ起きたのかを、レビュー担当者が検証できる形で説明してください。原因が不確かな場合は、計測機能を追加してから再現してください。推測に基づく修正をリリースしてはいけません。
2. 解決策の妥当性を説明してください。 修正内容、検討した代替案、そしてなぜこの案がより優れているのか（より単純である、より堅牢である、既存のモデルに沿っている、または個別のバグではなくその種類のバグをなくすなど）を説明してください。
3. なぜ起きたのかを考えてください。 バグは弱点があることを示す証拠です。重複した仕組み、不足している不変条件、検査できないコンポーネントなど、バグが示す簡素化の余地を探してください。そこも修正または指摘し、単にパッチを当てるだけでなく、コードをより堅牢にしてください。

改善するとき（およびコードに触れるたびに）

• 変更のたびに、コードをより良くする機会があります。名前をわかりやすくする、重複を取り除く、可観測性を高めるための接点を設けるなどを検討してください。
• 大きなファイル： 大きなファイルに変更を加える場合は、自然な形で分割できないか検討してください。ファイル、クラス、関数、モジュールを小さくし、再利用可能な仕組みを切り出して、ドメインの振る舞いはそのドメインに残してください。汎用の受け皿を作ってはいけません。

変更は小さく、レビューしやすい状態に保ってください。リファクタリングが修正の範囲を超えて大きくなる場合は、まとめて行わず、別途提案してください。