mapper-creator

事前確認：Spring MCP

このスキルはSpring Agent Toolkitの一部であり、（Amplicode IntelliJ プラグインが提供する）Spring MCP サーバーと連携するように設計されています。何かを始める前に、ツール一覧に Spring MCP ツールがあるか確認してください。これらのツールはamplicode MCP サーバーの下に公開されています（例：get_project_summary、list_module_dependencies、get_entity_details）。MCP ツールをツール一覧にフラット化するハーネスでは、同じ名前にmcp__amplicode__プレフィックスが付きます。

• Amplicode ツールが1つ以上ある場合 — MCP は接続されています。以下のスキルに進んでください。
• 1つもない場合 — 停止し、**amplicode-installスキル（Spring Agent Toolkit に同梱）を呼び出してください。このスキルは Amplicode プラグインをインストールし、ウェルカム画面の«Настроить Spring Agent»**ボタンの操作と MCP クライアントの再起動をユーザーに案内します。完了すると MCP ツールが利用可能になるため、このスキルを再開してください。
• スキル一覧にamplicode-installが登録されていない場合は、ユーザーの言語で次のように伝えてください。「このスキルには Amplicode IntelliJ プラグインとその MCP サーバーが必要です。https://amplicode.ru/marketplace から IntelliJ IDEA Ultimate/Community または GigaIDE にインストールし、任意のプロジェクトを開いて、Amplicode のウェルカム画面にある«Настроить Spring Agent»をクリックし、その後 MCP クライアントを再起動してください。」

---

マッパーの作成

エンティティと DTO の間で変換するマッパー（MapStruct インターフェース／抽象クラスまたはカスタムコンバーター）を作成します。

---

重要：コードは必ずexamples/ファイルのみを参照してください。一致する例がない場合は、停止してユーザーに確認してください。 重要：選択肢が固定された質問では、AskUserQuestion > その類似ツール > 通常のテキストリストの順に優先してください。番号付きの通常のテキストリストは、対話型ツールが利用できない場合の最後の手段です。 重要：Step 1を実行する前に、会話のコンテキストを確認してください。 Step 2～3の質問の半分は、ユーザーのプロンプトや前のやり取りですでに回答されている可能性があります。すでに伝えられた内容を再度質問することが、このスキルが遅く感じられる最大の原因です。

---

デフォルト

オプション	デフォルト	常に質問する？	備考
entity	—	はい	マッピングするエンティティ
dtoClass	—	はい	マッピング先の DTO
mapperType	MapStruct	はい	主な選択肢：MapStruct または Custom
className	{EntityName}Mapper	いいえ	提案して確認
packageName	DTO と同じパッケージ	いいえ	自動判定
parentInterface	null	いいえ	共通マッパーインターフェースを拡張
language	get_project_summaryから取得	いいえ	自動判定
componentModel	依存関係に Spring が含まれる場合は SPRING、それ以外は DEFAULT	いいえ	CDI は自動検出されません — ユーザーが明示的に指定する必要があります
partialUpdate	no	いいえ	partialUpdate メソッドを追加
partialUpdateNullStrategy	SET_TO_NULL	いいえ	partialUpdate = yes の場合：SET_TO_NULL / IGNORE / SET_TO_DEFAULT
updateWithNull	no	いいえ	updateWithNull メソッドを追加
dtoIsRecord	false	いいえ	DTO に Java record を使用するかどうか（Java のみ。カスタム toEntity のアクセサーに影響します）

スマートデフォルト： ユーザーが「デフォルトを使って」「すべてデフォルトで」「デフォルト設定」と言った場合、「常に質問する？」が「いいえ」の項目はすべて質問を省略します。必須項目のみ質問してください。

回答の自動認識： ユーザーが選択肢から選ぶのではなく、値を直接指定した場合は、その値を受け入れてください。例：

• 質問「どのエンティティですか？」-> ユーザーが「Order」と回答 -> それがエンティティです
• 質問「マッパーの種類は？」-> ユーザーが「mapstruct」と回答 -> それが選択内容です
• ユーザーが1つのメッセージで複数の回答を示した場合 -> すべて受け入れ、回答済みの質問は省略します
• ユーザーがすでに回答した内容を、間接的な回答であっても、絶対に再質問しないでください

質問のまとめ方： 関連する質問は1回のAskUserQuestion呼び出しにまとめてください（最大4問）。

• 主な質問（mapper type）は必ず単独で質問してください
• 異なる判断分岐の質問をまとめないでください
• AskUserQuestionを優先し、ツールが利用できない場合に限り通常のテキストに切り替えてください

---

ステップ 0 -- まず会話のコンテキストを確認する（必須、ツール呼び出しなし）

MCP を呼び出す前、質問をする前に、ユーザーのプロンプトとこの会話の前のやり取りを読み直し、すでに示されている情報を抽出してください。このステップにはコストがかからず、このスキルで最もよくある失敗、つまりユーザーがすでに伝えたことを尋ねてしまうのを防げます。

入力のチェックリストを頭の中で作成し、ユーザーがすでに明示的または暗黙的に提供している項目にチェックを付けてください。

入力	プロンプト／コンテキストで確認する内容
entity	クラス名（Order、Vet、ScheduleTemplate）、「X 用」、「X から Y へ」、IDE で開いているファイル、最近話題にしたエンティティ
DTO	Dto／Response／Request で終わるクラス名、「OrderDto へ」、「X から Y へ」、この会話内で dto-creator が直前に生成した DTO
mapperType	「MapStruct」、「mapstruct」、「@Mapper」、「custom」、「manually」、「static methods」、「extension function」→ MapStruct と Custom のどちらか
className	「OrderConverter という名前にする」、「クラス FooMapper」
package	「パッケージ … に」、「DTO と同じ場所に」、「コントローラーと同じ場所に」
methods	「toDto のみ」、「update 付き」、「部分更新」、「updateWithNull」
smart defaults	「デフォルトを使う」、「すべてデフォルト」、「デフォルト設定」、「いつもどおり」
prior project facts	言語、JDK、依存関係 — この会話の前のやり取りで話題にしていれば、すでに把握済みです。再取得しないでください
delegated invocation	dto-creator が直前にこのスキルへ処理を委任した場合、エンティティ、DTO、パッケージ、言語はすべて既知です — 決して聞き直さないでください

明示的または強く暗黙的に回答されている入力は、すべて決定済みとして扱い、ステップ 2～3 の該当する質問を省略してください。ユーザーが「Order から OrderDto へのマッパーを作成して」と書いている場合、「どのエンティティですか？」と尋ねないでください — エンティティと DTO の両方が示されています。ユーザーが「MapStruct のマッパーを作成して」と書いている場合、「MapStruct と Custom のどちらにしますか？」と尋ねないでください。

回答されていない入力については、以下の「意思決定の原則」に従ってください — まずプロジェクトのコンテキストから推測し（ステップ 1）、その後でのみ質問します。

ステップ 0 は頭の中で行うものであり、ツール呼び出しではありません。ユーザーに伝えないでください。「ステップ 0 完了」と書かないでください。ステップ 1 に進む前に、ユーザーがすでに伝えた内容を把握してください。

---

意思決定の原則 — まずコンテキストを確認し、その後で質問する

ユーザーに何かを質問する前に、すでに収集したコンテキストから回答を導き出してください。プロジェクト概要、モジュールの依存関係、エンティティの詳細、パッケージ内の既存ファイル、この会話の前のやり取り、ユーザーの元のプロンプトを確認します。コンテキストから明確なデフォルトを導けない場合、またはユーザーごとの選択が必要な場合（例：どのエンティティか、どの DTO か）に限り、質問してください。

意思決定の優先順位：

1. コンテキストが明確 → 無言で決定し、質問しないでください。 例：get_project_summary から言語とモジュールを特定する、list_module_dependencies から MapStruct の有無を特定する、DTO のパッケージからマッパーのパッケージを特定する、クラス名を {Entity}Mapper にする、Spring の有無から componentModel を決める、ユーザーが明示的に「MapStruct」または「Custom」と言っている場合に mapperType を決める。

2. コンテキストに強い根拠がある → 決定事項と代替案を 1 行で伝え、ユーザーが変更を希望する場合にのみ応答してもらいます。 形式：

   Will create `OrderMapper` (MapStruct, componentModel=spring, in the same package as `OrderDto`).
   Alternatives: Custom mapper. OK?
   

   ユーザーが「ok」／「yes」と答える、または何も答えない場合は、その選択を採用します。別の案を指定した場合は、それに切り替えます。

3. コンテキストから明確なデフォルトを導けない → AskUserQuestion（推奨）または同等の手段で、推奨オプションを先頭にし、(Recommended) を付けて質問します。 インタラクティブなツールが利用できない場合は、通常のテキストで質問します。

4. 重要な入力についてコンテキストがまったくない → そのまま質問します。 対象となるのは、どのエンティティか、どの DTO か（どちらも言及されていない場合）、ユーザーが何をしたいのかです。

質問の方法 — AskUserQuestion を優先する

質問が必要な場合は、回答本文に番号付きリストを書くよりも、AskUserQuestion ツール（またはその類似ツール）を優先してください。インタラクティブな選択ツールが利用できない場合に限り、通常のテキストで質問してください。

このスキルで AskUserQuestion を呼び出す際のルール：

• 1 回の呼び出しに、互いに独立した質問を最大 4 つ含められます（ツールはそれらをまとめて表示します）。これを利用して、関連する判断を 1 回のやり取りにまとめてください。
• 各質問には 2～4 個の選択肢を指定します。ツールは自由記述用の「その他」を自動で追加するため、手動では含めないでください。
• 推奨する選択肢は、ラベルの末尾に (Recommended) を付けて、最初に置いてください。
• header は 12 文字のチップラベルです（例：「Mapper」「Methods」「Package」）。
• 各選択肢には、その選択肢の意味を説明する description が必要です。

AskUserQuestion が適切なツールではない場合：

• 選択肢を列挙できない自由記述入力（例：任意のクラス名）は、通常のテキストで質問してください。
• 原則 2 の「確認を 1 行で尋ねる」形式は、列挙式の選択肢ではなく、単純な「はい／いいえ」の質問なので、通常のテキストを使ってください。

ステップ 2～3 にある画面操作を前提とした質問リストは、ケース 4 の代替手段です。上から順に実行する手順ではありません。原則 1～3 ですでに回答が決まっている質問は、スキップしてください。

---

ステップ 1 -- プロジェクトの最小限のコンテキストを収集する（自動、質問なし）

後続のステップで結果が実際に使用される MCP ツールのみを呼び出してください。「必要になるかもしれない」からといって事前に取得しないでください。ここで扱う各変数には、具体的な後続の用途が必要です。

ツール	抽出する内容	変数	用途
get_project_summary	言語、moduleName、buildFile	language、moduleName、buildFile	言語 → ステップ 4 の参照情報の選択（Java と Kotlin の判別）。moduleName → マルチモジュールの判別。buildFile → ステップ 5 の依存関係の追加
list_module_dependencies(moduleName)	アーティファクト ID	presentDeps	ステップ 5（MapStruct がすでに存在するか、追加が必要か）と、以下の componentModel の判断

ステップ 1 は以上です。以下は取得しないでください。

• Spring Boot のバージョン — これに基づく分岐はありません
• application.properties のパス — ステップ 5 ではプロパティファイルに何も書き込みません
• mainPackage — ステップ 4 では、プロジェクトのルートではなく DTO のパッケージからマッパーのパッケージを決定します
• get_entity_details / list_class_members — エンティティと DTO がわかってから取得するため、ステップ 2 に延期してください
• list_entity_mappers — MapStruct リファレンスのステップ 13（uses = {...} の解決）で、かつ関連エンティティごとにのみ必要です。対象となるエンティティは entityDetails を取得するまで不明なため、ステップ 13 まで延期し、ステップ 1 では事前取得しないでください。

マルチモジュールプロジェクト（get_project_summary に複数のモジュールが含まれる場合）の場合： 使用するモジュールを尋ねてください。その後、そのモジュールについて list_module_dependencies を再度呼び出してください。

componentModel — 簡略化

presentDeps に基づいて componentModel を決定します。

• Spring（いずれかの spring-boot-starter* または spring-context）→ SPRING
• それ以外 → DEFAULT

CDI は意図的に自動検出しません。CDI プロジェクトで componentModel = "cdi" を使用したい場合は、ユーザーが明示的に伝えます。スキルではデフォルトで CDI に基づく分岐を行わないでください。

---

ステップ 2 — エンティティと DTO

ステップ 0 でユーザーがエンティティと DTO に言及していれば、すでに把握しているはずです。よくあるケースは次のとおりです。

• ユーザーが「Order から OrderDto へのマッパーを作成して」と言った場合 → 両方把握できているため、質問は省略し、以下の並列取得に進みます。
• dto-creator から引き継いだ場合 → エンティティと DTO は、引き継ぎ元のスキルから渡されています。質問したり、改めて特定したりしないでください。
• ユーザーが「Order のマッパーを作成して」と言った場合 → エンティティは Order です。DTO は、この会話でそのエンティティについて最後に作成または話題にしたものです。複数の候補がある場合は、list_entity_dtos(orderFqn) を呼び出し、一意のものを選びます。複数の候補があり、ほかに判断材料がない場合に限り質問します。

コンテキストが本当にない場合に限り、質問してください。質問する際はプレーンテキストを優先してください（エンティティ名と DTO 名は自由入力のため、AskUserQuestion は適切なツールではありません）。

Which entity should I create a mapper for? And which DTO to map to?

エンティティ FQN と DTO FQN の両方が判明したら、次を並列で呼び出します。

ツール	変数	用途
get_entity_details(entityFqn)	entityDetails	ステップ 4 — @Mapping アノテーションの作成、および @AfterMapping 用に mappedBy を持つ非オーナー関連の検出
list_class_members(dtoFqn)	dtoFields	ステップ 4 — DTO フィールドとエンティティフィールドを比較し、必要な @Mapping(source, target) 行を判断

どちらの呼び出しもステップ 2 の入力が必要なため、ステップ 2 まで保留します。 ステップ 1 には含まれません。

---

ステップ 3 — マッパーの種類とバリアント設定

マッパーの種類 — まずコンテキストを確認

意思決定の原則を適用します。コンテキストから明らかな場合は、質問せずに判断してください。

コンテキストの手がかり	判断
ユーザーが「MapStruct」／「@Mapper」と言った	MapStruct。質問しません
ユーザーが「Custom」／「手動で」／「static メソッド」／「拡張関数」と言った	Custom。質問しません
presentDeps にすでに MapStruct があり、ユーザーから手がかりがない	MapStruct（原則 2 に従い、確認なし、または一行で確認）
presentDeps に MapStruct がなく、プロジェクトが小規模／シンプル	MapStruct も適切なデフォルトです。ステップ 5 で依存関係を追加します。一行の確認でその旨を伝えます。「MapStruct マッパーを作成します。ビルドファイルに依存関係を追加します。別の選択肢：依存関係のない Custom。よろしいですか？」
ユーザーが「デフォルトを使用して」と言った	MapStruct

上記のどの行にも当てはまらない場合に限り、AskUserQuestion を使用します。次の選択肢を指定してください。

質問	ヘッダー	選択肢（最初の選択肢を推奨）
{Entity} ↔ {Dto} のマッパーの種類は何にしますか？	Mapper	MapStruct（推奨）：@Mapper/@Mapping を使ったインターフェース / Custom：static メソッドを使った通常のクラス

バリアント設定 — 通常はデフォルトで問題ありません

MapStruct と Custom のどちらのバリアントでも、デフォルトはほぼ常に適切です。

• className = {EntityName}Mapper
• packageName = DTO と同じパッケージ
• partialUpdate = いいえ
• updateWithNull = いいえ

ユーザーが明示的に設定を求めた場合（「メソッドを設定して」「部分更新が必要」など）、またはデフォルトに反することを述べた場合を除き、これらの設定をまとめて質問しないでください。

設定を求められた場合は、該当する項目を選び、multiSelect: true を指定して、AskUserQuestion を一度だけ呼び出します。

質問	ヘッダー	選択肢（最初の選択肢を推奨）
マッパーにどのメソッドを追加しますか？	Methods	toDto + fromDto（推奨）：基本的な双方向変換 / + partialUpdate：DTO からエンティティを更新 / + updateWithNull：null で上書きする partialUpdate

クラス名とパッケージは自由入力です。ユーザーが「別の名前にしたい」または「別のパッケージにしたい」と言った場合に限り、プレーンテキストで質問してください。

---

ステップ 4 — コードの生成

マッパーの種類と言語に基づいて参照ファイルを決定します。

• MapStruct + Java → references/mapstruct-java.md を読みます
• MapStruct + Kotlin → references/mapstruct-kotlin.md を読みます
• Custom + Java → references/custom-java.md を読みます
• Custom + Kotlin → references/custom-kotlin.md を読みます

対応する参照ファイルを読み、Generation order に厳密に従います。

@Mapping アノテーションの構築

@Mapping アノテーションの構築方法については、references/mapping-annotations.md を読んでください。

entityDetails のエンティティフィールドと dtoFields の DTO フィールドを比較します。

1. DTO フィールドを名前でエンティティフィールドに対応付けます
2. 名前が異なるフィールドには、@Mapping(source, target) を追加します
3. 関連 ID フィールド（例：customerId → customer.id）には、適切なマッピングを追加します
4. フラットフィールド（例：customerName → customer.name）には、expression または source.target のマッピングを追加します

スケルトンとフラグメントの読み込み

1. examples/_skeletons/{variant}-{language}.md からスケルトンファイルを読みます
2. 変数を置換します
3. ファイルを書き込みます
4. 生成順の各フラグメントについて、次の手順を実行します。
   • フラグメントの条件を満たしているか確認します
   • examples/_fragments/{fragment-name}/{language}.md からフラグメントを読みます
   • 変数を置換します
   • 作成したファイルに挿入または編集します

変数置換ルール

• {packageName} → ステップ 1 のコンテキストまたはユーザーの回答から取得します
• {className} → ユーザーの回答、またはデフォルトの {EntityName}Mapper を使用します
• {entityClassFqn} → コンテキストからエンティティの FQN を取得します
• {dtoClassFqn} → コンテキストから DTO の FQN を取得します
• {entityParamName} → エンティティの短縮名の先頭を小文字にした名前です
• {dtoParamName} → DTO の短縮名の先頭を小文字にした名前です
• {methodName} → 命名規則から取得します（references/method-naming.md を参照）
• 例のファイルの Variables セクションに記載されていないものは、絶対に置換しないでください
• 例にない import、メソッド、コードを絶対に追加しないでください
• FQN の扱い（重要）： 例には FQN（例：org.mapstruct.Mapper、 org.mapstruct.Mapping、org.mapstruct.ReportingPolicy、 org.mapstruct.MappingConstants.ComponentModel.SPRING、エンティティ／DTO の FQN）が含まれています。最終ファイルを 書き込む際は、必ず次の手順を実行してください。
  1. 本文のすべての FQN を短縮名に置き換えます （例：@org.mapstruct.Mapper(...) → @Mapper(...)、 org.mapstruct.ReportingPolicy.IGNORE → ReportingPolicy.IGNORE、 {entityClassFqn} → エンティティの短縮名、{dtoClassFqn} → DTO の短縮名）。
  2. 短縮した FQN をすべて集め、対応する import 行を package 文の直後に、重複なしでソートして追加します。
  3. マッパーと同じパッケージのクラス（エンティティ、同じパッケージにある DTO）は import してはいけません。短縮名だけを使用します。
  4. java.lang の型は import してはいけません。
  5. Kotlin も同じルールです。本文では短縮名を使用し、先頭に import 行を追加します。 Kotlin では同じパッケージのクラスに import は不要です。
  6. IDE が import を最適化することはありません。ファイルはそのまま保存されます。

---

ステップ 5 — MapStruct の依存関係を追加（自動、MapStruct バリアントのみ）

Custom マッパーの場合、このステップ全体をスキップします。Custom マッパーには 外部依存関係がありません。

MapStruct の場合は、presentDeps を確認し、プロジェクトのビルドファイルに不足しているアーティファクトを追加します。

必須アーティファクト

アーティファクト ID	グループ ID	スコープ
mapstruct	org.mapstruct	implementation
mapstruct-processor	org.mapstruct	annotationProcessor（Java）／kapt または ksp（Kotlin）

どちらのアーティファクトも presentDeps に不足していない場合は、このステップの残りをスキップします。追加するものはありません。

ビルドファイルの編集方法

ステップ 1 で記録した buildFile のパスを使用してください。これは、スキルが編集しなければならない正確なファイルです。推測したり、プロジェクト内を検索してビルドファイルを探したりしないでください。

ファイル拡張子に応じて編集方法を選択してください。

• build.gradle.kts — 既存の dependencies { … } ブロック内に implementation("org.mapstruct:mapstruct:{version}") を追加します。プロセッサについては、次のとおりです。
  • Java プロジェクト → annotationProcessor("org.mapstruct:mapstruct-processor:{version}")
  • Kotlin プロジェクト → kapt("org.mapstruct:mapstruct-processor:{version}")（存在しない場合は kotlin("kapt") プラグインを適用します）。または、すでに KSP が設定されている場合は ksp(...)
• build.gradle（Groovy）— 上記と同様ですが、Groovy のシングルクォート構文を使用します
• pom.xml — <dependencies> 内に <dependency> エントリを追加し、役割に応じて <scope> を設定します（mapstruct には compile、プロセッサは maven-compiler-plugin の <annotationProcessorPaths> で設定します）

バージョンはハードコードしないでください。プロジェクトに既存のバージョンカタログ（例：gradle/libs.versions.toml）があれば、そこから最新の安定版 MapStruct バージョンを読み取ってください。ない場合は、Maven であれば Spring Boot BOM／プロジェクトの親 POM に一致するバージョンを使用してください。それ以外の場合は、プロパティ／変数のプレースホルダーを出力し、ユーザーに確認してください。

Edit ツールを使用し、{buildFile} を file_path に指定してください。編集は最小限にし、新しい行を既存の dependencies ブロックに挿入してください。ファイル全体を書き換えないでください。

プロパティは不要

Mapper の作成では、application.properties のエントリは追加しません。

次のように報告してください："Created mapper {className} in package {packageName}. Type: {mapperType}. Methods: {list of methods}."

---

幻覚を防ぐためのチェックリスト

コードを書く前に、次の項目を確認してください。

• コードの出典が examples/ 内のファイルである（どのファイルか明記する）
• 置換したのは、宣言済みの変数のみである
• フレームワークの API 呼び出しを「知識に基づいて」追加していない
• インポート一覧がサンプルと完全に一致している
• メソッドシグネチャがサンプルと完全に一致している
• コメントや利便性のためのメソッドを追加していない
• サンプル内の FQN を本体では短縮し、対応する import 行を package の後に追加している（IDE は自動で追加しません）
• @Mapping アノテーションが推測ではなく、エンティティと DTO のフィールド比較に一致している
• Kotlin：複数の @Mapping は @Mappings(value = [...]) で囲んでいる
• @AfterMapping は、マッピング対象のサブ DTO を持つ、mappedBy が設定された非所有側の関連がエンティティにある場合にのみ追加している
• デフォルトでは、toDto は個別の @Mapping(source, target) ペアを使用している。ユーザーから明示的に依頼された場合にのみ @InheritInverseConfiguration を使用する
• フラットなコレクション用ヘルパーは toDto 方向でのみ生成している。toEntity で ID によるエンティティの読み込みを試みない（リポジトリを注入しない）
• フラットなコレクション用ヘルパーの名前が {assocFieldName}To{capitalize(flatDtoFieldName)} の形式に従っている（例：petsToPetIds。petsToId ではない）