kamae

Kamae — TypeScript による関数型ドメインモデリング

6 つのトピックファイルで原則を説明しています。現在のタスクに関連するファイルだけを読みます。result-libraries/ と validation-libraries/ のライブラリガイドは、プロジェクトの package.json に基づいて必要に応じて読み込みます。

Step 0: 適用するルールを読み込む

ほかの手順に進む前に、次の優先順位でルールを glob し、読み込みます。

1. .claude/rules/*.md（作業ツリーのルートにあるプロジェクトレベルの上書き）
2. ~/.claude/rules/*.md（ユーザー全体の設定）
3. この SKILL.md を基準とした ../../rules/defaults/*.md（プラグインのデフォルト）

各ファイルについて：

• YAML フロントマターを読みます。applies-to が kamae または * でなければ、そのルールをスキップします。
• name ごとにグループ化します。各 name について、最も優先順位の高い層のインスタンスだけを残します（1 > 2 > 3）。同じ層では、ファイル名の辞書順で最後のものを採用します。
• 残った各ルールの本文を、以降の手順全体に適用します。library-preference ルールは Step 1 の検出方法に優先し、convention ルールは生成コードの形式を定め、override ルールは特定のトピックファイルのガイダンスに置き換わります。

ルールが見つからない場合は、../../rules/defaults/ に記載されているプラグインのデフォルトを適用します。

ルールの形式については、../../rules/README.md を参照してください。

トピックガイドとライブラリガイドを適用する前に、同じパッケージ内の近くにあるファイルを確認し、確立された一貫性のあるコーディングスタイルとインポートスタイルを把握します。ローカルの規約がある場合はそれに従い、リポジトリ内で規約が定まっていない場合にのみ Kamae のガイドに従います。

Step 1: プロジェクトのライブラリを検出する

package.json を一度読みます。使用されている Result ライブラリとバリデーションライブラリを確認します。

• Result ライブラリ — 優先順位 neverthrow > byethrow > fp-ts > option-t に従い、最初に見つかったものを選びます。エラー処理が対象の場合は、result-libraries/ にある該当ガイドを読み込みます。
• バリデーションライブラリ — 優先順位 zod > valibot > arktype に従い、最初に見つかったものを選びます。境界処理またはブランド型が対象の場合は、validation-libraries/ にある該当ガイドを読み込みます。

いずれも見つからない場合は、先に進む前にユーザーに確認します。

Step 2: タスクに関連するトピックを適用する

以下の各トピックは、それぞれ 1 つのファイルで構成されています。必要なファイルだけを読み込んでください。

型駆動のドメインモデリング — domain-modeling.md

状態は、kind を統一された判別子とする判別共用体で表します。interface ではなく type を使い、コンパニオンオブジェクトパターン、プロジェクトのバリデーションライブラリを使ったブランド型、Readonly<>、関数プロパティ記法、および 1 ファイル 1 概念の構成を採用します。

読み取り契約（リゾルバー）と書き込み契約（ストア）を分け、各契約にはメソッドを 1 つだけ設けることを優先します。各コンシューマーには必要な操作だけを提供します。イベントストアにリゾルバーや CRUD リポジトリは必要ありません。I/O はワークフローの境界に置き、値を純粋なドメイン判断に渡します。

ドメインに関わるポートは、ドメイン層で、それらが担う概念の近くに配置します。domain/ 内も含め、専用の port/ または ports/ ディレクトリは導入しないでください。具体的な I/O アダプターはドメインの外に置きます。ユースケースとアダプターは、ドメインが所有する契約をインポートします。依存関係の契約を定義する場合や、そのファイルの配置を決める場合は、domain-modeling ガイドを読みます。

状態遷移 — state-modeling.md

遷移は純粋関数で表現します。引数の型で有効な遷移元の状態を制約し、戻り値の型で遷移先を明示します。無効な遷移はコンパイルエラーになります。網羅性の確認には assertNever を使います。

エラー処理 — error-handling.md

• 想定されるビジネス上の失敗は、ユースケース固有の Result エラーユニオンとしてモデル化します。
• 外部要因による失敗をドメインの Result エラーユニオンに含めるのは、そのワークフローに文書化された復旧判断がある場合に限ります。
• 想定外のインフラストラクチャ障害や、契約・不変条件への違反は、アプリケーションのエラー境界まで到達させます。ライブラリの契約を維持してください。fp-ts は TaskEither 内で実行失敗を別のチャネルとして扱い、ネイティブの Promise 境界では想定外の障害を再スローします。詳しくは fp-ts guide を参照してください。
• プライベートな制御フロー用センチネルは、それに対応する境界がそのセンチネルだけを捕捉し、ほかのすべてのエラーを再スローする場合に限り使用できます。

境界の防御 — boundary-defense.md

すべての外部入力（API リクエスト、DB の結果、ファイル／キュー／環境変数）を、実行時にスキーマで検証します。ドメイン内部では型を信頼します。型アサーションは使用しないでください。許可される形式は as const と as const satisfies Type のみです。型が不明な場合は、検証ライブラリのスキーマを通してパースしてください。PII フィールドには Sensitive<T> を適用します。検証スキーマが自動的にラップします。

実行時スキーマですでに境界表現が定義されている場合は、同じ形状を再定義するのではなく、そのスキーマから TypeScript の型を導出してください。

宣言的なスタイル — declarative-style.md

命令型のループの代わりに、対応するオブジェクトの述語とともに filter ／ map ／ reduce を使用します。ドメインイベントは不変レコードとしてモデル化します。

テストデータ — test-data.md

as const satisfies Type を使ってフィクスチャを定義し、判別子のリテラル型を保持して型が広がるのを防ぎます。

例

エンドツーエンドの具体例は examples/ にあります。トピックガイドで特定の例が参照されている場合にのみ読んでください。

これらの原則の適用

これらは推奨事項であり、厳格な規則ではありません。状況に応じて判断してください。原則から逸脱する場合は、コメントに理由を記載してください。正当な理由の例としては、外部ライブラリがクラス継承を必要とする場合、不変オブジェクトの作成コストが測定可能なパフォーマンス上の懸念となる場合、またはチームの合意により別のパターンが採用されている場合があります。