コード簡潔化

目的

動作、公開インターフェース、副作用を保ちながらコードを簡潔にします。複雑で圧縮された構造よりも、明示的なコードと局所的な明確性を優先します。

引数

• --no-verify: 検証をスキップします。親のオーケストレーターが最終結果を別途検証します。
• --no-report: 完全なユーザー向けレポートをスキップします。呼び出し元に必要な簡潔な作業ノートのみを保持します。
• デフォルト: 修正された動作を検証し、完全なレポートを提示します。

スコープの解決

1. リポジトリコンテキストを確認: git rev-parse --git-dir。失敗した場合は停止し、ユーザーに git リポジトリから実行するよう伝えます。
2. ユーザーがファイルパス/パターン、コミット/範囲、または Resolved scope フェンスブロック (リポジトリ相対パスを1行ごとに記載) を提供した場合、スコープはそれらのターゲットそのものです。
3. それ以外の場合、スコープはセッション中に修正されたファイルのみです。他のコミットされていない変更は含めません。
4. セッション中に修正されたファイルがない場合、コミットされている追跡対象ファイルと未追跡ファイルすべてにフォールバックします:
   • 追跡対象: git diff --name-only --diff-filter=ACMR
   • 未追跡: git ls-files --others --exclude-standard
   • 両方のリストを組み合わせ、重複を削除します。
5. 特に要求されない限り、生成されたファイルやノイズの多いファイルを除外: ロックファイル、ミニファイ済みバンドル、ビルド出力、ベンダーコード。
6. スコープが 0 ファイルになる場合、報告して停止します。

動作ルール

• ランタイムの動作を正確に保存します。入出力、副作用、エラー動作を安定させます。
• 個人の好みよりも、プロジェクト規約を優先します。既存コード、リンター、フォーマッター、テストから規約を推測します。
• 明示的に要求されない限り、ユーザーが要求したファイルまたは最近修正されたコードに限定します。
• 小さく可逆的な編集を行います。対象を絞った簡潔化で問題が解決する場合、大規模な書き直しを避けます。
• 動作が変わる可能性がある場合、不確実性を即座に指摘します。

ワークフロー

1) スコープを決定する

• 上の「スコープの解決」セクションを使用してターゲットファイルを解決します。

2) 動作ベースラインを構築する

• 変更行だけでなく、周囲のコンテキストを読みます。
• 変更してはいけない不変量を特定します:
  • 関数シグネチャと公開 API
  • 状態遷移と副作用
  • 永続化/ネットワーク動作
  • ユーザー向けメッセージと外部に依存されているエラーセマンティクス
• 利用可能な検証コマンド (リント、テスト、型チェック) をメモします。

3) 簡潔化パスを適用する (この順序で)

1. 制御フロー:
   • ガード句と早期リターンで深いネストをフラット化します。
   • ネストされた三項演算子をより明確な条件に置き換えます。
2. 命名と意図:
   • ローカルコンテキストが安全な名前変更をサポートする場合、曖昧な識別子の名前を変更します。
   • 混在した関心事を意図を示す小さなヘルパーに分離します。
3. 重複排除:
   • 明らかな重複を削除します。
   • 少なくとも 2 つの実際の呼び出し側が恩恵を受け、抽象化が認知負荷を減らす場合のみ抽象化します。
4. データ変形:
   • 密な変換チェーンを、可読性が向上する場合は名前付きの中間ステップに分割します。
   • ホットパスのパフォーマンス特性を安定させます。改善が明示的で測定可能な場合を除きます。
5. 型とコントラクトの明確性:
   • 可読性と安全性を向上させ、広範な変更を強制しない場合、型注釈を追加または厳密にします。
   • 変更するよう明示的に求められない限り、外部インターフェースを保存します。

4) 安全制約を強制する

• 明示的に要求されない限り、同期 API を非同期に変換 (またはその逆) しません。
• 動作が同等のままで検証されない限り、エラー伝播戦略を変更しません。
• ロギング、テレメトリ、ガード、または動作意図をエンコードする再試行を削除しません。
• ドメイン固有のステップを、意図を隠すジェネリックヘルパーに折りたたみません。

5) 検証する

--no-verify が設定されている場合、このステップをスキップします。それ以外の場合:

• 最初に最も狭い有用なチェックを実行します:
  • 修正されたファイルのフォーマッター/リント
  • 修正されたモジュールに関連するターゲットテスト
  • 関連する場合は型チェック
• 高速ターゲットチェックが成功した場合、リスクが保証する場合のみより広いチェックを実行します。
• チェックを実行できない場合、スキップされた内容とその理由を述べます。

6) レポート

--no-report が設定されている場合、完全なレポートをスキップします。そのモードでは、修正されたスコープ、主要な簡潔化、親オーケストレーター向けの残存するリスクをカバーする簡潔な作業ノートのみを保持します。

それ以外の場合、以下を提供します:

1. 修正されたスコープ (ファイル/関数)
2. 簡潔な根拠を伴う主要な簡潔化
3. 実行された検証コマンドと結果
4. 残存するリスクまたは前提条件

簡潔化ヒューリスティクス

• 認知負荷を減らす場合、ネストされたインライン式よりも明示的なローカル変数を優先します。
• コンパクトだが曖昧な条件ツリーよりも、条件あたり 1 つの明確なブランチを優先します。
• 関数の長さを管理可能に保ちますが、行数のためだけに分割しません。
• 意図、不変量、または明らかでない制約を説明するコメントを保持します。
• 明らかなコード動作を言い換えるコメントを削除します。
• 最小文字数ではなく、次のメンテナーの理解時間を最適化します。

アンチパターン

• 投機的なアーキテクチャ書き直しを実行しません。
• 小さなローカル変更を簡潔化する際に、フレームワーク全体パターンを導入しません。
• 理解しやすい重複を不透明なユーティリティレイヤーで置き換えません。
• 無関係なクリーンアップを 1 つのパッチにバンドルしません。

停止条件

以下の場合は停止して指示を求めます:

• 簡潔化に公開 API/コントラクトの変更が必要な場合
• 動作パリティを確実に検証できない場合
• コードがドメイン制約のため意図的に複雑に見える場合
• 要求されたスコープが簡潔化ではなく大規模な再設計を意味する場合

出力コントラクト

--no-report が設定されていない場合、簡潔化結果を次のように提示します:

1. 正確に修正されたファイルとリージョンを表示します。
2. 可読性/保守性の向上に焦点を当てた 1 文で各重要な変更を説明します。
3. 動作保存仮定を明示的に確認します。
4. 実行された検証をまとめます (または明確に省略を述べます)。