lego-programming

name	lego-programming
description	設計、計画、実装方針、実装、リファクタリング、コードレビュー、UI 分割、モジュール設計、責務分離、レイヤリング、コンポーネント設計を行うときに使う。コードを書く前の計画や設計レビュー、実装中、完了前、差分レビュー時に、機能を高凝集・疎結合な「レゴ」として境界づけ、組み合わせ、見直すための設計ガードレールを提供する。特に「責務が混ざっている」「どこで分けるべきか」「実装前に構成を決めたい」「計画段階で部品境界を確認したい」「既存コードにどう配置するか」「再利用できる部品にしたい」「この差分の部品境界をレビューしたい」といった文脈では必ず確認する。

Lego Programming

目的

実装対象を、小さく説明可能な部品に分けてから組み立てる。

ここでいう「レゴ」は、単なる小さいファイルではない。明確な責務、入力、出力、依存方向を持ち、他の部品と組み合わせても内部実装を漏らさないモジュール、コンポーネント、関数、型、サービス、ライブラリを指す。

この skill は設計を大きくしすぎるためではなく、変更理由が違うものを混ぜないために使う。既存コードの構造、命名、公開契約を優先し、その範囲で自然な境界を作る。

使い方

設計時、計画時、実装前、実装中、完了前、またはコードレビュー時に次を確認する。

1. 境界を決める

   • 今回作るレゴを 2-5 個程度の責務として言えるか。
   • それぞれの入力、出力、副作用、所有する状態が説明できるか。
   • UI、ビジネスロジック、データ取得、永続化、外部 I/O が不用意に混ざっていないか。
   • 依存方向が既存アーキテクチャに沿っているか。

2. レゴを作る

   • 1 つのレゴに 1 つの変更理由を持たせる。
   • 呼び出し側が内部手順を知らなくてよい API にする。
   • 名前は「何をするか」ではなく「何の責務を持つか」が分かるものにする。
   • 既存の類似部品がある場合は、先に再利用または拡張を検討する。

3. レゴを組み合わせる

   • 上位のレゴは下位のレゴを調整するだけにし、細部の実装を抱え込まない。
   • データ変換、検証、永続化、表示などの接続点を明示する。
   • 組み合わせ部分が肥大化したら、それ自体を別のレゴとして切り出す。

4. 境界を見直す

   • 実装後に、責務、名前、配置、依存方向を再確認する。
   • 同じレゴを再利用できる将来ケースを 1 つ想像し、不自然なら境界を直す。
   • テストしたい単位とレゴの境界が大きくずれていないか確認する。

5. レビューする

   • 差分で新しく作られたレゴと、既存レゴへ追加された責務を分けて見る。
   • 変更理由が異なる処理が同じファイル、関数、コンポーネントへ押し込まれていないか確認する。
   • 呼び出し側が新しいレゴの内部手順や状態を知りすぎていないか確認する。
   • 境界の問題がバグ、回帰、テスト困難、将来の変更困難につながる場合は、レビュー指摘として具体的に書く。

判断基準

良いレゴは次の性質を持つ。

• 高凝集: 関連する状態とロジックが 1 つの責務にまとまっている。
• 疎結合: 呼び出し側が内部のデータ構造や手順に依存しない。
• 置き換え可能: 同じ contract を満たす別実装へ差し替えやすい。
• テスト可能: 外部 I/O や時間、乱数、グローバル状態を境界で分離できる。
• 配置が自然: 既存のレイヤー、ディレクトリ、命名に沿っている。

次の兆候があれば、境界を見直す。

• 1 つの関数やコンポーネントが「取得して、変換して、検証して、保存して、表示する」まで持っている。
• 引数が増え続け、呼び出し側が内部事情を知りすぎている。
• 同じデータ変換や条件分岐が複数箇所へコピーされている。
• テストで大量の無関係な setup が必要になる。
• 名前が manager、helper、utils、common のように責務を説明していない。

よくある境界

バックエンド:

• Controller / Handler: 入出力 protocol と request / response の責務
• UseCase / Service: ユーザー操作や業務処理の orchestration
• Domain Model / Entity / Value Object: ドメインの状態と不変条件
• Repository / Gateway / Client: 永続化や外部サービスとの境界
• Policy / Specification / Validator: 判断、条件、検証ルール
• Mapper / DTO / Serializer: 層をまたぐデータ変換

フロントエンド:

• Page / Route: routing と画面全体の組み立て
• Layout / Template: 領域構造と配置
• Organism / Feature Component: まとまった UI ワークフロー
• Molecule / Atom: 再利用可能な表示部品
• Custom Hook: UI から分離した状態管理や副作用
• API Client / Repository: データ取得と外部 I/O
• Presenter / ViewModel: 表示用の整形、派生値、文言の組み立て

共通:

• Package / Module / Library: 再利用可能な公開 contract
• Adapter: 外部形式と内部形式の変換
• Workflow / Job: 複数ステップの実行順序
• CLI / Plugin: 利用者との境界になる command surface

併用する skill

• 実装作業では code-general を併用し、仕様、公開契約、既存構造、検証方法を確認する。
• Go、TypeScript、React、Ruby、CSS など言語やフレームワーク固有の判断では該当する code-* skill を併用する。
• React / Next.js / TypeScript UI の大きな分割では component-design を先に使い、この skill で部品境界の品質を確認する。
• 命名で迷う場合は code-naming を併用する。
• 実装済み差分をレビューする場合は code-review を併用し、仕様違反や回帰リスクと部品境界の問題を分けて扱う。
• 実装済み差分の境界が次の開発者に伝わるか確認したい場合は code-next-developer-review を併用する。

完了前チェック

• 今回作った主なレゴの責務を 1 文ずつ説明できる。
• 各レゴの入力、出力、副作用、依存先が曖昧ではない。
• 上位レゴが下位レゴの内部実装を知りすぎていない。
• 既存コードの配置、命名、公開 contract から浮いていない。
• 変更理由が異なる処理を同じ場所に押し込んでいない。
• テストまたは検証が、作った境界に沿って説明できる。