component-identification-sizing

コンポーネントの特定とサイズ測定

このスキルでは、コードベース内のアーキテクチャ上のコンポーネント（論理的な構成要素）を特定し、サイズ指標を計算して、分解の実現可能性を評価し、サイズが大きすぎるコンポーネントを特定します。

使用方法

クイックスタート

コードベースの分析を依頼します。

• 「このコードベース内のすべてのコンポーネントを特定してサイズを測定してください」
• 「分割が必要なサイズの大きすぎるコンポーネントを見つけてください」
• 「分解計画用のコンポーネント一覧を作成してください」
• 「コンポーネントのサイズ分布を分析してください」

使用例

例 1: 完全な分析

User: "Identify and size all components in this codebase"

The skill will:
1. Map directory/namespace structures
2. Identify all components (leaf nodes)
3. Calculate size metrics (statements, files, percentages)
4. Generate component inventory table
5. Flag oversized/undersized components
6. Provide recommendations

例 2: サイズの大きすぎるコンポーネントを見つける

User: "Which components are too large?"

The skill will:
1. Calculate mean and standard deviation
2. Identify components >2 std dev or >10% threshold
3. Analyze functional areas within large components
4. Suggest specific splits with estimated sizes

例 3: コンポーネントのサイズ分析

User: "Analyze component sizes and distribution"

The skill will:
1. Calculate all size metrics
2. Generate size distribution summary
3. Identify outliers
4. Provide statistics and recommendations

ステップごとの手順

1. 初期分析: まずコンポーネントの完全な一覧を作成します
2. 問題の特定: 対応が必要なコンポーネントを見つけます
3. 推奨事項の取得: 実行可能な分割・統合案を依頼します
4. 進捗の監視: コンポーネントの成長を継続的に追跡します

使用するタイミング

次の場合にこのスキルを適用します。

• モノリシックな構成の分解に着手するとき
• コードベースの構造と構成を評価するとき
• サイズが大きすぎる、または小さすぎるコンポーネントを特定するとき
• 移行計画用のコンポーネント一覧を作成するとき
• コンポーネント間のコード分布を分析するとき
• コンポーネントベースの分解パターンを導入する準備をするとき

基本概念

コンポーネントの定義

コンポーネントとは、次の特徴を持つアーキテクチャ上の構成要素です。

• 明確に定義された役割と責任を持つ
• 名前空間、パッケージ構造、またはディレクトリパスによって識別される
• 関連するソースコードファイル（クラス、関数、モジュール）を含む
• 特定のビジネス機能またはインフラストラクチャ機能を実行する

重要なルール: コンポーネントは、ディレクトリ／名前空間構造のリーフノードによって識別されます。名前空間が拡張される場合（たとえば、services/billing が services/billing/payment に拡張される場合）、親はコンポーネントではなくサブドメインになります。

サイズ指標

ステートメント（コード行数ではありません）:

• セミコロンまたは改行で終わる実行可能なステートメントを数えます
• サイズを比較する際、コード行数よりも正確です
• 書式ではなく、コードの複雑さを考慮します

コンポーネントのサイズ指標:

• コードベースに占める割合: コンポーネントのステートメント数 / ステートメントの総数
• ファイル数: コンポーネント内のソースファイル数
• 標準偏差: コンポーネントサイズの平均からの距離

分析プロセス

フェーズ 1: コンポーネントの特定

コードベースのディレクトリ構造をスキャンします。

1. ディレクトリ／名前空間構造をマッピングする

   • Node.js の場合: services/、routes/、models/、utils/
   • Java の場合: パッケージ構造（例: com.company.domain.service）
   • Python の場合: モジュールパス（例: app/billing/payment）

2. リーフノードを特定する

   • コンポーネントは、ソースファイルを含む最も深い階層のディレクトリです
   • 例: services/BillingService/ はコンポーネントです
   • 例: services/BillingService/payment/ はその配下に拡張されているため、BillingService はサブドメインになります

3. コンポーネント一覧を作成する

   • 各コンポーネントの名前空間／パスを一覧にします
   • 親名前空間（サブドメイン）があれば記録します

フェーズ 2: サイズ指標の計算

各コンポーネントについて、次の手順を実行します。

1. ステートメント数を数える

   • コンポーネントディレクトリ内のソースファイルを解析します
   • 実行可能なステートメントを数えます（コメント、空行、宣言のみの行は除外）
   • コンポーネント内の全ファイルの数を合計します

2. ファイル数を数える

   • ソースファイルの合計数（.js、.ts、.java、.py など）を数えます
   • テストファイル、設定ファイル、ドキュメントは除外します

3. 割合を計算する

   component_percent = (component_statements / total_statements) * 100
   

4. 統計値を計算する

   • コンポーネントサイズの平均: total_statements / number_of_components
   • 標準偏差: sqrt(sum((size - mean)^2) / (n - 1))
   • コンポーネントの偏差: (component_size - mean) / std_dev

フェーズ 3：サイズの問題を特定する

大きすぎるコンポーネント（分割候補）：

• コードベース全体の 30% を超える（コンポーネントが 10 未満の小規模アプリの場合）
• コードベース全体の 10% を超える（コンポーネントが 20 を超える大規模アプリの場合）
• 平均より標準偏差で 2 以上大きい
• 複数の異なる機能領域を含む

小さすぎるコンポーネント（統合候補）：

• コードベース全体の 1% 未満（細分化されすぎている可能性があります）
• 平均より標準偏差で 1 以上小さい
• 機能がごくわずかなファイルしか含まない

適切なサイズのコンポーネント：

• 平均から標準偏差で 1～2 の範囲内
• 単一のまとまりのある機能領域を表す
• アプリケーションの規模に応じた適切な割合である

出力形式

コンポーネント一覧表

## Component Inventory

| Component Name  | Namespace/Path               | Statements | Files | Percent | Status       |
| --------------- | ---------------------------- | ---------- | ----- | ------- | ------------ |
| Billing Payment | services/BillingService      | 4,312      | 23    | 5%      | ✅ OK        |
| Reporting       | services/ReportingService    | 27,765     | 162   | 33%     | ⚠️ Too Large |
| Notification    | services/NotificationService | 1,433      | 7     | 2%      | ✅ OK        |

ステータスの凡例：

• ✅ OK：適切なサイズ（平均から標準偏差で 1～2 の範囲内）
• ⚠️ 大きすぎる：サイズのしきい値を超える、または平均より標準偏差で 2 を超えて大きい
• 🔍 小さすぎる：コードベース全体の 1% 未満、または平均より標準偏差で 1 を超えて小さい

サイズ分析の概要

## Size Analysis Summary

**Total Components**: 18
**Total Statements**: 82,931
**Mean Component Size**: 4,607 statements
**Standard Deviation**: 5,234 statements

**Oversized Components** (>2 std dev or >10%):

- Reporting (33% - 27,765 statements) - Consider splitting into:
  - Ticket Reports
  - Expert Reports
  - Financial Reports

**Well-Sized Components** (within 1-2 std dev):

- Billing Payment (5%)
- Customer Profile (5%)
- Ticket Assignment (9%)

**Undersized Components** (<1 std dev):

- Login (2% - 1,865 statements) - Consider consolidating with Authentication

コンポーネントのサイズ分布

## Component Size Distribution

コンポーネントのサイズ分布（コードベース全体に占める割合）

［可能であれば視覚的な表現またはヒストグラム］

最大：████████████████████████████████████ 33%（Reporting） ████████ 9%（Ticket Assign） ██████ 8%（Ticket） ██████ 6%（Expert Profile） █████ 5%（Billing Payment） ████ 4%（Billing History） ...

### Recommendations

```markdown
## Recommendations

### High Priority: Split Large Components

**Reporting Component** (33% of codebase):
- **Current**: Single component with 27,765 statements
- **Issue**: Too large, contains multiple functional areas
- **Recommendation**: Split into:
  1. Reporting Shared (common utilities)
  2. Ticket Reports (ticket-related reports)
  3. Expert Reports (expert-related reports)
  4. Financial Reports (financial reports)
- **Expected Result**: Each component ~7-9% of codebase

### Medium Priority: Review Small Components

**Login Component** (2% of codebase):
- **Current**: 1,865 statements, 3 files
- **Consideration**: May be too granular if related to broader authentication
- **Recommendation**: Evaluate if should be consolidated with Authentication/User components

### Low Priority: Monitor Well-Sized Components

Most components are appropriately sized. Continue monitoring during decomposition.

分析チェックリスト

コンポーネントの特定：

• すべてのディレクトリ／名前空間の構造をマッピングした
• リーフノード（コンポーネント）と親ノード（サブドメイン）を特定した
• コンポーネントの完全な一覧を作成した
• 各コンポーネントの名前空間／パスを記録した

サイズの計算：

• 各コンポーネントのステートメント数を数えた（行数ではない）
• ソースファイル数を数えた（テスト／設定ファイルを除く）
• コードベース全体に占める割合を計算した
• 平均と標準偏差を計算した

サイズの評価：

• 大きすぎるコンポーネントを特定した（しきい値超過、または標準偏差で 2 を超える）
• 小さすぎるコンポーネントを特定した（1% 未満、または標準偏差で 1 未満）
• 分割または統合が必要なコンポーネントにフラグを付けた
• サイズ分布を記録した

推奨事項：

• 大きすぎるコンポーネントの分割案を提案した
• 小さすぎるコンポーネントの統合案を提案した
• 影響度に基づいて推奨事項に優先順位を付けた
• リファクタリング用のアーキテクチャストーリーを作成した

実装上の注意

Node.js/Express アプリケーションの場合

一般的にコンポーネントは次の場所にあります。

• services/ - ビジネスロジックのコンポーネント
• routes/ - API エンドポイントのコンポーネント
• models/ - データモデルのコンポーネント
• utils/ - ユーティリティのコンポーネント
• middleware/ - ミドルウェアのコンポーネント

コンポーネント特定の例：

services/
├── BillingService/          ← Component (leaf node)
│   ├── index.js
│   └── BillingService.js
├── CustomerService/          ← Component (leaf node)
│   └── CustomerService.js
└── NotificationService/      ← Component (leaf node)
    └── NotificationService.js

Java アプリケーションの場合

コンポーネントはパッケージ構造によって特定します。

• com.company.domain.service - サービスコンポーネント
• com.company.domain.model - モデルコンポーネント
• com.company.domain.repository - リポジトリコンポーネント

コンポーネント特定の例：

com.company.billing.payment   ← Component (leaf package)
com.company.billing.history   ← Component (leaf package)
com.company.billing           ← Subdomain (parent of payment/history)

ステートメント数のカウント

JavaScript/TypeScript：

• ; または改行で終わるステートメントを数える
• 含めるもの：代入、関数呼び出し、return、条件分岐、ループ
• 除外するもの：コメント、空行、代入を伴わない宣言

Java：

• ; で終わるステートメントを数える
• 含めるもの：メソッド呼び出し、代入、return、条件分岐
• 除外するもの：クラス／インターフェース宣言、コメント、空行

Python：

• 実行可能なステートメントを数える（コメントや空行は含めない）
• 含めるもの：代入、関数呼び出し、return、条件分岐
• 除外するもの：docstring、コメント、空行

フィットネス関数

コンポーネントの特定とサイズ測定の後、自動チェックを作成します。

コンポーネントサイズのしきい値

// Alert if any component exceeds 10% of codebase
function checkComponentSize(components, threshold = 0.1) {
  const totalStatements = components.reduce((sum, c) => sum + c.statements, 0)
  return components
    .filter((c) => c.statements / totalStatements > threshold)
    .map((c) => ({
      component: c.name,
      percent: ((c.statements / totalStatements) * 100).toFixed(1),
      issue: 'Exceeds size threshold',
    }))
}

標準偏差のチェック

// Alert if component is >2 standard deviations from mean
function checkStandardDeviation(components) {
  const sizes = components.map((c) => c.statements)
  const mean = sizes.reduce((a, b) => a + b, 0) / sizes.length
  const stdDev = Math.sqrt(sizes.reduce((sum, size) => sum + Math.pow(size - mean, 2), 0) / (sizes.length - 1))

  return components
    .filter((c) => Math.abs(c.statements - mean) > 2 * stdDev)
    .map((c) => ({
      component: c.name,
      deviation: ((c.statements - mean) / stdDev).toFixed(2),
      issue: 'More than 2 standard deviations from mean',
    }))
}

ベストプラクティス

推奨事項 ✅

• コード行数ではなく、ステートメント数を使用する
• コンポーネントはリーフノードのみとして特定する
• 割合と標準偏差の両方を計算する
• しきい値を設定する際はアプリケーションの規模を考慮する
• 各コンポーネントの名前空間／パスを記録する
• 可能であればサイズ分布を視覚化する

避けること ❌

• コンポーネントの規模を測る際に、テストファイルを数えない
• 親ディレクトリをコンポーネントとして扱わない
• アプリの規模を考慮せず、固定のしきい値を使わない
• 小さなコンポーネントを無視しない（統合が必要な場合があります）
• 標準偏差の計算を省略しない
• インフラストラクチャとドメインのコンポーネントを同じ分析に混在させない

次のステップ

コンポーネントの特定と規模の測定が完了したら：

1. 共通ドメインコンポーネントの収集パターンを適用する - 重複する機能を特定します
2. コンポーネントのフラット化パターンを適用する - ルート名前空間から孤立したクラスを取り除きます
3. コンポーネントの依存関係の特定パターンを適用する - コンポーネント間の結合を分析します
4. コンポーネントドメインを作成する - コンポーネントを論理的なドメインにグループ化します

注記

• コンポーネントの規模に関するしきい値は、アプリの規模によって異なります
• 小規模なアプリ（コンポーネントが10個未満）では、30％のしきい値が適切な場合があります
• 大規模なアプリ（コンポーネントが20個超）では、10％のしきい値がより適切です
• 固定の割合よりも標準偏差のほうが信頼性が高いです
• 適切な規模のコンポーネントは、平均から1〜2標準偏差の範囲にあります
• 規模が大きすぎるコンポーネントには、分割可能な複数の機能領域が含まれていることがよくあります