reduce-system-complexity

システムの複雑さを減らす

振る舞いを保ちます。仕組みを最小限にします。

具体的な振る舞いの経路またはサブシステムが選定され、意図する結果が仕組みの純減である場合にのみ、このスキルを使用してください。このスキルでは、保全台帳、経路全体の仕組みの算定、第一原理に基づく最小構成、振る舞いと仕組みそれぞれのゲートを扱います。

以下とは区別してください。

• improve-codebase-architecture：アーキテクチャへの投資を発見し、優先順位を付けます。
• codebase-design：選定されたモジュールの責務と、呼び出し元向けの完全な契約を設計します。
• structure-codebase：物理的な配置、パッケージ、インポート、適用、移行を扱います。
• refactoring：経路全体の削減を主張せず、範囲を限定して通常の振る舞いを維持するクリーンアップを実装します。
• functional のリデューサー関数、Redux リデューサー、状態管理の選択。

診断または実装レポートを作成する前に、references/ledger-template.md を読んでください。由来の説明や、この適用と上流のソースとの比較を行う場合は、references/source-notes.md を読んでください。

運用上の契約

• ユーザーが指定した範囲を守ってください。単一の経路をリポジトリ全体の書き換えに広げないでください。
• 診断は読み取り専用です。既定で書き込み可能なのはレポートのみで、実装には明示的な許可が必要です。
• リポジトリの指示、アーキテクチャ上の決定、用語集、公開契約、変更済みワークツリーに関する制約に従ってください。ユーザーまたはチームメイトの変更を破壊的にリセット、チェックアウト、上書きしないでください。
• 実装、テスト、トレース、履歴、インシデント、運用担当者の知識を証拠として扱ってください。現在の分解方法を目標として引き継がない一方、そこから判明した文書化されていない制約を無視しないでください。
• フィクスチャ、トレース、スナップショット、レポートから、シークレット、トークン、個人データ、本番環境のペイロードを削除してください。
• リスクに応じて台帳の規模を調整してください。ローカルフラグの削除に分散移行と同等の手順は不要ですが、データ、認可、並行性、互換性、外部作用に関わる変更では必要です。
• 有限個のテストと観測を保全の証拠と呼び、普遍的な等価性の証明とは呼ばないでください。確信度と忠実性に関するギャップを明示してください。
• プロバイダー、統合、移行、フェイルオーバー、ロールバック、公開、運用に関する確認は、既定で読み取り専用または使い捨てのサンドボックスで行ってください。その作用に対する具体的な許可なく、稼働中の外部システムに書き込まないでください。

ワークフロー

1. スコープ、モード、保全する契約を確定する

次を明示します。

• 選択されたエントリーポイント、成果、呼び出し元、データ、連携、および運用パス
• 診断モードか、承認された実装モードか
• このスコープにおいて「より少ないメカニズム」が意味するもの
• 除外される動作と境界
• 作業を制約する不可逆的な影響または公開された契約

保全を約束する前に、観測された動作を分類します。

分類	扱い
文書化された、または受け入れ済みの契約	ユーザーが動作変更を承認しない限り保全する
依存されている観測可能な動作	文書化されていなくても、互換性に敏感なものとして扱う
意図されており、現在サポートされている、または信頼できる証拠を伴って観測されている動作	保全し、必要に応じてそのオラクルを強化する。願望的な意図は動作変更であり、契約の解決と tdd に戻る
既知のバグまたは係争中の動作	プロダクト／ドメインの決定のために提示する。黙って保全したり修正したりしない
到達不能、廃止済み、または推測的な内部構造	到達可能性と利用者の証拠を確認した後にのみ削除候補とする

出力、影響、エラー、順序付け、永続化、連携、認可、セキュリティ、プライバシー、信頼性、リソース予算、互換性、並行性、リトライ、マイグレーション、リカバリ動作を洗い出します。それぞれを、その証拠とギャップとともに動作・保証台帳に記録します。

特性化テストはコードが何をするかを明らかにしますが、何をすべきかは決定しません。診断中は、編集せずに欠落しているオラクルを記録します。実装とテストハーネスの作業が別々に承認されている場合、現在の動作に使用可能なオラクルがないときに characterisation-tests と finding-seams をロードします。動作レベルのオラクル設計には testing をロードします。最終的な変更スコープを記録しますが、自動化された mutation-testing ハーネスは、削減スライスがそれ以外の点で PR の準備が整うまで延期します。

そのフェーズ終了時の PR 準備ゲートでは、ミューテーションテストは、到達不能であると証明されたすべてのパス、設定のみの変更、生成された境界、または運用メカニズムにとって意味があるわけではありません。代わりに、到達可能性、設定、契約、連携、または運用の証拠を添えて N/A とマークします。ワークフローを満たすために構造的なミュータントや偽の RED をでっち上げないでください。

提案されたスライスが影響しうる重要な動作に未解決の証拠ギャップがある限り、実装は診断のままです。

2. メカニズム全体をベースライン化する

保全する各動作を、トリガーから成果、そしてリカバリまで追跡します。適用可能なメカニズムの次元を、その後使用されるのと同じスコープと計数方法で洗い出します。

• 制御 — 決定、条件、順序付け、エラー、リトライ、フォールバック、リカバリのパス。サイクロマティック複雑度はローカルなシグナルの一つであり、システム横断的な合計ではありません。
• 状態と時間 — 状態、遷移、可変の所有者、キャッシュ、キュー、タスク、コールバック、ロック、同期ポイント、ライフサイクルフェーズ。
• 構造 — モジュール、表現、レイヤー、ホップ、内部および外部の依存関係、循環、アダプター、変換。
• 可変性と運用 — フラグ、モード、設定、拡張ポイント、デプロイ可能なもの、ジョブ、マイグレーション、モニター、ランブック、障害処理。

テストと運用の仕組みが継続的な所有コストを課す場合は、それらも含めます。ソース、ビルド、またはランタイムのメカニズムが変わらない限り、生成された成果物は除外します。無関係な次元は N/A とマークします。

混在するランタイムの場合、エントリーポイントで削除されたラッパーだけを数えるのではなく、前後のインベントリに利用者と実装にまたがるランタイムエントリと変換を含めます。そのパスが Effect を使用する場合は、Effect ランタイムリファレンスを参照してください。

異なる種類のカウントを合成スコアにまとめないでください。関数、ディレクトリ、または差分が小さくなっても、呼び出し元、オペレーター、依存関係、またはリカバリパスが削除された負担を引き継ぐ場合、それは削減ではありません。

3. 制約から最小構成を導き出す

現在の構成に依存せず、次の問いに答えてください。

1. どのような成果と非機能保証が必要ですか？
2. どのドメイン上の判断と外部制約が不可欠ですか？
3. どの境界が固定されており、状態、時間、障害、復旧は誰が担う必要がありますか？
4. トリガーから観測可能な成果までの、最短で一貫した経路は何ですか？

最小限の実現可能な仕組みを描き、残す要素すべてについて、その根拠となる制約を明示してください。効果の高い順に、次のことを検討してください。

1. 廃止済みと証明された経路、オプション、フラグ、設定、フォールバック、推測的な仕組みを削除します。
2. 重複するポリシー、表現、状態、所有権を統合します。
3. 判断の選択肢と状態の空間を縮小します。
4. 中継レイヤー、変換チェーン、時間的な中継、調整を取り除きます。
5. ライフサイクル全体と運用コストが下がる場合に限り、独自の仕組みを確立されたプリミティブに置き換えます。重要な依存関係やツールの選定には、evaluate-existing-solutions を使用してください。

複雑さを単に改名、分割、ラップ、移動、隠蔽するだけの提案は却下してください。より深いモジュールによって呼び出し側が改善されても、内部の仕組みが維持または増加することはあります。それは妥当な codebase-design の成果ですが、それだけでは削減に成功したとはいえません。

4. 完全な削減案を選ぶ

候補を定性的に順位付けします。

1. 一部を隠すよりも、仕組み全体を取り除くことを優先します。
2. 保全を裏付ける証拠がより強く、忠実性の欠落がより少ない案を優先します。
3. 判断が同等の場合は、影響範囲が小さく、復旧が容易な案を優先します。

選択した候補について、次の事項を記録します。

• 対象となる正確な仕組みと、維持する動作。
• 該当する各側面についての、客観的な変更前の観測結果と目標値。
• 影響を受ける呼び出し元、データ、連携、運用、公開契約。
• 不足しているオラクルと、その他の証明義務。
• ロールアウト、可観測性、互換性、データ移行、復旧に関する要件。
• 古い仕組みがなくなった最終状態。
• 複数スライスからなるプログラムの場合は、計画／台帳の識別情報、最終スライス、および各スライスの分類（削減への移行または最終削減）。

小さく、元に戻せるスライスを優先してください。元に戻すことが不可能または安全でない場合は、実装前に、保護策を設けた前進復旧の経路を定義します。拡張／縮小型の移行では、一時的にブリッジ、フラグ、二重書き込み、互換性シムを追加する場合があります。それぞれに担当者、削除条件、期限を設定してください。移行によって一時的なブリッジが導入されない場合は、N/A と記録します。旧来の仕組みが最終状態でなくなるまでは、削減を達成したと主張しないでください。

診断はここで終了し、レポートを作成します。複数のデリバリースライスが必要な場合は、完全な削減案とゲートを定義した後に planning を使用してください。

5. REFACTOR パスで削減する

実装は、許可を得てから続行してください。

編集前に、許可されたスライスを分類してください。

• 削減移行 — 保存対象の契約を維持しながら、一時的にメカニズムを残したり追加したりする場合がある、独立して検証可能なプログラムの増分です。計画／台帳と最終スライスを参照し、ブリッジがある場合は所有者／削除／存続期間の上限に関するメタデータを記録します（ブリッジがない場合は N/A）。また、mechanism gate: pending — no net-reduction claim を維持します。
• 最終削減 —置き換えられたメカニズムと期限切れのブリッジを削除するスライスです。プログラム／台帳を参照し、以前の移行で生じた義務を履行するか、N/A — authorized single terminal slice と記録します。両方のゲートを通過した後に限り、純削減を主張できます。

プログラム全体が未完了でも、移行は安全にマージできる増分になり得ます。移行自体のメカニズムゲートが保留中というだけで、完了した削減として記述したり、削減台帳を失わせたりしないでください。

振る舞いを維持する削減は、合格済みの振る舞いオラクルに加え、影響範囲に応じた到達可能性、構成、契約、統合、運用の証拠を起点とします。これは REFACTOR パスであり、分岐、レイヤー、状態、依存関係の数を主張する失敗テストを捏造する理由にはなりません。スライスがそれ以外の点で PR の準備が整ったら、該当する場合は、蓄積された結果に対してミューテーションチェックを実施してください。望ましい結果によって観測可能な振る舞いが変わる場合や、議論のあるバグを修正する場合は、このワークフローを中止し、意図する契約を確定してから、振る舞いの変更には tdd を使用してください。

安全な各スライスについて、次の手順を実施してください。

1. スライス適用前の状態を記録し、影響を受ける振る舞い、型、ビルド、統合、運用のチェックを実行します。
2. 編集前に、データベース、キュー、デプロイ、メッセージ、認可、並行処理、およびその他の不可逆な影響を特定します。
3. 完全な削減に向けて進める、最小限で一貫性のある変更を行います。
4. 振る舞いを対象とするテストを維持します。実装形状に依存するテストを削除するのは、同等の振る舞いカバレッジを確保してからにしてください。PR の前に、フェーズ終了時のミューテーションまたは代替証拠のゲートで、テストスイートの累積結果を検証します。
5. まず対象を絞ったチェックをただちに実行し、その後、関連する広範なテストスイートと、モックでは忠実性を確認できない場合のプロバイダ／契約チェックを実行します。明示的な権限が正確な本番環境での影響を対象としていない限り、プロバイダチェックは読み取り専用またはサンドボックス内で実施します。明示されていない権限を根拠に、本番環境でのマイグレーション、フェイルオーバー、ロールバック、公開、外部への書き込みを決して行わないでください。
6. 置き換えられたコード、依存関係、フラグ、状態、構成、破棄する内部実装のテスト、および削除条件を満たした一時的なブリッジを削除します。
7. 呼び出し元、運用、障害、復旧を含め、経路全体を読み直します。

証拠が不合格になった場合、または影響を受ける新たな振る舞いが見つかった場合は、中止してください。無関係な作業を損なうことなく、このスライスが所有する編集と影響のみを復旧してください。変更後の振る舞いを変更前のベースラインとして使用してはいけません。

6. クラス固有のゲートを適用する

動作ゲート

• 影響を受ける台帳項目すべてについて、要求される忠実度で保全の証拠が合格しています。
• 結果、効果、エラー、順序、境界、非機能要件が、合意済みの契約の範囲内に収まっています。
• 削除された判断、状態、依存関係、またはフォールバックごとに示唆される境界ケースについて、到達可能で有意義なものを検証しています。そうでない場合は、その主張を裏付ける到達可能性、設定、契約、統合、または運用上の明示的な証拠があります。
• 残る不確実性と、未検証のプロバイダーの動作が明示されています。

仕組みゲート

• 同じ範囲と方法で、同じ次元を再集計しています。
• 新たに導入された各部分を、置き換える以前の仕組み、または満たす必須制約に対応付けています。
• 呼び出し元、アダプター、運用、デプロイ、復旧について、外部に転嫁された負担がないか確認しています。
• 置き換えられた仕組みと期限切れの移行ブリッジが取り除かれていることを確認しています。
• ライフサイクル全体の所有負担が減ったことを確認しています。差し引きがゼロ、または負担を単に移しただけの最終結果は不合格です。移行段階のみの結果では、このゲートは保留のままであり、マージ可能なスライスではなくプログラムが未完了であることを意味します。

削減移行では、動作ゲートと独立したスライス検証に合格する必要があります。一方、仕組みゲートは明示的に保留のままとし、純削減を主張してはなりません。最終削減では、実現した削減を主張する前に、両方のゲートに合格する必要があります。

レポート

references/ledger-template.md を使用して、新しい Markdown レポートを作成してください。診断によってリポジトリが汚れないよう、特に指定がない場合は OS の一時ディレクトリにタイムスタンプ付きのファイルを作成してください。プロジェクトの永続パスを使用するのは、指定された場合、またはプロジェクトで既に確立されている場合に限ります。

診断では、削減案、目標差分、証拠の不足、リスク、次の判断を報告してください。同等性も、実現した削減も主張してはなりません。

PR 準備済みの削減移行では、保持された契約と、プログラム／最終スライスの関連付けを先頭に示してください。behavior gate: pass、独立した検証、フェーズ終了時に行った単一の変更結果または代替証拠としての明示的な N/A、ブリッジの所有・削除に関するメタデータ（該当なしの場合は N/A）、および mechanism gate: pending — no net-reduction claim を示してください。

最終削減では、プログラム／台帳へのリンク（または N/A — authorized single terminal slice）、保持された契約、削除した仕組みを先頭に示してください。条件を揃えた変更前後の証拠を示し、実施した検証をすべて列挙し、以前の移行義務と期限切れのブリッジがすべて解消されたことを確認し、残る忠実度の不足や必須の複雑さを開示してください。

完了チェック

• このワークフローの開始前に、具体的なシステムまたは動作経路を選定しましたか？
• 文書化された動作、依拠されている動作、意図された動作、異議のある動作、廃止された動作を区別しましたか？
• 影響を受けるすべての保証について、相応の保全の証拠があるか、明示的なブロッキング上の不足がありますか？
• ベースラインには、編集したファイルだけでなく、呼び出し元と運用上の仕組みも含まれていますか？
• 最小構成は流行の形ではなく、実際の制約から導き出されていますか？
• 最終状態では、仕組みを移動または隠すのではなく、取り除いていますか？
• すべての実装成果物が削減移行または最終削減に分類され、プログラムと最終スライスが関連付けられていますか？
• 一時的な移行の仕組みは、所有者と期限が定められ、削除予定があるか、存在しない場合は明示的に N/A とされていますか？
• 動作ゲートと仕組みゲートを別々に評価しましたか？
• 移行段階では仕組みゲートを保留のままとして純削減を主張せず、最終削減の場合にのみ両方のゲートに合格したと主張していますか？
• 主張の強さは証拠に見合っていますか？

帰属表示

Adam Bulmer の MIT ライセンスの reducer スキルをベースにしています。ローカル版では、トリガーの範囲を絞って名前を変更し、誤った精度を伴う順位付けを定性的なエビデンスに置き換え、関連するテストスキルとアーキテクチャスキルを統合し、実装、移行、プライバシー、変更の残ったワークツリーに関する安全策を追加しています。固定された来歴とライセンス条項については、references/source-notes.md と LICENSE を参照してください。