simplifying-code

コードの簡素化

作業ルール

• 動作、インターフェース、副作用、ドメイン上の意図を維持します。未リリースの形状に対する例外を設ける場合は、スコープ外に利用者がいないことを証明します。
• 外部の危険要因に対するガードを削除する前に、その前提条件を再現し、危険が処理されることを示します。そうでなければ、ガードを維持します。
• 標準ライブラリへの置き換えは、空、null、該当なし、順序、ゼロ値の各ケースで検証します。
• 分析のみの依頼では、対象を特定し、コードを編集せずに簡素化案を報告します。

原則

原則	ルール
動作を維持する	出力は入力が行ったことをそのまま実行し、機能を黙って追加したり削除したりしてはなりません。特に、非同期／同期の境界（同期を非同期に変更したり、その逆にしたりしない）、エラー伝播の経路（方針を変更しない）、運用上の意図を表すログ記録／テレメトリー／ガード／再試行、ドメイン固有の手順（意図を隠す汎用ヘルパーにまとめない）を維持します。例外は1つあります。現在の未リリースのスコープにおける以前の反復にのみ存在した形状は、保護対象の動作ではありません。解決対象のスコープ外に、デプロイ済み、永続化済み、公開済み、外部、依存ブランチ、またはリポジトリ内の呼び出し元がないこと、また必要な呼び出し元の更新がすべて編集範囲内で完結することを確認してください。そうでなければ、互換性経路を維持します。この限定的な免除は、利用者が存在しないと証明できる形状に関するものであり、ガードの削除を許可するものではありません。ガードの削除には「AI Slop の除去」で定める証拠基準が適用されます
巧妙さより明示性	ネストした式より、明示的な変数を優先します。簡潔さより読みやすさを優先します
整然さより単純さ	パターンに頼りすぎた「クリーン」なコードより、率直なコードを優先します。早まった抽象化をするより、似た3行をそのままにします
外科的な変更	簡素化が必要な箇所だけに手を加えます。周囲のコードにあるスタイル、命名規則、書式に合わせます
前提を明らかにする	ブロックを変更する前に、そのブロックをインポートするもの、そのブロックがインポートするもの、対象をカバーするテストを確認します。依存先も同じ作業で編集します
簡素化より削除を優先する	最適化より簡素化を、簡素化より削除を優先します。変更点が見つからない作業も、妥当で完了した結果です

インターフェース、エクスポート名、永続化形式、またはパスを変更すると、インポートグラフの範囲を超えます。古い識別子を持つ生成元、利用側、スキーマ、フィクスチャー、ジェネレーター、マニフェスト、スクリプトと CI のレシピ、設定の参照、ドキュメントをすべて列挙し、同じ作業で移行します。最後に古い識別子を検索し、該当がゼロであることを確認するか、意図的に残した各箇所の理由を1行ずつ記述します。インポートグラフに含まれないため、古いキーを保持するフィクスチャーや .env.example のエントリーで、名前変更は放置されがちです。識別子が公開 API またはエクスポートされた API の場合は、まず「停止条件」を適用します。ユーザーに確認してから列挙してください。依頼なしで検索範囲を広げるのは、内部識別子に限ります。

プロセス

1. 最初に読む：変更を加える前に、ファイル全体と依存先を把握します。チェスタトンの柵の原則を適用します。コードが不要に見えても、その理由が不明な場合は削除する前に git blame を確認します。まず理由を理解し、その理由が今も当てはまるかどうかを判断します。
2. 不変条件を特定する：何を維持する必要があるかを確認します。公開 API、戻り値の型、副作用、エラーの挙動などです。編集前に、編集前の正確な状態を再現する使い捨てのワークツリーで、関連する観測可能な出力を記録します。変更前の参照がその状態と一致する場合に限り、変更前の参照で代用できます。作業ツリーを stash せず、既存の未コミットの編集をベースラインのコピーに保持します。
3. 対象を特定する：効果の大きい簡素化の機会を見つけます。効果とは、可読性と保守性を指します。優先順位は、制御フロー → 命名 → 重複 → データ整形 → 型です（「問題点 → 修正」表を参照）。
4. 順番に適用する：制御フロー → 命名 → 重複 → データ整形 → 型の順に進めます。構造的な変更を先に行い、見た目の変更は最後にします。分析のみの依頼では、変更を適用せず、提案する変更を説明します。
5. 検証する：変更を適用した場合は、関連するテスト、型チェック、インポートチェックで動作の同等性を確認します。同一の入力を使用して、レスポンス、CLI 出力と終了ステータス、またはジョブの成果物を変更前の記録と比較します。ドキュメント化された非決定的なフィールドのみを、両方で一貫して正規化します。説明のつかない差異はリグレッションとして扱います。テストがない場合は直接比較を行い、観測されていない動作を明記します。分析のみのレポートでは、必要なチェックと利用可能な証拠を特定し、提案した変更が検証に合格したとは述べません。
6. 提出前のスコープ監査：変更した行をすべて確認し、「この行は依頼されたタスクで明示的に必要とされているか？」と問いかけます。必要でない場合は元に戻し、Residual Risks のフォローアップ項目として記載します。スコープが曖昧な依頼（「プロジェクトを簡素化して」など）の変更前補完については、ia-verification-before-completion の Scope Confirmation ゲートを参照してください。

停止条件

次の場合は、続行する前に停止して確認します。

• 簡素化のために公開 API（関数シグネチャ、戻り値の型、エクスポート）の変更が必要な場合
• テストまたはベースラインとの直接比較で動作の同等性を検証できない場合
• パフォーマンスが重要、またはプロトコル準拠といったドメイン上の理由で、コードが意図的に複雑になっている場合
• スコープが簡素化ではなく再設計を意味する場合

制約

• 要求された内容のみを簡素化してください。機能の追加、スコープの拡大、新しい依存関係の導入、または要求されていない設定可能性や柔軟性の憶測による追加は行わないでください。
• 変更しないコードには手を加えないでください。簡素化していない行にコメント、ドキュメント文字列、型注釈を追加しないでください。
• 関連のない整理を1つのパッチにまとめないでください。各簡素化は、まとまりがありレビュー可能な単位にしてください。
• 小さなローカル変更を簡素化する際に、フレームワーク全体に適用するパターンを導入しないでください。
• 理解しやすい重複を、不透明なユーティリティ層に置き換えないでください。時期尚早な抽象化よりも、似た3行をそのまま残すほうが適切です。
• 意図、不変条件、または自明でない制約を説明するコメントと、ツール指示（例外事項）は残してください。明らかなコードの挙動を言い換えているだけのコメントは削除してください。古くなったコメントを修正するのは、このパスで変更する行に限ってください。
• 簡素化によってコードが理解しにくくなる場合は、変更を見送ってください。
• 過度な簡素化に注意してください。インライン化しすぎると、概念を示す名前が失われます。無関係なロジックを1つの関数にまとめると、別々の責務が隠れます。テスト容易性のためにある抽象化を削除すると、テストスイートが壊れる可能性があります。
• 使用されていないように見えるコードを削除する前に、テスト、フィクスチャ、設定、テンプレート、文字列キーや動的な呼び出し元も含め、ツリー全体を検索してください。該当するディスパッチ機構を検索で検出できない場合は、ヒットがないことを根拠に削除せず、コードを残して確認を求めてください。
• 自己完結性に価値がある成果物（プロンプト、スキルやエージェントの指示、サービスごとの設定、ベンダー提供のポリシーファイル）では、編集内容に実際のずれが生じるまでは、共有依存関係を作るより重複させるほうが低コストです。連携した変更が繰り返し同期しなくなった場合、または共有形式を使う実際の利用者ができた場合にのみ、抽出してください。

検証

分析のみのレポートでは、確認できた根拠と、実装後に必要なチェックを区別してください。コード変更後は次のチェックを行ってください。

• テストが成功し、型チェックが通ること
• 動作に変更がないこと（同じ入力から同じ出力が得られること）
• スコープが要求されたファイルに限定されていること。ついでの整理は行わないこと
• テストの範囲は、手順1（前提の把握）で確認したインポーター数に合わせてください。外部インポーターがない場合は、変更したパスを対象とするテストを実行します。外部インポーターが1つ以上ある場合、または共有コード／ユーティリティコードを編集した場合は、各インポーターを対象とするテストを実行します。テストランナーにパスを指定する機能がない場合は、全テストスイートを実行してください。

出力

分析のみを行う依頼では、各対象について場所、変更案、理由、動作上のリスク、必要な検証を報告してください。変更案が未実装であることを明記してください。

簡素化を適用した後は、次の内容を報告してください。

• 変更した範囲：変更したファイルと関数
• 主な簡素化：変更内容と理由（各1行）
• 検証：テスト成功、型チェック通過、動作に変更なし
• 残存リスク：置いた前提、対応していないものの注意が必要な領域

タスク固有の参考資料

実装またはレビューする挙動に応じて、関連する参考資料を確認してください。

• 問題の特定、AI 生成による不要な記述の削除、ガードや回避策の除去については、simplification-patterns.md を参照してください。
• 共有された解決済みスコープに対して他のスキルと連携する場合は、orchestrated-simplification.md を参照してください。