easy-wins

すぐにできる改善

システム全体をよりシンプル、安全、高速にする、またはリグレッションを起こしにくくする、範囲の明確な変更を1つ見つけます。別の整理作業に着手するより、作業を完了させることを優先してください。

運用ルール

提案がすぐにできる改善に当たるのは、次の条件をすべて満たす場合に限ります。

• 範囲が具体的であること：対象となるファイル、シンボル、依存関係、アセット、テスト、または移行手順が特定されている；
• メリットがユーザーまたは多くのメンテナーに及ぶこと。提案者だけのメリットではない；
• 問題と提案する修正を裏付ける証拠があること；
• 1つの小さな PR でレビューとテストができること；
• リスクが把握され、検証計画があること；
• エントロピーを減らすこと：概念、依存関係、経路、例外、古くなった事実、または以前の状態に戻る手段が減ること。

これを一般的なアーキテクチャレビューにしないでください。「モジュール性を改善する」「テストを増やす」といったテーマではなく、修正可能な候補を提示してください。

実行手順

1. 調査範囲を定める

提案の前に、次を調査します。

1. 作業ツリー、現在のブランチ、プロジェクトの指示、パッケージマニフェスト、ビルド／テスト／lint コマンド、既存のコントリビューションルール。
2. 最近の履歴（git log、おおむね過去30～90日）。繰り返し変更されたファイルやサブシステム、直近で変更されたものを重点的に確認します。
3. リポジトリのツールで手軽に確認できる場合は、オープン中の PR／issue も調べます。対応中の作業や、最近完了した作業を提案しないよう、オープン中の項目と最近クローズされた項目を確認します。
4. 変更の多い領域のコードと設定。リポジトリ標準の検索・分析ツールを使い、ファイル名だけから推測しないでください。

有用な候補を証拠付きで見つけるために必要な、最小限の調査から始めます。最初の調査で候補が見つからない場合に限り、範囲を広げてください。

2. 効果の大きい完了点を探す

おおむね次の順で、以下の兆候を探します。各候補には主要カテゴリを1つ割り当て、実装手法は別カテゴリではなくタグとして扱います。

• 削除と統合：不要な依存関係、スクリプト、設定、コード、エクスポート、機能フラグ、アセット、生成物、重複する動作、到達不能な経路、冗長なフォールバック；
• 移行の完了：残る手順、互換性シム、二重経路、またはフォールバックが明らかな古い移行；
• 依存関係のメンテナンス：大幅に古い依存関係、またはセキュリティ上・メンテナンス上のコストがある依存関係。アップグレードを提案する前に、変更履歴／リリースノートと互換性を確認してください；
• リグレッションと境界のテストカバレッジ：価値の高い境界で不足しているテスト。特に、実際のバグや頻繁に変更される経路を対象とするリグレッションテスト；
• テスト容易性と境界の簡素化：小さな純粋関数への切り出しや明示的な境界によって、抽象化を増やさずに動作を検証しやすくできる、副作用を伴う接続部分；
• 開発者と CI のフィードバックループ：ローカルで測定可能な修正ができる、遅い、不安定、ノイズが多い、または非決定的なツール；
• 信頼性と障害時の修正：握りつぶされるエラー、安全でないフォールバック、不足しているタイムアウトや復旧処理、非決定性、不完全または破損した入力への不適切な対応；
• セキュリティとプライバシーの強化：安全でないログ出力、過度に広い権限、安全でないデフォルト、境界検証の不足、または古くなった認証情報／設定の経路；
• 契約とドキュメントの乖離：実装の詳細やプロジェクトの誤った動作を記述している、古くなったコメント、ドキュメント、例、テスト、または生成出力。

ユーザー向けの動作、UX、アクセシビリティ、またはプロダクトの変更は提案しないでください。これらには関係者との協議が必要です。実行時のパフォーマンス改善を対象に含められるのは、プロダクトの動作を変えず、プロダクト上の判断も必要としない、効果を測定可能な局所的な実装変更がある場合に限ります。

削除を主張する場合は、インポート／参照、スクリプト、設定、動的読み込み、生成ファイル、文書化されたコマンド全体を確認し、利用されていないことを証明してください。移行については、新旧両方の経路と、最後に削除または切り替えを行う箇所を特定してください。依存関係のアップグレードについては、単にバージョンが古いことを価値の根拠とせず、変更履歴／リリースノートと互換性を確認してください。

3. 候補をスコアリングする

候補をちょうど5件作成し、順位を付けます。すべての候補はエビデンスの基準を満たし、確実に効果が見込めるものにしてください。弱い候補でリストを埋めるのではなく、必要に応じて調査を続けるか、対象範囲を広げてください。各候補が条件を満たす場合は、主要カテゴリに偏りがないようにします。各候補には主要カテゴリを1つ設定し、実装手法はタグとして別途記録します。各項目を1～5で評価してください。

• Impact（影響）：ユーザーにとっての利点、信頼性、セキュリティ、パフォーマンス、またはメンテナーへの波及効果。
• Reach（対象範囲）：恩恵を受けるユーザー、実行回数、パッケージ、またはコントリビューターの数。
• Confidence（確信度）：問題と修正が実在することを示す直接的なエビデンスの強さ。
• Recency（最近性）：最近変更されたコードや進行中の作業との関連性。
• Finishability（完了可能性）：範囲が限定されており、小規模なPR 1件で完了できる見込み。
• Entropy reduction（エントロピー削減）：取り除かれる概念、依存関係、パス、例外、または古くなった情報。以前の状態が再び生じない場合は加点します。
• Cost（コスト）：想定される実装およびレビューの工数。高いほど悪い評価です。
• Risk（リスク）：回帰、互換性、移行、または段階的な導入に伴うリスク。高いほど悪い評価です。

すべての見積もりを示し、透明性のある順位スコアも計算してください。

leverage = impact × reach × confidence × finishability × entropy reduction

leverage を cost × risk で割ります。計算式に recency は含めないでください。最近の変更はまだ十分に練られていない可能性があるため、recency は状況証拠として扱い、confidence、entropy reduction、reach、finishability を考慮した後のタイブレークにのみ使ってください。最近の変更は関連性を示すものであり、リスクの高い変更を行う許可ではありません。影響が大きいというだけで、リスクの高い項目を推奨しないでください。

候補はエントロピーを削減する、回帰を防ぐ、または測定可能な利点をもたらす必要があります。他の条件が同等の場合、entropy reduction をより重視してください。

4. 提案を提示する

ちょうど5件を提示してください。最も推奨する候補を先頭に置きます。各提案には次の項目を含めてください。

• Category（カテゴリ）：検索分類から選んだ主要カテゴリを1つ。
• Tags（タグ）：削除、移行、抽出、テスト、依存関係の変更などの実装手法。
• Title（タイトル）：アクションと具体的な対象。
• Evidence（エビデンス）：コマンド、履歴、参照情報、または測定値、およびそれらが示すこと。
• Change（変更）：対象となる正確なファイル、シンボル、または依存関係と、実行可能な最小限の差分。
• Benefit（利点）：誰がどのような恩恵を受け、エントロピーの削減、回帰の防止、または測定可能な利点がどのように実現するか。
• Scores（スコア）：impact、reach、confidence、recency、finishability、entropy reduction、cost、risk。recency も報告しますが、計算式には含めません。
• Verification（検証）：失敗を検出できるテスト、静的チェック、ベンチマーク、ビルド、または実行時チェック。
• Residual risk（残存リスク）：残る不確実性と、その抑制方法。
• PR shape（PR の形）：想定されるタイトル、変更対象ファイル、移行メモまたはリリースノートが必要かどうか。

エビデンスが不完全な場合は、そのことを明確に述べてください。「使われていない可能性がある」は調査の手がかりであり、削除提案ではありません。

ユーザーに候補を1つ選ぶよう依頼してください。調査中にコードを編集したり、ブランチを作成したりしないでください。作業ツリーに未コミットの変更がある場合は、候補を調査して報告しますが、クリーンなベースラインが確立するまで実装は行わないでください。

5. 選んだ候補を実行する

ユーザーが選択した後：

1. スコープ、成功の確認項目、リスクを短い計画にまとめて再提示します。選択した変更が提案と大きく異なる場合、または本番環境やデータに不可逆な影響を与える場合を除き、追加承認を求めずに進めます。
2. 最新のデフォルトブランチを取得し、そこから変更範囲を絞ったブランチを作成して、該当するコードを正確に確認します。提案で明示的に変更する場合を除き、公開されている動作を維持します。
3. 最小限の変更を行います。外部から観測できる動作の境界でテストを追加または調整します。実装詳細に依存するテストを削除するのは、残るテストで契約が引き続き網羅されている場合に限ります。
4. まず対象を絞ったチェックを実行し、その後、リポジトリで必須の lint、型チェック、ビルド、テストの各コマンドを実行します。失敗は失敗として報告し、成功させるためにチェックを弱めてはいけません。
5. 再導入がないか再確認します。古いインポート、互換性パス、参照、ドキュメント、ロックファイルのエントリー、生成物、不要なテストを調べます。削除の場合は、対象が存在しないことと、ビルドが引き続き成功することを確認します。
6. 一貫性のある変更を1つコミットし、ブランチをプッシュして、リポジトリの慣例に従って PR を作成します。PR のタイトルと本文には、簡潔な What と Why に加え、根拠、検証内容、リスク、エントロピーの削減を記載します。説明には AI generated と明記します。別のクリーンアップを PR にまとめてはいけません。リポジトリで PR を使っていない場合、またはリモートにアクセスできない場合は、変更範囲を絞ったパッチを残し、残っている引き継ぎ事項を正確に報告します。

根拠とリスクの基準を満たす候補がない場合は、「簡単に実現できる改善は見つかりませんでした」と報告し、根拠が不足している点とともに、有力な次点候補を示します。毎日の提案を無理に作ってはいけません。

PR を作成したら終了します。レビューとその後の対応は人が行います。

完了の条件：選択した範囲の実装が済み、根拠に基づくチェックに合格し、削除が目的の場合は古い経路がひそかに残存または再導入されないことを確認し、PR が作成されているか、残っている障害が正確に報告されていること。

品質基準

大規模なリファクタリングより、単純な削除、完了した移行、対象を絞った回帰テスト、または効果を測定できるツールの改善を優先します。ネイティブコードを優先するのは、より小さく明確で、プロジェクトのランタイム対応範囲でサポートされ、動作上同等である場合に限ります。コメントやドキュメントもコードと同様に扱います。古くなった事実は削除しつつ、コードから読み取れない理由は残します。

セキュリティに関わる変更、データを破壊する変更、公開 API の変更、または大規模な依存関係の変更を、リスク、互換性の根拠、ロールバックまたは段階的展開の計画を明示せずに「簡単に実現できる改善」として提案してはいけません。基準を満たす候補がない場合は、勢いを作り出すのではなく、そのことを率直に伝えます。