sliced-bread-depth

Sliced Bread の深さ

各スライスを、実装の大部分を隠す小さく安定した公開サーフェスを持つ、深いモジュールとして評価します。スライスはすべての境界チェックに合格していても、その外皮自体が実装になっている場合があります。たとえば、実質的な処理がごく簡単なヘルパー関数2つだけなのに、外皮が900行もあるケースは、基準には適合していても浅いスライスです。詳しい根拠はSliced Bread リファレンスに記載されています。このスキルでは、その測定を行います。

対象範囲

デフォルトでは、リポジトリ内のすべてのスライスを対象にします。ユーザーがスライスを指定した場合は、それらのみを測定しますが、比率を把握できるよう、全体の一覧も表示します。ドキュメントに記載されている外皮の例外（スライスの継ぎ目となるシングルトンなど）も含めて分類します。例外の存在自体は問題として指摘しません。

ステップ 1 — 一覧の作成

各スライスの外皮を特定します。外皮とは、その言語におけるネイティブな形式の公開インターフェイスです。Go ではエクスポートされた識別子、Python ではパッケージの __init__ サーフェス、TypeScript ではインデックスモジュール、その他の言語では公開クラスのサーフェスにあたります。サーフェステストを適用します。利用者が内部を詳しく調べたり、何百ものシンボルがあるエントリーポイントに頼ったりせずに、外部から使用できる操作の小さく明快なセットを最上位で確認できるでしょうか。外皮の形状を分類します。

形状	特徴
薄いファサード	再エクスポート、ファクトリー、カタログ。独自のロジックはほとんど、またはまったくありません
フレームワーク依存	外皮がフレームワークの基底クラス（シーンノード、ビュー、コンポーネント）を継承する必要があります
サービス／シミュレーション	外皮がホットループまたは長時間実行プロセス（ステップ、ティック、ディスパッチ）を所有します

ステップ 2 — 測定

各スライスについて、推定ではなくコードを使って算出します。

• 外皮の LOC と スライス全体の LOC。重要な比率は 実装比率 です。外皮の LOC ÷ スライス全体の LOC で求めます。
• 内部モジュール数と LOC。外皮が隠している深いレイヤーを確認します。
• 公開サーフェス。外皮にある、エクスポート対象またはアンダースコアで始まらない関数、メソッド、イベント／シグナルのおおよその数。
• ライフタイムの混在。公開サーフェスに、無関係なライフタイム（初回のみのセットアップ、フレームごと／リクエストごとの処理、UI の配線など）が混在しているかどうか。

ステップ 3 — 評価

次の両方に該当する場合は、クラストを分解すること（内部実装を抽出すること。2つ目の公開シームは決して追加しないこと）を推奨します。

• (a) クラストファイルにホットパスの実装が含まれており、
• (b) 深層レイヤーが空または薄い（実装の大部分がクラスト側にある）、または公開サーフェスに関係のないライフタイムが混在している。

指標を公平に保つための調整：

• 指標は絶対的な LOC ではなく比率です。 純粋なファクトリーリーフスライスの 100％を占める 250 行のクラストは健全です。一方、スライスの実装量の 85％を抱える 900 行のクラストは問題です。
• フレームワークに依存するクラストには、凝集性を考慮した許容範囲があります。 フレームワークのコールバック（ライフサイクル、物理演算、レンダリング）はサブクラスに置く必要があります。抽出対象は、クラストが所有する通常のヘルパーオブジェクトであり、2つ目の公開シームではありません。
• 内部ファイルが多いこと自体は問題ではありません。 深層モジュールが 30 個ある広いクラストは、API のクラスタリングに問題があります。サーフェスをグループ化して絞り込むべきであり、深さの問題ではありません。そのスライスの分割は推奨しないでください。
• 文書化された意図を尊重してください。 ドキュメンテーション文字列やコメントでサーフェスが意図的なものだと明示されているクラストは、該当箇所を引用したうえで、問題として指摘するのではなく、控えめに否定してください。
• 二重シーム（稼働中のシングルトンと純粋なヘルパーファサード）の場合は、分割ではなく明確化を促してください。2つ目のクラストを作るのではなく、どちらのシームが何を担うのかを文書化するよう推奨してください。
• 兄弟同士を比較してください。 同じパターンを実装する 2 つのスライスで深さが正反対（片方はホットループを委譲し、もう片方はインライン化している）なら、最も確度の高い問題です。リポジトリ内にすでに目標とする形が存在します。

成長に関するガード — 深さを評価する際に抑制すべき誤検出：

• 利用者が 1 つしかいないことだけでは、抽象化が早すぎる証拠にはなりません。具体的な圧力が存在するかを評価してください。利用者が 2 ついることは通常の根拠ですが、必須条件ではありません。
• 1 ファイルのまま維持されている新しい単一ファイルの概念は適切です。問題として指摘しないでください。
• スライス間の循環依存を解消するために導入されたディスパッチャーは、イベントとサブスクライバーが 1 つずつでも、圧力が実証されています。
• 数値のしきい値は参考指標であり、評価可能な違反ではありません。実装の比率、公開サーフェスのサイズ、ライフタイムの混在を評価してください。
• ファイルの配置だけがプライバシーを実現する唯一の手段である言語では、内容を内部向けと示すサブディレクトリは、内部にファイルが 1 つだけでも、その可視性境界に対する圧力が実証されています。

判定

判定	意味
extract	2 つのヒューリスティック条件を満たしています。内部実装をクラストから切り離します
narrow	深さはあります。公開サーフェスをまとめて縮小します
watch	肥大化傾向はありますが、単一軸です。次の機能が追加された際に再確認します
healthy	深さは適切な場所にあります。対応は不要です
intent	文書化された設計による広さです。該当箇所を引用して控えめに否定します

出力

以下の 3 つのセクションを読み取り専用で報告してください。このスキルはコードを編集しません。

1. カタログ — スライス、形状、クラストの LOC、内部モジュール、実装比率、公開サーフェスをまとめた表を 1 つ。
2. 評価 — スライスごとの判定をまとめた表を 1 つ。extract → narrow → watch の順に並べ、それぞれに file:line を引用した 1 行の理由を付けます。
3. ROI の高い抽出案トップ 3 — 具体的に、クラストから何を取り出し、どこに配置するのか、存在する場合はリポジトリ内のどの先例を手本にするのかを示します。推測に基づく再構成より、既存の先例を活用した機械的に実施できる改善を優先してください。

すべてが healthy のカタログも有効な結果です。問題を捏造しないでください。