Fork Discipline

マルチクライアント・コードベースの core/client 境界を監査します。すべてのマルチクライアント・プロジェクトは、共有プラットフォーム・コード（core）とデプロイメントごとのコード（client）との間に明確な分離を持つべきです。このスキルは、その境界がどこで曖昧になっているかを見つけ、修正方法を示します。

原則

project/
  src/            ← CORE: 共有プラットフォーム・コード。クライアントごとに修正しない。
  config/         ← DEFAULTS: ベース設定、機能フラグ、妥当なデフォルト。
  clients/
    client-name/  ← CLIENT: デプロイメントごとに異なるすべてのもの。
      config      ← デフォルト上にマージされたオーバーライド
      content     ← シード・データ、ナレッジベース記事、テンプレート
      schema      ← ドメイン・テーブル、マイグレーション（0100 以降の番号）
      custom/     ← 独自機能（ルート、ページ、ツール）

fork テスト: ファイルを修正する前に、「これは core か client か」と自問してください。判断できない場合、境界が十分にクリーンではありません。

使用時機

• 既存プロジェクトに 2 番目または 3 番目のクライアントを追加する前
• プロジェクトが有機的に成長し、境界が曖昧になった後
• if (client === 'acme') チェックが共有コードに入り込んでいることに気づいた時
• 実装と特定の違いを理解するための大規模リファクタ前
• 新しい開発者をオンボードする際にアーキテクチャを理解させたい時
• マルチクライアント・プロジェクトの定期的なヘルスチェック

モード

モード	トリガー	出力物
audit	"fork discipline", "check the boundary"	境界マップ + 違反報告書
document	"write FORK.md", "document the boundary"	プロジェクト用 FORK.md ファイル
refactor	"clean up the fork", "enforce the boundary"	リファクタリング計画 + マイグレーション・スクリプト

デフォルト: audit

---

Audit モード

ステップ 1: プロジェクト・タイプの検出

マルチクライアント・プロジェクトであるか、どのパターンを使用しているかを判定します：

シグナル	パターン
clients/ または tenants/ ディレクトリ	明示的なマルチクライアント
クライアント名を持つ複数の設定ファイル	設定駆動型マルチクライアント
共有パッケージ + クライアント別パッケージを持つ packages/	Monorepo マルチクライアント
CLIENT_NAME や TENANT_ID のような環境変数	ランタイム・マルチクライアント
単一デプロイメント、クライアント・ディレクトリなし	シングルクライアント（マルチクライアントへ移行する可能性あり）

シングルクライアントの場合: プロジェクトの CLAUDE.md またはコードベースが将来マルチクライアントになることを示唆しているかを確認します。示唆がある場合は準備状況を監査します。本当にシングルクライアント専用の場合、このスキルは不要です。

ステップ 2: 境界をマップする

コードベースをスキャンして境界マップを構築します：

CORE（すべてのクライアントで共有）:
  src/server/          → API ルート、ミドルウェア、認証
  src/client/          → React コンポーネント、フック、ページ
  src/db/schema.ts     → 共有データベース・スキーマ
  migrations/0001-0050 → Core マイグレーション

CLIENT（デプロイメントごと）:
  clients/acme/config.ts    → クライアント・オーバーライド
  clients/acme/kb/          → ナレッジベース記事
  clients/acme/seed.sql     → シード・データ
  migrations/0100+          → クライアント・スキーマ拡張

BLURRED（注意が必要）:
  src/server/routes/acme-custom.ts  → Core の中のクライアント・コード！
  src/config/defaults.ts line 47    → ハードコードされたクライアント・ドメイン

ステップ 3: 違反を検出

これらの特定のアンチパターンをスキャンします：

Core コード内のクライアント名

# 共有コード内のハードコードされたクライアント識別子を検索
grep -rn "acme\|smith\|client_name_here" src/ --include="*.ts" --include="*.tsx"

# クライアント固有の条件分岐を検索
grep -rn "if.*client.*===\|switch.*client\|case.*['\"]acme" src/ --include="*.ts" --include="*.tsx"

# 共有コード内の環境ベースのクライアント・チェックを検索
grep -rn "CLIENT_NAME\|TENANT_ID\|process.env.*CLIENT" src/ --include="*.ts" --include="*.tsx"

重大度: 高。Core コード内のハードコードされたクライアント・チェックは、次のクライアントが共有コードの修正を必要とすることを意味します。

マージではなく置換する設定

クライアント設定がファイル全体を置換するか、デフォルト上にマージするかを確認します：

// 悪い例 — クライアント設定は完全な置換
// clients/acme/config.ts
export default {
  theme: { primary: '#1E40AF' },
  features: { emailOutbox: true },
  // 他のデフォルトすべてが欠けている — 失われている
}

// 良い例 — クライアント設定はデフォルト上にマージされたデルタ
// clients/acme/config.ts
export default {
  theme: { primary: '#1E40AF' },  // 異なるもののみをオーバーライド
}
// config/defaults.ts に他のすべてがある

探す対象: デフォルト・ファイルのサイズに近い、疑わしいほど大きなクライアント設定ファイル、またはデフォルトが既に処理しているフィールドを定義しているクライアント設定。

重大度: 中。古いクライアント設定は新しいデフォルトと機能を見落とします。

クライアント・コードの分散

クライアント固有のコードがクライアント・ディレクトリ外に存在するかを確認します：

# src/ 内のパスにクライアント名を持つファイル
find src/ -name "*acme*" -o -name "*smith*" -o -name "*client-name*"

# 単一クライアントを提供するルートまたはページ
grep -rn "// only for\|// acme only\|// client-specific" src/ --include="*.ts" --include="*.tsx"

重大度: 高。src/ のクライアント・コードは core が本当に共有されていないことを意味します。

拡張ポイントの欠落

Core が修正なしでクライアント・カスタマイズのメカニズムを持っているかを確認します：

拡張ポイント	確認方法	有効化内容
設定マージ	config/ にマージ関数があるか	置換なしでクライアント・オーバーライド
動的インポート	Core が clients/{name}/custom/ を探すか	クライアント固有のルート/ページ
機能フラグ	機能はコードではなく設定でトグルされるか	クライアントごとに有効/無効
テーマ・トークン	色/スタイルが変数にあるか、ハードコードされていないか	ビジュアル・カスタマイズ
コンテンツ・インジェクション	クライアントがシード・データ、テンプレートを提供できるか	クライアント固有のコンテンツ
フック/イベント・システム	クライアントがパッチなしで動作を拡張できるか	カスタム・ビジネス・ロジック

重大度: 中。拡張ポイントの欠落は client コードを core に強要します。

マイグレーション番号の競合

# すべてのマイグレーション・ファイルとその番号をリストアップ
ls migrations/ | sort | head -20

# クライアント・マイグレーションが予約された範囲にあるかを確認
# Core: 0001-0099、クライアント・ドメイン: 0100-0199、クライアント・カスタム: 0200+

重大度: 競合が発生するまでは低、その後は重大。

機能フラグ vs クライアント・チェック

// 悪い例 — クライアント名チェック
if (clientName === 'acme') {
  showEmailOutbox = true;
}

// 良い例 — 設定の機能フラグ
if (config.features.emailOutbox) {
  showEmailOutbox = true;
}

動作がクライアント・アイデンティティではなく設定に基づいて分岐するパターンを検索します。

ステップ 4: レポートを作成

.jez/artifacts/fork-discipline-audit.md に書き込みます：

# Fork Discipline 監査: [Project Name]
**日時**: YYYY-MM-DD
**パターン**: [明示的マルチクライアント / 設定駆動型 / monorepo / シングル→マルチ移行中]
**クライアント**: [クライアント・デプロイメントのリスト]

## 境界マップ

### Core（共有）
| パス | 目的 | クリーン？ |
|------|------|----------|
| src/server/ | API ルート | Yes / No — [問題] |

### Client（デプロイメントごと）
| クライアント | Config | Content | Schema | Custom |
|-----------|--------|---------|--------|--------|
| acme | config.ts | kb/ | 0100-0120 | custom/routes/ |

### Blurred（注意が必要）
| パス | 問題 | 推奨される修正 |
|------|------|--------------|
| src/routes/acme-custom.ts | Core 内のクライアント・コード | clients/acme/custom/ に移動 |

## 違反

### 高重大度
[file:line、説明、修正方法付きリスト]

### 中重大度
[file:line、説明、修正方法付きリスト]

### 低重大度
[リスト]

## 拡張ポイント
| ポイント | 存在？ | 注記 |
|---------|--------|------|
| 設定マージ | Yes/No | |
| 動的インポート | Yes/No | |
| 機能フラグ | Yes/No | |

## ヘルススコア
[1-10] — [説明]

## トップ 3 の推奨事項
1. [最大インパクト修正]
2. [2 番目の優先度]
3. [3 番目の優先度]

---

Document モード

プロジェクト・ルートの FORK.md を生成して境界をドキュメント化します：

# Fork Discipline

## アーキテクチャ

このプロジェクトは共有コードベースから複数のクライアントをサービスします。

### Core（クライアントごとに修正しない）
[ディレクトリとその目的のリスト]

### Client（デプロイメントごとに異なる）
[クライアント・ディレクトリ構造と説明]

### 新しいクライアントを追加する方法
1. `clients/_template/` を `clients/new-client/` にコピー
2. クライアント・オーバーライドで `config.ts` を編集
3. `content/` にシード・データを追加
4. 0100+ の番号でマイグレーションを作成
5. `CLIENT=new-client wrangler deploy` でデプロイ

### Fork テスト
ファイルを修正する前に: これは core か client か？
- Core → `src/` での変更、すべてのクライアントが恩恵
- Client → `clients/name/` での変更、他のクライアントに影響なし
- 判断できない → 境界をまず修正する必要があります

### マイグレーション番号付け
| 範囲 | オーナー |
|------|---------|
| 0001-0099 | Core プラットフォーム |
| 0100-0199 | クライアント・ドメイン・スキーマ |
| 0200+ | クライアント・カスタム機能 |

### 設定マージ・パターン
クライアント設定はデフォルト上に浅くマージされます：
[プロジェクトからの実際のマージ・コード]

---

Refactor モード

監査後、境界を強制する具体的なステップを生成します：

1. Core からのクライアント・コードの移動

クライアント・コードが src/ 内に存在する違反ごとに：

# クライアント・ディレクトリが存在しない場合は作成
mkdir -p clients/acme/custom/routes

# ファイルを移動
git mv src/routes/acme-custom.ts clients/acme/custom/routes/

# 動的検出を使用するよう core のインポートを更新

2. クライアント・チェックを機能フラグに置換

Core 内の各 if (client === ...) に対して：

// 前（src/ 内）
if (clientName === 'acme') {
  app.route('/email-outbox', emailRoutes);
}

// 後（src/ 内）— 機能フラグ
if (config.features.emailOutbox) {
  app.route('/email-outbox', emailRoutes);
}

// 後（clients/acme/config.ts 内）— クライアントが有効化
export default {
  features: { emailOutbox: true }
}

3. 設定マージを実装

設定を置換するのではなくマージするプロジェクトの場合：

// config/resolve.ts
import defaults from './defaults';

export function resolveConfig(clientConfig: Partial<Config>): Config {
  return {
    ...defaults,
    ...clientConfig,
    features: { ...defaults.features, ...clientConfig.features },
    theme: { ...defaults.theme, ...clientConfig.theme },
  };
}

4. カスタム・ルートの拡張ポイントを追加

クライアントがカスタム・ルートを必要とするが、現在 core を修正している場合：

// src/server/index.ts — クライアント・ルートの自動検出
const clientRoutes = await import(`../../clients/${clientName}/custom/routes`)
  .catch(() => null);
if (clientRoutes?.default) {
  app.route('/custom', clientRoutes.default);
}

5. リファクタリング・スクリプトを生成

.jez/scripts/fork-refactor.sh にスクリプトを書き込みます：

• クライアント・ディレクトリ構造を作成
• 識別されたファイルを移動
• インポート・パスを更新
• FORK.md を生成

---

実行に適切な時機

クライアント数	実施内容
1	リファクタしない。境界をドキュメント化（FORK.md）するだけで、どこにあるかを知ります。
2	監査を実行。高重大度違反を修正。設定マージ・パターンを開始。
3+	フル・リファクタ・モード。境界はクリーンである必要があります — 実装と特定を証明する必要があります。

ルール 5: クライアント #3 まで抽象化しない。1 クライアントで推測、2 クライアントでパターン・マッチング、3 クライアント以上で何が本当に異なるかを知ります。

ヒント

• 新しいクライアントを追加した後ではなく、前に実行してください
• 設定マージは単一最高 ROI リファクタ — 最初に実施してください
• 機能フラグは 1 クライアント時でも if (client) を上回ります。「これはほぼ同じですが...」 = 機能フラグ、fork ではありません。
• FORK.md は Claude のためだけではなく、チーム向けです — 人間が読むように書いてください