goal-sloc

goal-sloc — SLOCを北極星として、誠実に

SLOCは目標ではなく、代理指標です。 目標は、よりシンプルで、より優れた設計で、なおかつ正しく動作するシステムです。SLOCが役立つのは、無駄な部分や偶発的な複雑さを見つけ、実質的な判断を下すよう促すからです。一方で、簡単にごまかせるうえ、SLOCを動かす手軽な方法（コメントの削除、行の詰め込みや書式変更、ヘルパーの切り出し）では、システムが改善しないことも多いため、危険でもあります。削除する行の一つひとつについて、*「システムは以前と同等以上に良くなり、今も動作する」*と主張し、その根拠を示さなければなりません。

譲れない点は二つです。創意工夫（本質的な構造改善を見つけること）と、誠実さ（システムを犠牲にして代理指標を最適化しないこと。厳しい現実を隠さず、明らかにすること）です。

自己監査（最重要ルール）

最大の失敗パターンは、放っておくと、手軽な方法で指標を最適化し、それを進歩と呼んでしまうことです。 自分自身の衝動に歯止めをかけてください。

• マイルストーンをいくつか進めるごとに、削減分を分類してください。構造的な作業による割合（不要・仮置きのコードの削除、移動、重複排除、再設計）と、手軽な手段による割合（コメントの削減、書式変更、空白の削除、ヘルパーの切り出し）です。
• 手軽な手段が大半を占めるなら、自分をごまかしています。立ち止まって構造的な改善に取り組んでください。 あるいは、構造的な改善の余地が尽きたと報告してください（それ自体が誠実な結論です）。
• この内訳をマイルストーン報告に記載し、人に報告してください。相手が自分で気づくのを待ってはいけません。

---

0. 事前確認 — 削除する前に必ず実施

事前確認を省略すると、信頼できない「簡素化」が発生する最大の原因になります。コピーして使える references/preflight-checklist.md に取り組み、各項目に回答するまで削除を始めないでください。

0a — 目標を固定し、指標を理解します。

• 現在の目標を確認します。目標値はいくつで、どのツール／コマンドで正確に測定するのか、また基準値に変更はないかを確認してください。SLOC の目標は設定ファイルではなく、周囲の状況に応じて変わることがよくあります。人間が目標を持ち出すたびに再確認し、古い目標の記録を鵜呑みにしないでください。
• 測定ツールを確認します。どのパス／ファイルが集計対象ですか（追跡対象のみか、生成物か、バイナリか、テストか）？ 自分で指標を定義する必要がある場合は、デフォルトとして空行ではなく、コメントだけでもない行を対象とし、ドキュメントコメントを数えるかどうかを明記して、結果を比較できるようにしてください。
• ベースラインの合計と領域ごとの内訳を記録します。

0b — フィードバックループを確立します（最も重要な前提条件）。 検証できないコードを安全に削減することはできません。セーフティネットの優先順位を付け、不足しているものを最初に整備してください。

1. ベースラインでテストがすべて成功し、変更対象を実際にカバーしていること。 テストが乏しいことは最大のリスクです。まずカバレッジを補うか、徹底した実行時チェックを行い、細心の注意を払って作業してください。
2. 静的解析／型チェック／リンターがクリーンであること。 アナライザーがない場合、最低限必要なのはパース／コンパイルのチェックとテストです。 変更のたびに再実行してください。
3. 実際のシステムをエンドツーエンドで実行し、動作を確認します。 システムの形態に合った方法を選んでください。アプリのドライバー／UI 自動化、HTTP 呼び出し、CLI の実行、統合テスト、または（ライブラリの場合）利用者／サンプルを通じた公開 API の実行などです。最もよくある、最も危険な不足は、実行時のフィードバックループがないことです。 ユニットテストで証明できるのは契約であり、「実際に動く」ことではありません。動作を確認できない場合は、それが重大なリスクであることを認識し、ドライバーを作成するか、リスクを明確に示してください。作業中に実際に実行してください。

0c — ロールバックに備えます。 ブランチで作業してください（main では作業しないでください）。検証済みのマイルストーンごとにコミットし、どの変更も簡単に元に戻せるようにしてください。大胆な削除や書き換えを行うときこそ、これが必要です。

0d — 実際のツールでコードを把握します（grep ではなく）。 セマンティックツールを使って、デッドコード／未使用エクスポートのレポートと、依存関係グラフ＋複雑さのホットスポットを取得してください。grep はコードインテリジェンスではありません。 相対インポート、再エクスポート、ティアオフ、動的／文字列ディスパッチを見落とし、「デッドコード」という誤った判断につながります。grep はツールの検出結果を確認する場合に限って使用してください。何もインストールされておらず、インストールもできない場合のツールの代替手段は、言語サーバー → 最小限の AST スクリプト（貼り付けて使えるスニペットは references/minimal-tools.md にあります） → grep は確認専用、の順です。

0e — 分類し、削減の下限を算出します。 集計対象のコードを製品に含めるコード、テスト／開発用の補助コード、生成物／プラットフォーム固有／ベンダー提供コード（「下限」）に分けます。削減できない下限（生成された設定、行数として数えられるバイナリアセット、サードパーティコード）を算出し、計算してください。目標は floor + genuine feature minimum を超えて実現可能でしょうか？ そうでなければ、今すぐ伝えてください。残りの差はエンジニアリングの問題ではなく、プロダクト／スコープの判断です。

1. 誠実な削減の順序

正当性／価値の順序 — 下に進むほどリスクは高まります：1～2は安全です。6～8はリスクが高く、強力なフィードバックループが必要です（§0b）。各ステップの後に検証してください（§4）。

1. デッドコードを削除する — 参照がまったくないファイル／エクスポート／関数（grepではなく、セマンティックツールで検証）。純粋なプラスです。
2. プレースホルダー／何もしないサブシステムを削除する — 完全に組み込まれているのに何もしない機能（「利用不可」にハードコードされた切り替え、ログを記録するだけで何もしないメソッドなど）。機能としては無駄です。純粋なプラスです。
3. 配置場所が間違っているコードを、本来あるべき場所に移す — 製品コードにあるテスト／開発／自動化用の足場コードを、薄い境界を介して test/ または dev/ 領域に移します。実際の構造改善であり、変更していない測定値にも反映されます。（ファイルの移動は測定値の編集とは異なります — §2。）
4. 実際に重複しているコードを統合する — 繰り返しのブロックを、パラメーター化したヘルパーにまとめます。よく似たN個のファイルを1つにまとめます。（LOCはほぼ変わらないことが多いですが、明確さのために行います。）
5. コメント／冗長さを整える — コードの言い換えにすぎないコメントや、AIが残したノイズを整理します。正当な改善ですが、そこに落とし穴があります： 最も手軽な手段で、満足のいく削減ができても、設計上の改善はゼロです。すでに書き換えているファイルで、ついでに行う分には問題ありません。落とし穴は、これを単独の戦略として行うことです。「進捗」の大半がこれなら、自己監査を確認してください。
6. テストを仕様としたクリーンルーム書き換え — テストを基準に、蓄積した不要物を捨てて、最大のファイルをゼロから書き直します。テストが忠実な動作仕様になっている場合にのみ安全です。そうでなければ、バグを機能として書き直してしまいます。（すでに整理されたコードでは、控えめな密度向上が一般的です。目標ではありません。）
7. アーキテクチャを簡素化する — 冗長なレイヤーを統合し、アンチパターンをなくし、モジュールの凝集度を高めます。SLOCはほぼ変わらないか、むしろ増えることが大半です — 数字ではなく、品質のために行ってください。 §5の落とし穴に注意してください。
8. ライブラリに委ねる — 自作コードを成熟した依存関係に置き換えると、集計対象のツリーからコードを取り除け、通常はより良い選択にもなります。ただし、そのライブラリが本当に優れた選択肢である場合に限ります。測定値を避けるために使ってはならず、依存関係のコストも考慮してください。

1～8をすべて実施しても目標を超えている場合、残された手段は機能／スコープ／プラットフォームの削減だけです。これは製品上の判断です。下限値の計算を示して人間にエスカレーションし、機能を黙って削除してはなりません。

---

2. 数字の操作と誠実さ（2回読んでください）

境界線はここです。システム自体が本当にシンプルで良くなったのか、それとも数字を動かしただけなのか？

対応	判定	理由
測定ツールを編集して、特定のパスを除外する	❌ 数字の操作	対象ではなく、物差しを変えています。
フォーマッターの設定を広げる／行を詰める／空白行を削除して数値を改善する	❌ 数字の操作	表面的な変更で、実質的な改善がなく、可読性を損ないます。
数値を改善するために実際の機能／ドキュメントを削除する	❌ 数字の操作（デッド／プレースホルダーでない限り）	整理に見せかけたスコープ削減です — エスカレーションしてください。
テスト／開発コードをテスト／開発用ディレクトリに移す	✅ 正当	構造を正し、測定値が実態に沿います。
デッド／プレースホルダー／重複コードを削除する	✅ 正当	システムを実際に小さくしています。
言い換えコメント／AIノイズのコメントを整理する	✅ 正当な整理 — 戦略にしてはなりません	手軽な手段ですが、頼りすぎると本来の趣旨から外れます。
自作コードを実際のライブラリに委ねる	✅ 正当（エンジニアリング上、より良い場合）	自分で保守するコードが減り、品質も上がります。

測定上の注意点： 自動フォーマッターが、削減した行を気づかないうちに元に戻し、「成果」を見せかけにしてしまうことがあります。フォーマットに関する方針を1つに固定し、フォーマットを正規化した差分を測定してください（一貫した方法でコピーを再フォーマットし、差分を取る）。これにより、実際の削減とフォーマットのノイズを切り分けられます。サブエージェントに場当たり的な再フォーマットをさせないでください。

誠実さを保つ義務： 下限値を正直に報告してください。目標が制約（全機能／全プラットフォームの維持、数字の操作をしないこと）と衝突する場合は、データを示して明らかにし、人間に選択を委ねてください。実行していないことを「動作する」と主張してはなりません。省略した内容とその理由を報告し、構造的な改善と手軽な削減の内訳も報告してください（自己監査）。

3. 停止条件とエスカレーション

• 効果の逓減： 連続するマイルストーンで成果がほとんどなく、リスクが高まる場合、または残る手段がすべて SLOC を変えないアーキテクチャ変更の場合は、そこで止めて報告し、無理に変更を作り出さないでください。（リファクタリング→後悔→元に戻す、というループに注意してください。）
• スコープ拡大の防止： このセッション中に完了して検証できない再アーキテクチャには着手しないでください。レイヤーが半端に統合された状態や、パターンが半端に移行された状態は、何もしないよりも悪い結果になります。
• 下限到達： 機能・スコープ・プラットフォームの削減しか残っていない場合は、数値を示してトレードオフを担当者にエスカレーションしてください。それを判断するのは担当者です。

4. 検証の頻度

定義は references/preflight-checklist.md → 「作業中のループ」 に一度だけ記載されています。要約すると、変更のたびに静的解析またはコンパイルと、関連するテストを実行します。マイルストーンでは、全テストスイートを実行し、代表的なターゲット上で実際のシステムを実行して敵対的な条件でテストします（操作を素早く連続して行う、不正な入力を与える、モードを切り替えるなど。潜在的なバグや新たに入り込んだバグが表面化するのはこうした場面です）。その後、再計測してコミットします。

5. 落とし穴とリスク

リスク	緩和策
テストがない、または不十分で、盲目的なリファクタリングになる	まず変更対象の領域のカバレッジを高め、実行時のテストを活用してください。
実行時のフィードバックループがない	削減に着手する前に、エンドツーエンドのテスト環境を構築して確保し、実際に実行してください。
grep を分析に使い、未使用コードを誤判定する	セマンティックツールを使い、grep は確認にのみ使ってください。
フォーマッターによる増加	フォーマットを1つに固定し、フォーマットを正規化した差分を計測してください。
「深いモジュール／リファクタリングは行数削減とは限らない」	凝集性を高める作業では足場となるコードが増えます。設計のために行い、SLOC 削減として売り込まないでください。
神オブジェクトの落とし穴	冗長なレイヤーを統合すると、受け手側に責務が過度に集中し、取り除いたはずの問題が再発することがあります。統合後に、凝集性の高い協調オブジェクトを抽出してください。
並行作業のエージェントが同じツリーを変更する	リスクが高い変更や重複する編集は順番に実行し、並行作業はファイルが重複しない場合に限り、最後に全体を検証してください。
生成コード／プラットフォーム／ネイティブコードを、変更不可または削減し放題とみなす	よくある見落としです。生成された足場コードは確かに下限ですが、実際のカスタムネイティブ／プラットフォームコードは他のコードと同様に削減できます。どちらなのかを把握し、後者を軽視しないでください。
効果の逓減を失敗と取り違える	スコープ削減しか残っていない状況を認識し、エスカレーションしてください（§3）。

6. 参考資料

• references/preflight-checklist.md — コピー＆ペーストで使える事前チェックと、作業中の標準ループ。
• references/minimal-tools.md — SLOC のカウント方法と、セマンティックツールがインストールされていない場合に使える、未使用コード／孤立したインポートを検出するスクリプト。
• references/flutter-sloc-reference.md — Flutter／Dart 固有の情報（hooks と StatefulWidget、GlobalKey→controller、provider／ChangeNotifier のレイヤリング、sealed class、データ駆動型 UI、プラットフォームの下限、dart format、DCM／GitNexus、VM サービス拡張機能を使ったアプリの操作）。