| name | upstream-fix |
| description | 修正・バグ修正・リファクタリングの依頼時に、末端パッチではなく上流での根本解決を優先するスキル。
「これ直して」「バグがある」「修正して」「ここがおかしい」「リファクタリングして」「設計を見直して」
「場当たり的じゃなくちゃんと直して」「根本から直して」といった依頼で使う。
コード修正の依頼全般で使うこと。単純な typo 修正や1行の変更でも、周辺に根本的な問題が潜んでいないか
確認するために一度このスキルのワークフローを通す価値がある。
|
Upstream Fix - 上流解決スキル
修正依頼を受けたとき、その場しのぎのパッチではなく、設計レベルで根本原因を解決するためのワークフロー。
末端でのパッチは「今この瞬間」は最速に見える。しかし同じ種類の問題が別の場所で再発し、パッチが積み重なってコードベースが複雑化する。上流（データの流れの源流、抽象化のより高いレイヤー、設計の根本）で直せば、下流の問題が一括で消える。修正コストは一度だけ、効果は永続的。
Phase 1: 現状把握
修正に手をつける前に、現状を正確に理解する。
- コミット履歴を読む - 直近のコミットから、この領域でどんな変更が行われてきたかを把握する
- 関連コードを広く読む - 報告された問題箇所だけでなく、周辺・呼び出し元・呼び出し先も読む。「症状」の場所と「原因」の場所は違うことが多い
- データの流れを追う - 問題のあるデータや状態が、どこで生まれ、どこを通って、どこで問題を起こしているかをトレースする
Phase 2: 診断
現状把握の結果を整理し、ユーザーに共有する。
## 診断結果
### 症状（ユーザーが報告した問題）
- [何が起きているか]
### 直接原因（症状を引き起こしているコード）
- [どのコードが問題か、なぜそうなっているか]
### 根本原因（なぜそのコードがそうなっているか）
- [設計上の問題、データフローの問題、責務の曖昧さなど]
### 影響範囲
- [同じ根本原因から生じている、または生じうる他の問題]
Phase 3: 設計判断
「今あるコードをどう直すか」ではなく、「この領域を今からゼロで作るならどう設計するか」を考える。
観点:
- 責務の配置: この処理はここにあるべきか？もっと上流で処理すべきでは？
- データの正規化: 下流で何度も変換・チェックしているなら、上流で一度だけ正しい形にすべきでは？
- 契約の明確化: 関数間・モジュール間の暗黙の前提を、型や明示的なバリデーションで契約にできないか？
- 抽象化のレベル: 似たパッチが複数箇所にあるなら、共通の抽象化が足りていないのでは？
「ここまでやれば綺麗になる」が見えたら、その全体像をユーザーに提案する。一見関係なさそうに見える領域でも、根を辿れば同じ設計上の問題に繋がっていることがある。そういう繋がりが見えたなら、それも含めて提案する。見えている改善を黙っているのは機会損失。
Phase 4: 提案
修正方針を選択肢として示す。
## 修正方針
### A: フル改善（ここまでやれば綺麗になる）
- 何をするか: [根本原因の解消 + 周辺の設計改善]
- 影響範囲: [変更が及ぶファイル・機能]
- メリット: [この領域全体がスッキリする、今後の変更も楽になる]
### B: 上流修正（報告された問題の根本解決）
- 何をするか: [根本原因の解消に絞った変更]
- メリット: [根本解決、再発防止]
### C: 局所修正（最小パッチ）
- 何をするか: [症状を直接修正]
- メリット: [変更が小さい、リスクが低い]
- リスク: [再発の可能性、技術的負債の蓄積]
判断ガイド:
- 緊急の本番障害 → C で止血、後日 A or B
- 通常の修正依頼 → B を推奨
- 「ちゃんと直して」「綺麗にして」→ A を推奨
- 急ぎでない場合やユーザーが明示的に「ちゃんと直して」と言っている場合 → 提案をスキップして A で進めてよい
A が見えているなら必ず提案に含める。
Phase 5: 実装
選択された方針に沿って実装する。
- 変更の粒度: 1つのコミットに1つの関心事。リファクタリングと機能修正は分ける
- WHY を残す: なぜこの設計にしたか、なぜ上流で直したかをコメントやコミットメッセージに書く
- テスト: 根本原因に対するテストを書く。症状に対するテストだけでは不十分
上流修正の判断基準
| シグナル | 上流修正すべきか |
|---|
| 同じ種類の修正が複数箇所にある | はい - 共通の原因がある |
if や特殊ケース分岐が増えている | はい - データの正規化不足 |
| 「ワークアラウンド」「暫定」コメントがある | はい - 本来の解決が別にある |
| 修正箇所がデータの流れの下流にある | はい - 上流で正しいデータを作るべき |
| 問題が1箇所だけで設計に問題がない | いいえ - 局所修正で十分 |
| 緊急の本番障害 | まず局所修正、後日上流修正 |
アンチパターン
- 症状だけ消す: エラーを握りつぶす、表示を隠す、条件分岐で回避する
- コピペパッチ: 同じ修正を複数箇所に適用する（→ 共通化すべきサイン）
- 下流でバリデーション追加: 本来は上流で正しいデータを保証すべき
- 改善の可能性を黙殺する: 「ここまでやれば綺麗になる」が見えているのに提案しない
