code-simplify

コードの簡素化

目的

動作、公開契約、副作用を維持しながら、コードを簡素化します。デフォルトでは、全体を対象に簡素化を行います。安全な場合は、命名や意図の整理も含め、理解しやすさを大きく高める、または不具合のリスクを減らす、確度の高い簡素化を適用します。

引数

• パス、パターン、コミット／範囲、またはスコープを示す語句：スコープ解決ステップ 2 で使用します。
• --no-report：ユーザー向けの詳細レポートを省略し、呼び出し元には簡潔な作業メモを返します。
• --no-verify：親オーケストレーターが最終結果を別途検証するため、検証を省略します。
• デフォルト：全体を対象に簡素化を行い、変更箇所の動作を検証して、詳細レポートを提示します。

スコープの解決

スコープを一度だけ解決し、その結果を実行中は固定として扱います。

1. リポジトリのコンテキストを確認します：git rev-parse --git-dir。失敗した場合は停止し、ユーザーに Git リポジトリ内で実行するよう伝えます。
2. リクエストに対象（ファイルパス／パターン、コミット／範囲、自然言語で示された対象範囲（例：「パーサーの変更」）、またはリポジトリ相対パスを1行に1つ記載した resolved-scope のフェンス付きブロック）が指定されている場合、スコープはその対象のみです。自然言語で示された対象範囲は、続行する前に具体的なパスに対応付けます。
3. 指定がない場合、スコープはこのセッションで変更されたファイルのみです。つまり、このセッションで以前に作成または編集されたファイルです。その他の未コミット変更は含めません。
4. このセッションで変更されたファイルがない場合、またはこのコンテキストで以前の会話履歴を参照できない場合は、すべての未コミットファイルを対象とし、各コマンドを1回ずつ実行します：
   • 追跡対象：git diff --name-only --diff-filter=ACMR
   • 未追跡：git ls-files --others --exclude-standard
   • 両方のリストを結合し、重複を除外します。
5. 生成物、ベンダーコード、一括データ、情報量の少ないファイルは、明示的に依頼された場合を除き、手作業での簡素化から除外します。対象は、ロックファイル、最小化済みバンドル、ビルド出力、生成出力、ベンダーコード、大規模なデータスナップショットです。除外したファイルが正しさに関係する場合は、任意で excluded-scope とタグ付けしたフェンス付きコードブロックを出力し、リポジトリ相対のパスまたは glob を1行に1つ記載して、検証または不変条件のチェックで確認します。
6. スコープに含まれるファイルが0件の場合は、その旨を報告して停止します。
7. スコープを resolved-scope とタグ付けしたフェンス付きコードブロックで出力し、リポジトリ相対のパスを1行に1つ記載します。このブロックを確定情報として扱い、以降はスコープ解決コマンドを再実行したり、除外対象を再検討したりしません。

作業ルール

• 編集を始める前に、前提を明示します。簡素化や検証方針が変わる複数の解釈がある場合は、それぞれを提示して指示を仰ぎ、作業を停止します。
• 実行時の動作を正確に維持します。入力、出力、副作用、エラー時の動作を変えないでください。
• 個人の好みよりプロジェクトの規約を優先します。既存コード、リンター、フォーマッター、テストから規約を判断します。
• 小さく、元に戻しやすい変更にします。変更するすべての行は、ユーザーの依頼、依頼された整理、または自身の編集に伴う整理に根拠を持たせます。
• 依頼された問題を解決するために必要な最小限のコードを書きます。機能、単一用途の抽象化、推測に基づく柔軟性、依頼されていない設定可能性を追加しません。
• 自身が作り出した問題のみを解消します。自身の変更によって未使用になったインポート、変数、関数、ファイルを削除し、変更前から存在する未使用コードは削除せず、「残るリスク」に記載します。
• 命名のみのリファクタリングは、具体的な明瞭さまたは安全性の向上につながり、安全に検証できる場合に限って行います。
• 生成物、ベンダーコード、一括データ、情報量の少ないファイルについては、可能であれば生成器、スキーマ、または契約を簡素化し、生成された各行やファイルを直接編集するのではなく、不変条件のチェックで出力を検証します。
• 動作が変わる可能性がある場合は、ただちに不確実性を伝えます。

ワークフロー

1）スコープの決定

• 「スコープの解決」セクションを適用します。
• excluded-scope ブロックに記載された対象は、手作業での簡素化から除外しますが、検証計画には含めます。

2) 動作のベースラインを作成する

• 変更された行だけでなく、前後のコンテキストも読みます。
• 変更してはならない不変条件を特定します。
  • 関数シグネチャとエクスポートされる API
  • 状態遷移と副作用
  • 永続化やネットワークに関する動作
  • 外部から依存されているユーザー向けメッセージやエラーの意味
• 利用可能な検証コマンド（lint、テスト、typecheck）を確認します。
• 編集前に成功条件を定義します。複数の手順が必要な作業では、各手順に検証チェックを明記した簡潔な計画を立てます。

3) 簡素化の機会を見極める

• 簡素化によって理解しやすさが確実に大きく向上する、現在の変更に伴う不要な処理が取り除かれる、または不具合のリスクが低減される場合を除き、編集しないことを基本とします。
• 広範な書き換えよりも、動作を保つ局所的な編集を優先します。
• 何も変わらない編集は行いません。対象のコードがすでに十分明確であれば、無理に変更せず、その旨を報告します。
• 識別子の名前変更やヘルパーの分割は、明確さや安全性が具体的に向上し、安全な検証手段がある場合にのみ行います。好みだけを理由に API の構造を変えてはいけません。

4) 簡素化のパスを適用する

次のチェックリストを上から順に適用します。

1. 制御フロー：
   • ガード節や早期リターンを使って、深いネストを解消します。
   • ネストした三項演算子を、より明確な条件分岐に置き換えます。
2. 命名と意図：
   • ローカルのコンテキストから安全に変更できる場合は、曖昧な識別子の名前を変更します。
   • 異なる関心事を、意図が伝わる名前を付けた小さなヘルパーに分けます。
3. 重複：
   • 明らかな重複を取り除きます。
   • 実際に少なくとも 2 つの呼び出し箇所で役立ち、認知負荷を軽減できる場合にのみ抽象化します。
4. データ整形：
   • 可読性が向上する場合は、複雑な変換チェーンを、名前付きの中間ステップに分けます。
   • 明示的な測定に基づく改善がない限り、パフォーマンスが重要な処理の特性を維持します。
5. 型と契約の明確化：
   • 可読性と安全性が向上し、広範な変更を強いない場合は、型注釈を追加または厳格化します。
   • 変更を求められていない限り、外部インターフェースを維持します。

5) 安全性の制約を守る

• 明示的に求められていない限り、同期 API を非同期に（またはその逆に）変換してはいけません。
• 動作が同等であることを検証できない限り、エラーの伝播方法を変更してはいけません。
• 運用上の意図を示すログ、テレメトリー、ガード、リトライを削除してはいけません。
• ドメイン固有の手順を、意図が見えにくくなる汎用ヘルパーにまとめてはいけません。

6) 検証する

--no-verify が設定されている場合はスキップします。それ以外の場合は、以下の「検証」セクションに従って検証します。

7) 報告する

以下の「報告」セクションに従って報告します。

簡素化のヒューリスティクス

• 認知負荷が軽減される場合は、ネストしたインライン式よりも、明示的なローカル変数を優先します。
• 簡潔でも曖昧な条件式より、条件ごとに明確な分岐を 1 つ設ける方法を優先します。
• 関数の長さは適切に保ちますが、行数だけを理由に分割してはいけません。
• 意図、不変条件、または一見して分かりにくい制約を説明するコメントは残します。
• 明白なコードの動作を言い換えるだけのコメントは削除します。
• 文字数の最小化ではなく、次の保守担当者が理解するまでの時間を短縮することを優先します。

アンチパターン

• 推測に基づくアーキテクチャの書き換えを行ってはいけません。
• 小規模な局所変更の簡素化に、フレームワーク全体に適用するパターンを持ち込んではいけません。
• 理解しやすい重複を、不透明なユーティリティ層に置き換えてはいけません。
• 無関係なクリーンアップを 1 つのパッチにまとめてはいけません。
• 起こり得ない状況に対するエラー処理を追加してはいけません。
• コード量を保つこと自体を目的にしてはいけません。より簡単で同等の方法がある場合はそれを採用するか、依頼を満たさない理由を説明します。

検証

変更した動作を検証できる、最も対象を絞ったチェックを実行します。

• 変更したファイルに対するフォーマッター／lint
• 変更したモジュールを対象とするテスト
• 必要に応じた型チェック
• 関連する excluded-scope の出力に対する不変条件チェック

リスクに見合う場合に限り、特に簡素化によって共有契約が変更される場合は、より広範なチェックを実行します。スキップしたチェックと、その理由をすべて明記します。

レポート

--no-report が設定されている場合は省略し、代わりに簡潔な作業メモを返します。変更範囲、主な簡素化、残存リスクを記載してください。

以下の見出しをこの順序で使用してください。該当しないセクションは省略し、番号を付けたり、空欄やプレースホルダーを残したりしないでください。

範囲

変更したファイルと領域、および検証方法を使用した excluded-scope の項目を記載します。

簡素化

意味のある変更ごとに、読みやすさまたは保守性の向上に焦点を当てた一文を記載します。動作を維持する前提を明示してください。

検証

実行したコマンドと結果を、省略したチェックも含めて記載します。

残存リスク

リスクごとに一行で記載します。形式は次のとおりです。<前提>を仮定しています。誤っていた場合は<発生する問題>。<コマンドまたは確認方法>で確認してください。 平易な言葉を使い、専門分野固有の用語は説明または言い換えてください。ユーザーの判断が必要な質問も直接的に記載します。該当するリスクがない場合は なし。 と記載してください。

中止条件

次の場合は作業を中止し、指示を求めてください。

• 簡素化のために公開 API や契約を変更する必要がある。
• 要件が不明確であったり、解釈の違いによって編集内容が大きく異なったりする。
• 動作の同等性を確信を持って検証できない。
• コードがドメイン上の制約により意図的に複雑になっているように見える。
• 要求された範囲が、簡素化ではなく大規模な再設計を必要とする。