module-dev

OSS モジュール型リポ（ポートフォリオ兼実用）の設計規範。新規リポの型決め・モジュール追加・配布形態やデモ方式の判断に適用する。

1. リポの型を決める

正体を「汎用部分 + 固有部分」に分離して一文で定義する。固有部分の実資産（実クライアントのテンプレート・実データ・本番パラメータ）はリポに置かない。

型は次の手順で判定する。

汎用部分は利用者のビルド・実行環境に取り込まれるか？ ── yes → 組み込み型
   └ no（利用者は読んで自分の文脈へ写す）
      提示するのは再利用できる機械か、問いと検証の作法か ── 機械 → ツールキット型
                                            └ 作法 → 研究型

1問目は import / require されるかどうかという客観的な事実で決まるため、通常は割れない。割れやすいのは2問目、ツールキット型と研究型の境目である。

ツールキット型 / 研究型のリトマス試験（迷ったらこちらで決める）: パラメータやデータを全部外部注入・設定に追い出しても、リポ単体で「動く機械」としての価値が残るか。残るなら機械が主役のツールキット型。残らないなら、つまり外部から注入されるのが答えそのものであり機械はそれを出すための手段でしかないなら、作法が主役の研究型になる。

型は3つ。

• clone リファレンスが既定。レジストリ公開は versioning・後方互換・英語 doc の継続コストを伴うため、組み込み型である場合か利用者が現れた場合にのみ払う。
• 言語はドメインのエコシステムに従う。「npm が標準」「pip が標準」という決め方をしない。

README の Type A/B/C との関係

repo-readme スキル §1 の Type A/B/C（README の書き方を決める分類）と、本節の組み込み型・ツールキット型・研究型（設計と配布形態を決める分類）は、別々に判定するものではなく、片方が決まればもう片方はおおむね決まる（機械的な1対1対応ではない）。組み込み型は利用者のビルドに取り込まれることが定義そのものなので、ほぼ必然的に Type B（利用保証型）になる。研究型は「問いと検証結果」自体が主張であり、Type C（実験型・Lab）の「測ったらこうだった」という主張とそのまま重なる。幅があるのはツールキット型で、機械を実際に使わせることが主張の中心なら Type B、実利用者を想定せず「この機械を作れたこと」自体が主張のポートフォリオなら Type A になる。組み込み型・ツールキット型・研究型はコードを書く前の設計段階で module-dev が決め、構造と配布形態を規定する。Type A/B/C は動くコードができてから repo-standardize が §1・§3 を使って判定する（コードがない段階では判定できない）。両者が食い違った場合は、先に決まり構造にまで反映されている本節側の型を優先し、Type A/B/C 側をそれに合わせて訂正する。

2. 構造

repo/
├── packages/ (or src/)   # 汎用部分。ドメイン語彙なし
│   └── <module>/
│       ├── cli.*         # モジュールごとに CLI 入口（デモと検証を兼ねる）
│       └── demo.tape     # VHS 台本（同梱してデモを再現可能に保つ）
├── tests/                # src をミラー配置
└── examples/<domain>/    # 適用例（架空・中立データのみ）

• 外部依存（DB・外部 API・変換サービス・時刻）は直接 import せず引数・factory で注入する。テストは fake で回す。
• 汎用部分は組み立て側（app）を import しない。一方向依存を守れば、後のレジストリ切り出しはディレクトリ移動程度で済む。
• MVP の完成条件（DoD）は「実利用者が1日使える」×「第三者が価値を 30 秒で理解できる」から逆算し、PLAN.md に列挙する。

境界の切り方

「ドメイン語彙」は、変数名・型名・設定キーに業界固有の用語がそのまま現れているかで見分ける。patientId や claim_status はドメイン語彙、itemId や state は一般語彙である。判断に迷うのは、一般語彙に見えて業界の慣習を前提にした名前（approvalWindow が特定業界の承認フローの日数を指している、等）で、こうした名前は呼び出し元の文脈まで読んで判断する。

汎用側に置くか固有側に置くか迷ったら、固有側に置く。汎用側に置いたものを後で固有側へ剥がすコストは高い（呼び出し元・テスト・ドキュメントを含めた再設計になる）一方、固有側にあるものを汎用側へ引き上げるコストは低い（実装を1つ動かしたまま関数を抽出するだけで済む）。この非対称性から、判断が確定するまでは固有側に留めておく。

モジュールを分けるのは、同じ抽象に対する実装が2つ以上そろってからにする。1つしか実装が無い抽象を先に切り出すと、抽出したインタフェースが実際の2つ目の使われ方に合わず、結局作り直すことになる。

3. デモ

• 常設 URL は作らない。モジュール = VHS GIF（.tape 同梱、vhs <tape> で再生成）、アプリ = 一発起動（docker compose up 等）+ 画面録画 GIF。
• 機密・エッジ・実データは映さない。データソースの再配布規約にも注意（数行の提示は de minimis）。
• 成績・実測値をデモで実績として語らない（中立パラメータのデモ結果は本番と無関係）。
• セットアップ手順は各言語の標準ツール（venv+pip / npm）を正とし、Nix は任意ショートカットとして触れるだけにする（Nix 外の利用者が大多数）。

4. 既存リポへのモジュール追加を判断する

新しいモジュールを既存リポに足すか、新しいリポを立てるかは、汎用部分の配布単位で判断する。既存リポと同じ配布単位（同じレジストリパッケージ・同じ clone リファレンス）で公開して困らないなら既存リポに足す。配布単位が変わる（例: 既存は npm パッケージ、新モジュールは別言語のツールキット）なら新しいリポを立てる。

既存リポの型に合わないモジュールを足したくなった場合は、足さない。研究型のリポにツールキット型のモジュールを足すと、リポの主張（問いと検証結果が本体）が崩れる。型が合わないモジュールは、そのモジュール単体で新しいリポとして独立させる。