gjalla-debug

デバッグ

ここでの役割は、まだ何かを修正することではありません。実際に何が起きているのかを突き止め、調査の過程を示せるようにすることです。自信満々の誤診は、診断がないよりも大きな損失を招きます。その診断の上に築かれたものをすべて取り消さなければならなくなるからです。

常に警戒すべき失敗パターンは、早い段階で仮説を立て、それを裏付ける情報だけを読むことです。部分的な調査も、調査している本人には完全なものとまったく同じように感じられます。

プロセス

1. 症状を正確に把握する

コードに触れる前に、実際に何が観測されたのかを明確にします。誰が、どの画面で、どのような入力を使い、どのくらいの頻度で、いつから見ているのかを確認します。「壊れている」と「セッション中の2回目の保存で古いデータが返る」では、調査内容がまったく異なります。

報告が曖昧な場合、まず出すべき有用な成果物は、修正ではなく問題をより明確に説明したものです。

2. 再現するか、できなかったことを明言する

実際に動かしてください。動作を観察できるのに、コードがどう動くかを推測してはいけません。コードを読むだけでフローを追うと、条件分岐や、すでに存在しないコードについて説明している古いコメント、本番でしか発生しないデータ形状の陰にバグが隠れてしまいます。

再現できない場合は、そのことを明確に伝え、再現を必要としない証拠、つまりログ、テレメトリー、データベースの状態、エラーレポートに切り替えます。再現できないバグでも診断はできますが、確信度は異なるため、報告でもその違いを示してください。

3. 読んでいる内容が最新であることを確認する

確認にかかる手間はわずかですが、怠ると調査全体が無効になることがあります。チェックアウトしたコードがデプロイ済みのものと一致していること、古いワークツリーやベンダーコピーを読んでいないこと、参照しているキャッシュ済みの成果物が最近再生成されたことを確認してください。放棄されたブランチの grep 結果も、稼働中のコードの grep 結果と同じように見えます。

4. 仮説を立てる前に背景を集める

gjalla を確認し、すでにわかっていることを調べてください。ルール、メモ、変更履歴には、これから再発見しようとしている落とし穴がそのまま記されていることがよくあります。また、アーキテクチャを見れば、実際にどのコンポーネントが処理経路上にあるのかがわかります。誰かが以前に同じ問題に遭遇し、発生理由を書き残しているかもしれません。

5. 観測したことと推測したことを分ける

自分のメモでも報告でも、両者を区別してください。「レスポンスボディが空である」は観測です。「シリアライザーがフィールドを落としている」は推測です。推測を確定事項として扱う前に、コードまたはデータで確認する必要があります。確認できなかった推測を報告する場合は、その旨を明記してください。

6. 症状を解消するだけの最初の手段ではなく、根本原因を見つける

壊れた状態を生み出した行だけでなく、そもそもなぜその状態に到達できたのかを考えてください。ガードの欠如は通常、不変条件を自然に強制できない仕組みがあることの症状です。

制限、タイムアウト、再試行回数、予算を変更する前に、git の履歴とコメントを確認して意図を調べてください。こうした数値は意図的に設定されていることが多く、以前のインシデントを受けて存在している場合もあります。

7. リポジトリ全体でバグのパターンを列挙する

欠陥の形がわかったら、リポジトリ全体でそのパターンを grep してください。ガードなしで呼び出されるメソッド、使われていないヘルパー、繰り返されているパターンを探します。そして件数を報告してください。見つけた1か所だけを修正し、ほかの3か所を残すのは、来月また報告されることになる修正です。

パターンがサービス境界をまたぐ場合は、ほかのリポジトリも確認してください。

8. 証明する

根本原因を特定した証拠となるのは、修正前には失敗し、修正後には正しい理由で成功するテストです。可能であれば、修正前にテストを書いてください。提案した修正を適用してもそのテスト結果が変わらないなら、説明がどれほどもっともらしくても、原因の見立てが間違っています。

出力

• 症状：何が観察され、どのような条件で発生するかを正確に記述します。
• 根本原因：その仕組みを、ファイル名と行番号の根拠とともに説明します。
• 到達可能だった理由：表面化した場所だけでなく、この状態が存在できた理由を説明します。
• 影響範囲：同じ形が見られる他のすべての場所を、件数とともに列挙します。
• 確信度：直接確認したこと、推測したこと、判断できなかったことを示します。
• 修正案：修正を立証するテストも含めます。

修正が単純でない場合、またはシステムプリミティブに触れる場合は、ここで作業を止め、直接実装せずにgjalla-specへ引き継いでください。

原則

• 推論より証拠を重視します。 実行、観察、照会ができる場合は、コードを根拠に議論するのではなく、実際に行ってください。
• わからないことも報告します。 「再現できず、診断の根拠はログの1行のみです」は、有用で誠実な報告です。根拠のない自信は禁物です。
• バグが表面化した場所に原因があるとは限りません。 スタックトレースが示すのは、問題が見えるようになった場所です。その場所は、問題が発生した場所から数層下流にあることがよくあります。
• 学んだことを保存します。 すぐにはわからない原因は、gjalla memoryに記録すべき内容です。次のエージェントや次回の自分が、同じことを再発見せずに済みます：gjalla memory add "<the fact>" -n "<short-name>"。