spring-data-jdbc

検出ガード

このスキルのルールを適用する前に、対象ファイルが org.springframework.data.relational.core.mapping / org.springframework.data.annotation からインポートしていることを確認してください。jakarta.persistence.* のインポートが見つかった場合は、そこで中止して spring-data-jpa スキルに切り替えてください。この2つのスタックは互換性がなく、JPA のパターン（HibernateProxy、@ManyToOne、@OneToMany、@JoinColumn、FetchType）はここでは適用できません。

ハーネスの互換性

このスキルは、複数のエージェント実行環境（Claude Code、Codex、OpenCode）で動作するように設計されています。このスキルでは、ハーネス固有のプリミティブを2つ名前で参照しています。これらは優先的に使用しますが、必須ではないため、利用できない場合は適切に代替してください。

• AskUserQuestion（Claude Code の選択肢付き構造化プロンプト）。実行環境が対応している場合は、すべての規約ファイルのステップ1.4で使用してください。それらのファイルにある JSON の例は、このツールが想定するペイロードに対応しています。実行環境が対応していない場合（Codex、OpenCode、通常の CLI）は、会話内でまったく同じ質問をしてください。各質問は短い段落で提示し、その後に番号付きまたは箇条書きの選択肢を並べ、推奨する選択肢には (Recommended) を付けてください。ユーザーの回答では、選択肢のラベルまたは番号のどちらも受け付けてください。判断の流れは同じで、変わるのは提示方法だけです。
• 「Memory」 — Claude Code の永続的なファイルベースの自動メモリーです。「以前に保存した規約についてメモリーを確認する」などの記述は、Claude Code の自動メモリーを利用できる場合は、まずそこを確認するという意味です。Codex/OpenCode（および永続メモリーがない実行環境）では、「この会話の前のターンを確認する」に置き換えてください。同じセッション内ですでに規約が決まっている場合はそれを再利用し、セッションが新しい場合はステップ1を最初から実行してください。

これらのプリミティブがないことを理由に、タスクを拒否しないでください。インラインで代替し、タスク開始時に一度だけ代替を伝えてください（「この実行環境では AskUserQuestion を利用できません。インラインで質問します」／「この実行環境には永続メモリーがありません。規約を最初から検出します」）。

---

事前確認：Spring MCP

このスキルは Spring Agent Toolkit の一部で、Spring MCP サーバー（Amplicode IntelliJ プラグインが提供）と連携するように設計されています。他の作業を始める前に、ツール一覧に Spring MCP ツールがあるか確認してください。これらは amplicode MCP サーバー配下に公開されています（例：get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories）。MCP ツールがツール一覧に統合されるハーネスでは、同じ名前の先頭に mcp__amplicode__ が付きます。

• Amplicode ツールが1つ以上利用できる場合 — MCP は接続されています。以下のスキルに進んでください。
• 利用できるものがない場合 — 中止して amplicode-install スキル（Spring Agent Toolkit に同梱）を呼び出してください。このスキルは Amplicode プラグインをインストールし、ウェルカム画面の «Настроить Spring Agent» ボタンを使った設定と、MCP クライアントの再起動をユーザーに案内します。完了すると MCP ツールが利用可能になるため、このスキルを再開してください。
• amplicode-install がスキル一覧に登録されていない場合、またはユーザーがインストールを断った場合（たとえば、CI サンドボックスなど MCP に対応していないハーネスを使用している場合）は、次のセクションで説明するファイル読み取りの代替手段を使って、タスクが進行できるようにしてください。

---

MCP の利用可能性とフォールバック

このスキルでは、Spring MCP ツール（get_jdbc_entity_details、list_all_domain_entities、list_entity_repositories）を優先します。これらのツールは、プロジェクト全体を解決した回答を 1 回の呼び出しで返すためです。Spring MCP サーバーに接続できず（接続エラー、ツールが登録されていない、MCP をサポートしていないハーネスなど）、かつユーザーが上記の Preflight でプラグインをインストールしないことを選択している場合は、タスクを拒否せず、ファイルの直接読み込み／grep にフォールバックしてください。

このプロジェクトは Kotlin を優先しています（主に Kotlin 2.2.20、一部のモジュールでは Java）—フォールバックでの grep は必ず *.kt と *.java の両方を対象にしてください。rg に -t java を渡さないでください。型フィルターを省略するか、-t kotlin -t java を使ってください。

• list_all_domain_entities の代わりに、プロジェクトを検索し、org.springframework.data.relational.core.mapping.Table のインポート（または、そのインポート先が当該パッケージである @Table アノテーション）を探して、JDBC エンティティを列挙します。.java と .kt のどちらでも同じように機能します。
• list_entity_repositories の代わりに、リポジトリ宣言のキーワード（Java では extends、Kotlin では :。Kotlin ではコロンの前にスペースがない場合があるため、\s* を使います）を検索します。省略可能な接頭辞に頼らず、すべての基底インターフェースを明示してください — (List)?(...|...) は人間が読むと曖昧に解析されます。

  (extends|:)\s*(ListCrudRepository|CrudRepository|ListPagingAndSortingRepository|PagingAndSortingRepository)\b
  

• get_jdbc_entity_details の代わりに、references/aggregate-rules-impl.md の「Without get_jdbc_entity_details」のサブセクションを参照してください。そこに記載されている手順では、Java と Kotlin の両方のソースファイルを読むことで、idField.type／aggregateRootFqn／aggregates／referencedBy と同じ情報を得られます。

タスクの開始時に、フォールバックモードで作業することと、その理由を 1 回明示してください（例：「Spring MCP に接続できないため、ファイル読み込みにフォールバックします」）。黙って切り替えないでください。

JDBC エンティティの操作

Spring Data JDBC エンティティの作成または変更を伴うタスクの場合：

1. この会話でエンティティの規約がまだ検出されていない場合は、まず以前に保存された規約がメモリーにあるか確認してください（永続メモリーのないランタイムでは、前の会話ターンを確認してください。「Harness compatibility」を参照）。見つかった場合は再利用してください。見つからない場合は、references/entity-conventions.md を読み、そこにあるすべてのサブステップに従ってプロジェクトの規約を検出してください。
2. エンティティの作成または変更にあたっては、references/entity-rules-impl.md を読み、そこに記載されたルールに従ってください。
3. エンティティ間、または既存のエンティティとの間に 何らかの関係 がある場合 — コレクションフィールド、参照フィールド、FK カラム、またはユーザーのリクエストに記述された関係（「X は Y に属する」「Y は複数の X を持つ」） — いずれかのリンクの形を決定する前に、references/aggregate-rules-impl.md も読んでください。エンティティのルールではフィールドの構文を扱い、集約のルールでは、どの関係の形が許されるか、またどの方向にリンクを保持できるかを決定します。この手順を省略すると、許可されない形（別の集約のメンバーへの生の FK、ルート以外への参照）が生成されます。

ツールとソースの使い分け — エンティティを編集する場合は、ソースファイルを直接読んでください。get_jdbc_entity_details は読み取り専用の分析ツールとして説明されており、「その後エンティティクラスを変更する予定がある場合は、代わりにファイルを直接読んでください」と明記されています。MCP ツールは、1 つのファイルからは確認できない集約間のコンテキストに限って使用してください。

• 集約内での対象の役割（aggregateRootFqn）。
• ここを参照している他の集約（referencedBy）。
• AggregateReference<Other, IdType> を介してリンクする必要がある別の集約の ID 型（Other のソースを読むのが過剰な場合）。

編集するファイル内のすべての情報 — ID 型、現在のフィールド、現在の @MappedCollection／@Embedded 宣言 — は、ファイルを読んで確認してください。

JDBC パターンのレビュー

ユーザーから、プロジェクト内の JDBC パターン、規約、またはコード品質のレビューを依頼された場合：

1. references/entity-conventions.md（手順 1.1～1.5）に従って、現在の規約を検出します。
2. 検出した規約を references/entity-rules-impl.md に定められたベストプラクティスと比較します。逸脱がある場合は、それぞれ次の形式で推奨事項を出力します。

### JDBC Review

**[Convention or pattern name]**
- Current: <what the project does>
- Recommended: <what the best practice says>
- Reason: <why this matters>

逸脱が見つからない場合は、プロジェクトがベストプラクティスに従っていると伝えます。

---

JDBC リポジトリの操作

Spring Data JDBC リポジトリの追加または変更を伴うタスクの場合：

1. この会話でリポジトリの規約がまだ検出されていない場合は、まずメモリ（または以前の会話ターン。「ハーネスとの互換性」を参照）を確認します。それ以外の場合は、references/repository-conventions.md を読み、そこにあるすべてのサブステップに従います。
2. references/repository-rules-impl.md を読み、そこにあるルールに従います。

新しいリポジトリを作成する前に、entityFqn = <target> を指定して list_entity_repositories を呼び出し、このエンティティのリポジトリがすでに存在しないことを確認します。また、対象に対して get_jdbc_entity_details を呼び出します。リポジトリを作成できるのは集約ルートのみです（aggregateRootFqn == null）。list_entity_repositories には JDBC フィルターがないため、entityFqn を指定せずに呼び出した場合は、結果を手動でフィルターしてください。

---

集約の操作

集約境界に関わるタスク（AggregateReference フィールドの追加、所有する @MappedCollection の集約間リンクへの変換、集約の分割、エンティティ間のあらゆる関係（1 対多、多対多を含む）の作成、「X を参照しているのは誰か？」「集約 Y の中には何があるか？」への回答など）の場合：

1. 必須： references/aggregate-rules-impl.md を最初に読み、対象の関係タイプに適用されるルールを確認します。適用されるルールを確認するまでは、エンティティの変更に進まないでください。
2. この会話で集約規約がまだ検出されていない場合は、まずメモリ（または以前の会話ターン。「ハーネスとの互換性」を参照）を確認します。それ以外の場合は、references/aggregate-conventions.md を読み、そこにあるすべてのサブステップに従います。
3. 両方の参照ファイルを読んでから、エンティティの変更に進みます。そこにあるルールに厳密に従ってください。

MCP ツール get_jdbc_entity_details は、集約への所属に関する信頼できる情報源です。その応答には、aggregateRootFqn（このエンティティ自体がルートの場合は null）、aggregates（所有する子エンティティ。再帰的で、ルートに対してのみ値が設定されます）、および referencedBy（AggregateReference を介してこのエンティティにリンクする他の集約）が含まれます。集約境界について判断する前に、これらを確認してください。

---

重要：1 対多および多対多の関係

**異なる集約間の1対多または多対多の関係には、必ずリンクエンティティが必要です。**これは必須です。このような関係を実装する前に：

1. get_jdbc_entity_details（またはエンティティの確認）により、両方の要素が集約ルートであることを確認するか、それぞれの集約への所属を確認します。
2. 両者が異なる集約に属する場合は、必ず中間リンクエンティティを作成してください。別のルートを指す直接の @MappedCollection は使用しないでください。
3. references/aggregate-rules-impl.md の該当するルールを読みます。「Rule: One-to-many between two aggregates goes through a link entity」または「Rule: Many-to-many between two aggregates goes through a link entity」のセクションを参照してください。
4. ドキュメントに記載されたリンクエンティティのパターンに厳密に従います。所有側は @MappedCollection を介してリンクコレクションを所有し、各リンクエンティティは対象ルートへの AggregateReference<Target, IdType> を保持します。