debug-looplisted

# Debug Loop ## 使用条件 次のいずれかで使う。 - 原因が明白でないbug、regression、flaky failure - 非同期、retry、cache、lifecycle、複数environment、分散処理が関係する - 同型のtest failureまたはreviewの指摘が2件以上ある - 1回目の修正で直らない、または別の症状へ移った - error messageと実際に失敗した層が一致しているか不明 単純なtypoや、失敗箇所と修正が一意な小変更へ形式的に適用しない。 ## 原則 - root causeを確認する前にhardcode、delay追加、JSON整形回避、例外握り潰し等のquick fixを入れない。 - error stringだけを原因の証拠にしない。code path、state、log、reproductionで裏付ける。 - 観測事実、原因候補、未確認事項、利用者向け対処を分ける。 - 1回の試行では、主仮説と予測する観測signalを1つに絞る。 ## 1. 症状と契約を固定する `_ai/TASK.md` またはactive planへ記録する。 ```markdown ## 症状 - 入力・操作: - 実際の結果: - 期待結果: - 発生環境・version: - 再現率: ## 証拠 - log / stack trace: - failing test: - 成果物: ## 未確認 - ... ``` 期待値は、user requirement、product spec、責任分界、既存の正常挙動から確認する。実装と同時に書いたtestだけを期待値の根拠にしない。 ## 2. 決定的な再現を作る 優先順位： 1. 最小のfailing unit test 2. 固定fixtureによるintegration test 3. 再現script 4. manual procedureとlog/成果物 - 変更前にfailureを確認する。 - 外部API、clock、random、filesystem、process、networkは可能な限り注入・fake化する。 - 「たまに起こる」は、seed、timing、state transition、並行順序を記録して狭める。 - 再現できなければ、修正よりinstrumentation追加を優先する。 ## 3. 実行経路と境界を図にする 特に分散・非同期処理では、次を表にする。 | 段階 | 実行主体・environment | 入力 | state | 次へ渡すもの | 実行しない条件 | failureの見え方 | |---|---|---|---|---|---|---| - errorが起きた層と、後続で呼ぶ予定だった層を混同しない。 - cache、保存済みstate、古いprocess、network restriction、permissionを、直接原因と周辺課題に分ける。 - retry/replayでは、idempotency、duplicate side effect、stale callback、generation/token、cancel条件を確認する。 ## 4. 履歴と既存patternを調べる regressionの可能性がある場合： - `git log -S` または `git log -G` - `git blame` - 関連commit・P