reducing-entropy

reducing-entropy スキルの概要

reducing-entropy スキルは、コードベースを意図的に小さくしていくための、手動専用のリファクタリング支援です。汎用的なクリーンアップ用プロンプトではなく、自動で発火させる前提のものでもありません。使うべきなのは、「整理すること」自体が目的ではなく、可動部分を減らし、総コード量を削り、通常のリファクタよりも強く“削除寄り”の判断をしたいときです。

reducing-entropy が向いている人

reducing-entropy が特にフィットするのは、次のようなケースです。

• 成熟しているのに増え続けるコードをリファクタしている
• 「cleanup」の名目で、実は抽象化が増えそうな計画をレビューしている
• そもそもその機能・レイヤー・ヘルパーが必要なのかを見極めたい
• アーキテクチャを“並べ替える”のではなく、本気で単純化したい

特に reducing-entropy for Refactoring との相性は高く、こうした場面では既存構造を取り除くべきなのに、逆に新しい構造を足してしまうのが典型的な失敗だからです。

このスキルが本当に解くべき仕事

このスキルが答えようとするのは、「何を変更すべきか？」より一段難しい問いです。問うのは次の点です。

• 変更後、コードベースはどんな姿になっているべきか
• その最終状態は、本当に今より小さくなっているか
• 残すのではなく、何を消せるか

そのため、単に「このコードを簡潔にして」と頼む汎用プロンプトよりも、純減を強く狙いたい場面で役に立ちます。

reducing-entropy が他と違う理由

最大の違いは、成功指標が「実装の手間」ではなく「最終的なコード量」であることです。

そのため、次のような結果を優先します。

• 小さな移行コードを書いて、大きなサブシステムを撤去する
• 独自型を、もっと単純なデータ構造に置き換える
• オプション挙動を一般化する代わりに削除する
• 見た目は“きれい”でも総コード量が増える設計は却下する

導入前に知っておくべき重要な制約

これは、あらゆる作業で安全に使えるデフォルトではありません。リポジトリでも reducing-entropy は明示的に manual-only とされており、ユーザーのはっきりした意図があるときに使う前提です。もしチームが、そのタスクではコード削減よりも拡張性・将来への備え・インターフェースの安定性を重視するなら、このスキルは削除方向に寄りすぎる可能性があります。

使うか決める前に読むべきファイル

まずは次のファイルを読んでください。

• skills/reducing-entropy/SKILL.md
• skills/reducing-entropy/README.md
• skills/reducing-entropy/references/simplicity-vs-easy.md

その上で、状況に応じて追加で 1〜2 個、参照用のマインドセットを読むのがおすすめです。

• references/data-over-abstractions.md
• references/design-is-taking-apart.md
• references/expensive-to-add-later.md

これらの参照ファイルが重要なのは、このスキルが「実行前に少なくとも 1 つの単純化の視点に立って判断する」ことを前提にしているからです。

reducing-entropy スキルの使い方

reducing-entropy のインストールとセットアップ

このリポジトリの Skills CLI パターンを使う場合は、次のコマンドでインストールします。

npx skills add softaworks/agent-toolkit --skill reducing-entropy

インストール後は、まずスキルのフォルダを開いて SKILL.md を読んでください。これは入れてすぐ動く自動化スキルではなく、意図を持って呼び出す判断フレームワークです。

まず必須の reference mindset から始める

見落とされがちな実務上のポイントとして、reducing-entropy は開始前に references/ 内のファイルを最低 1 つ読み込むよう求めています。ここは先にやり、どのファイルを使うかも明示してください。

相性のよい組み合わせは次の通りです。

• 慣れたパターンに引っ張られがちだが重いときは simplicity-vs-easy.md
• コード全体に wrapper、manager、独自型が多いときは data-over-abstractions.md
• 責務が絡み合っているときは design-is-taking-apart.md
• 削除判断が将来の後付けコストと衝突しそうなときは expensive-to-add-later.md

この手順で出力品質が上がるのは、「きれいにして」という曖昧な目標ではなく、具体的な単純化のレンズをモデルに渡せるからです。

reducing-entropy に必要な入力

有用な出力を得るには、repo のリンクやファイル一式を投げるだけでは足りません。reducing-entropy が最も機能するのは、次の情報を与えたときです。

• ユーザー承認済みのゴール
• 維持しなければならない現在の挙動
• 対象範囲となるコードベースの部分
• API、移行、期限に関する制約
• ファイル・モジュール・機能をまたいだ削除が許されるかどうか

よい入力例:

“Use reducing-entropy on our billing retry flow. Goal: preserve current retry behavior for Stripe failures, but reduce total code in services/billing/ and workers/retry/. You may remove dead configuration paths and duplicate helper layers. Do not change public API responses or database schema this week.”

これは、次のような依頼よりはるかに有効です。

“Refactor billing to be simpler.”

粗い要件を強い reducing-entropy プロンプトに変える

よい reducing-entropy usage プロンプトには、通常 5 つの要素があります。

1. 明示的な起動指定
2. 対象スコープ
3. 保護すべき挙動
4. 削除の許可範囲
5. 出力形式

例:

“Apply the reducing-entropy skill. Load one reference mindset first and tell me which one you chose. Analyze src/cache/ and src/session/ for the smallest codebase that still supports current login/session behavior. Prefer deletion over reorganization. Reject options that increase total code even if they look cleaner. Give me:

• the smallest end-state design
• what to delete
• what to merge
• risks
• rough before/after code footprint”

実際のリファクタリングでのおすすめ reducing-entropy ワークフロー

安定して使いやすい流れは次の通りです。

1. SKILL.md を読む
2. 参照マインドセットを 1 つ選ぶ
3. 現在のモジュール境界を確認する
4. 残すべき挙動を列挙する
5. スキルの 3 つの中核質問を投げる
6. 2〜3 個の候補となる最終状態を作る
7. 正味のコード削減量で比較する
8. 最小で成立する案を実装する
9. 残った抽象化や不要経路がないか再確認する

これでよくある失敗、つまり「生き残る最小設計を決める前に編集へ飛び込む」ことを防げます。

毎回必ず入れたい 3 つの質問

このリポジトリでは、スキルの中心に 3 つのチェックがあります。実際には、プロンプトに明示しておくのが有効です。

• What is the smallest codebase that solves this?
• Does the change result in less total code?
• What can we delete?

この 3 問を強制しないと、出力は普通のリファクタリング助言に戻りがちです。

reducing-entropy が最も効く場面

特に相性がよいのは、次のようなタスクです。

• 重複したモジュールを 1 つの単純な経路にまとめる
• wrapper、factory、manager、薄い抽象化を取り除く
• 独自構造を plain data と関数に置き換える
• あまり使われていない機能や設定可能性を削る
• 新規開発の前に、もつれたサブシステムを簡素化する

この意味で reducing-entropy for Refactoring は最適解に近く、局所的なコードスタイル調整よりも、最終状態の再設計に重心があるからです。

reducing-entropy を使わないほうがよいケース

次の仕事が主目的なら、このスキルは避けたほうがよいです。

• 将来要件がまだ不確かな新機能追加
• サードパーティ向けに安定した拡張面を維持すること
• 後からの改修コストが高い基盤設計
• 削除や挙動統合の許可なしに、読みやすさだけを上げたい場合

こうしたケースでは、削除バイアスは強みではなくミスマッチになりやすいです。

リポジトリ内で最初に読むとよい実用ファイル

最短で理解したいなら、次の順で読むのが効率的です。

1. SKILL.md
2. README.md
3. references/simplicity-vs-easy.md
4. references/design-is-taking-apart.md
5. references/data-over-abstractions.md

adding-reference-mindsets.md は、作者たちが参照用の思想ファイルをどう位置づけているかまで知りたい場合にだけ読めば十分です。

出力品質を目に見えて上げるコツ

特に差が出るのは、次の 3 つです。

• コード変更を求める前に、「最小の最終状態アーキテクチャ」を先に出させる
• 単なる簡略化ではなく、明示的な削除を必須にする
• 何が消えるかを見積もらせる: files、functions、classes、branches、configs

これにより、このスキルは単なるスタイル改善の後押しではなく、実際の削減作業として機能します。

reducing-entropy スキル FAQ

reducing-entropy は普通の refactor プロンプトより優れていますか？

目的が「正味での単純化」なら、多くの場合は yes です。汎用プロンプトは、よりきれいなレイヤー分け、命名改善、再利用しやすい抽象化を提案しがちです。そうした動きでコードベースがむしろ膨らむなら、それに抗ってくれる点で reducing-entropy のほうが向いています。

reducing-entropy は初心者でも使えますか？

はい。ただし、現行システムを十分理解していて、「何を守るべきか」と「どこまでが対象か」を言語化できることが前提です。フレームワーク自体はシンプルですが、よい結果を出すには、何を安全に取り除けるかを把握している必要があります。

reducing-entropy はコード削除だけを意味しますか？

いいえ。全体として大きな削除につながるなら、多少コードを書くこと自体は正当化されます。判断基準は最終状態です。小さな追加で、より大きな構造を置き換えられるなら問題ありません。

reducing-entropy は greenfield 開発にも使えますか？

通常、主ガイドとしてはあまり向きません。ゼロから設計するより、既存コードベースを刈り込む・単純化するほうで強みが出ます。

reducing-entropy は通常の cleanup 作業と何が違いますか？

通常の cleanup は、局所的な読みやすさや整理を最適化することが多いです。reducing-entropy skill が最適化するのは、概念の数、構造の数、総コード量を減らすことです。両者は重なる部分もありますが、同じものではありません。

インストール前に知っておくべき主なリスクは何ですか？

大きなリスクは次の通りです。

• 実際には必要な柔軟性まで削ってしまう
• 将来要件を見越した備えを単純化しすぎる
• 行数だけで機械的に良し悪しを判断してしまう
• 実運用上の理由で存在する構造まで取り除いてしまう

だからこそ expensive-to-add-later.md が重要です。純粋な削除バイアスに対する、筋の通った例外条件を与えてくれます。

reducing-entropy はどんなリポジトリにも合いますか？

いいえ。コードが増え続けること自体が課題になっている環境で最もフィットします。明示的な構造そのものが製品要件になりやすい、強い規制下のシステム、公開プラットフォーム、高い拡張性が求められる環境では相性が落ちます。

reducing-entropy スキルを改善する方法

reducing-entropy の境界条件をもっと明確にする

reducing-entropy usage を改善する最速の方法は、「何を変えてはいけないか」をはっきり定義することです。ここが曖昧だと、価値ある挙動まで削除する提案が出やすくなります。

有効な境界条件の例:

• “Preserve API shape.”
• “No schema changes.”
• “Keep test coverage expectations.”
• “User-visible behavior must stay identical.”

境界が明確なら、攻めた削減も安全に進めやすくなります。

単一案ではなく、最終状態の比較を求める

1 つの推奨案だけを求めるのではなく、2〜3 個の候補となる最終状態を、次の軸で順位づけしてもらうのがおすすめです。

• total code reduction
• migration cost
• risk of breaking behavior
• maintenance burden

これでトレードオフが見え、「最小ではあるが今は危険すぎる」案を見分けやすくなります。

エントロピーの高さが見えるコードベースの兆候を渡す

次のような“膨らみのサイン”を示すと、このスキルはよりよく働きます。

• モジュール間で重複しているロジック
• 挙動の少ない wrapper class
• 使われていないモード向けの config 分岐
• 呼び出しを転送するだけの helper layer
• plain data で足りるのに独自型を使っている箇所

こうした手がかりがあると、表面的な整形ではなく、本当に削れるポイントを狙いやすくなります。

よくある失敗パターンを見張る

ありがちな悪い出力は次の通りです。

• コードをより多くのファイルへ再配置する
• 「将来の成長に備えて」抽象化を追加する
• 死んだ互換経路を温存する
• 構造を減らさず名前だけをきれいにする
• 「変更量が少ないこと」を目標にしてしまう

こうした兆候が出たら、評価指標を言い直してください。重視すべきは、最終コードベースの総コード量が減ることです。

reference ファイルを戦略的に使う

結果を良くするには、課題に合ったマインドセットを選ぶことが重要です。

• class-heavy な設計を疑うなら data-over-abstractions.md
• 責務の混在をほどきたいなら design-is-taking-apart.md
• 定番解が重すぎるときは simplicity-vs-easy.md
• 残す価値がある少数の要素を守りたいなら expensive-to-add-later.md

ここはこのリポジトリの強みのひとつで、受け身で眺めるのではなく、明示的に使う価値があります。

カテゴリ別に削除候補を出させる

歩留まりの高いプロンプトの型として、次が使えます。

“List deletion candidates by category: feature, abstraction, config, compatibility path, helper, type, and file.”

この形にすると、局所的なコード編集だけでなく、より広い削減機会まで探させやすくなります。

最初の出力後にもう一段掘る

1 回目の結果のあと、次のような追質問をすると効果的です。

• “What remains that exists only to support the old design?”
• “Which abstractions are now redundant?”
• “What can be merged further without changing behavior?”
• “What would you remove if you had to cut this module by 30%?”

こうした 2 ラウンド目の問いで、本当に大きい削減余地が見えてくることがよくあります。

行数だけでなく、正味の複雑さで検証する

この文脈では行数は重要ですが、それだけで判断してはいけません。よい改善は、次の点も一緒に減らします。

• 学ぶべき概念の数
• 挙動を追うための module hops
• special cases
• branching paths
• dependency surface

小さくなっても、まだ絡み合っているコードベースなら勝利は半分です。最善の reducing-entropy guide 活用は、削除と疎結合化をセットで進めることです。