spring-explore

事前確認：Spring MCP

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

• Amplicode ツールが1つ以上利用可能な場合 — MCP は接続されています。以下のスキルを続行してください。
• 利用可能なツールがない場合 — 停止して 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 クライアントを再起動してください。"

---

アプリケーションを調査する

手順 0～6 でプロジェクトの基本的なコンテキストを収集します。各手順は順番に実行してください。 それぞれの手順は、前の手順の結果を踏まえて進みます。

重要： 現在の会話ですでにコンテキストを収集している場合は、調査を繰り返さず、既知の情報を使用してください。

---

手順 0 — ユーザーのリクエストから関連領域を予測する

ユーザーに次のように伝えてください：Step 0/6: Analyzing request...

この手順ではツールを呼び出さないでください。

ユーザーのリクエストを読み、実装に関係しそうな要素を推測してください。 ツールを呼び出さず、命名規則、ドメイン用語、一般的な Spring Boot のパターンに基づいて妥当な予測を立てます。

• エンティティ — どのようなドメインオブジェクトが関係しそうですか？（例：「注文を作成する」→ Order、OrderItem）
• リポジトリ — それらのエンティティに、どのリポジトリが存在しそうですか？
• サービス — どのサービスクラスが必要になりそうですか？
• コントローラー — この領域を扱う REST コントローラーはどれですか？
• その他の Bean／コンポーネント — マッパー、バリデーター、イベントリスナー、設定など。
• ファイル — 関連しそうな Java 以外のファイルは何ですか？（例：DB マイグレーションスクリプト、application.properties、Liquibase の変更履歴、HTML テンプレート）。ここに Java クラスを挙げないでください。Java クラスは上記のカテゴリに含めます。

本当に必要なものだけを含む、暫定的な不足項目リストを作成してください。

### Predicted involvement:
- Entities: Order, OrderItem, Customer
- Repositories: OrderRepository, CustomerRepository
- Services: OrderService
- Controllers: OrderController
- Other: OrderMapper
- Files: src/main/resources/db/migration/V1__create_orders.sql, application.properties

この予測を手順 1～5 で使用し、タスクに関係のない項目は調査を省略してください。

---

手順 1 — 調査の目的を定め、調査対象のパスを選択する

ユーザーに次のように伝えてください：Step 1/6: Selecting exploration paths...

この手順ではツールを呼び出さないでください。

現在の会話のコンテキスト（ユーザーのリクエスト、これまでの調査結果、残っている不足項目）を読み、調査の主要な目的を1文でまとめてください。ユーザーにその文を提示してください。

### Exploration goal:
Understand the Order aggregate structure and verify what repositories and mappers already exist.

この目的に基づいて、以下の各調査パスについて、含めるか省略するかを明示し、1行で理由を示してください。すべてのパスについて判断し、評価そのものを省略しないでください。 プロジェクト構成

• プロジェクトの概要を取得 — 技術スタック、Spring Boot のバージョン、またはモジュール構成が必要な場合に含めます。特定のクラスに限定されたタスクの場合は省略します。
• 永続化スタックを特定 — 以下のエンティティに関わるパスを選択しており、会話の中でスタック（JPA と JDBC）がまだ判明していない場合に含めます。list_module_dependencies を呼び出します。spring-boot-starter-data-jpa／hibernate への依存関係がある場合は JPA、spring-boot-starter-data-jdbc／spring-data-jdbc への依存関係がある場合は JDBC です。どちらもない場合は、サポート対象の永続化レイヤーがないため、エンティティに関わるパスを省略します。
• ドメインエンティティを一覧表示 — ドメイン領域がまったく不明で、関係するエンティティを予測できない場合にのみ含めます。リクエストですでにエンティティが指定されている場合や、文脈から予測できる場合は省略します。エンティティ構造の取得や FQN の特定には使用しないでください。
• REST エンドポイントを一覧表示 — 重複を避けるため、既存のエンドポイントを確認する必要がある場合や、規約を把握する必要がある場合にのみ含めます。リクエストですべてのエンドポイントが一から定義されている場合は省略します。

ドメインモデル

• エンティティの説明を取得 — エンティティのフィールドやアノテーションが必要な場合に含めます。すべてのエンティティではなく、予測したエンティティにのみ適用します。スタックに応じて使い分けます。JPA の場合は get_entity_details を使用し、references/entity-description.md を参照します。JDBC の場合は get_jdbc_entity_details を使用し、references/entity-description-jdbc.md を参照します。
• エンティティから詳細なモデルを取得 — 複数のエンティティにまたがる関係をたどる必要がある場合（ネストされたリソースやカスケードなど）に含めます。JPA のみです。JDBC では get_jdbc_entity_details が所有する子のツリー（aggregates）と逆方向のリンク（referencedBy）をすでに返すため、代わりに以下の DDD パスを使用します。references/deep-model-based-on-jpa.md を参照してください。
• エンティティから DDD モデルを取得 — 集約境界が重要な場合（URL 設計、カスケード計画、DTO の構成など）に含めます。JPA の場合は references/ddd-model-based-on-jpa.md に従います。JDBC の場合は get_jdbc_entity_details を呼び出し、aggregateRootFqn、aggregates、referencedBy を直接確認します。Spring Data JDBC はフレームワークレベルで集約境界を適用します。

永続化

• エンティティのリポジトリを取得 — 予測したエンティティのリポジトリが不明な場合や、確認が必要な場合に含めます。references/entity-repositories.md を参照してください。
• エンティティのコンポーネントを取得 — エンティティに関連するすべてのコンポーネント（リポジトリ、サービス、コントローラー）を把握する必要がある場合に含めます。references/entity-components.md を参照してください。

サービス

• エンティティのサービスを取得 — 予測したエンティティのサービスが不明な場合や、確認が必要な場合に含めます。references/entity-services.md を参照してください。

マッパー

• エンティティのマッパーを取得 — タスクに DTO が関係し、既存のマッパーを把握する必要がある場合に含めます。references/entity-mappers.md を参照してください。

DTO

• エンティティの DTO を取得 — 既存の DTO クラスを把握する必要がある場合に含めます。references/entity-dtos.md を参照してください。

REST レイヤー

• エンティティのコントローラーを取得 — エンティティに関連付けられたコントローラーを特定する必要がある場合に含めます。references/entity-controllers.md を参照してください。

評価内容を明示してから、含めたパスのみを使って最終的な計画を作成してください。

例 — 「顧客の注文と注文品目、商品名をすべて返すページネーション対応のエンドポイントを追加する」というリクエストの場合：

### Path evaluation:
- Fetch project summary: INCLUDE — need Spring Boot version and module structure
- Detect persistence stack: INCLUDE — entity-touching paths selected and stack unknown from conversation
- List domain entities: SKIP — Order, Customer, OrderItem, Product are predictable from the request
- List REST endpoints: INCLUDE — need to check if an orders endpoint already exists
- Get entity description: INCLUDE — need Order, OrderItem, Product fields for response DTO design
- Get deep model: SKIP — relationship structure is clear: Order → OrderItem → Product
- Get DDD model: SKIP — no cascade planning needed, just a read endpoint
- Get entity repositories: INCLUDE — need to verify OrderRepository exists and supports pagination
- Get entity components: SKIP — repositories are sufficient, no need for full component chain
- Get entity services: SKIP — no service layer changes expected
- Get entity mappers: INCLUDE — need to know if OrderMapper already exists before creating DTOs
- Get entity DTOs: INCLUDE — need to know if OrderDto already exists
- Get entity controllers: SKIP — will check via "List REST endpoints" instead

### Exploration plan:
1. Fetch project summary
2. Detect persistence stack
3. List REST endpoints (filter to order-related controllers)
4. Get entity description for Order, OrderItem, Product
5. Get entity repositories for Order
6. Get entity mappers for Order
7. Get entity DTOs for Order

---

ステップ 2 — 参照資料を読み込む

ユーザーに次のように伝えます：Step 2/6: Loading relevant references...

このステップではツールを呼び出さないでください。

ステップ 1 の調査計画に基づき、選択したパスに必要で、この会話ですでに読み込まれていない参照資料のみを読み込みます。 読み込み後は、ステップ 3 に直接進みます。ファイルの検索や glob、プロジェクト構造の手動調査は行わないでください。プロジェクトに関する情報はすべて、ステップ 3〜5 で MCP ツールのみを使って取得してください。

選択したパス	読み込む参照資料
エンティティの説明を取得（JPA）	references/entity-description.md
エンティティの説明を取得（JDBC）	references/entity-description-jdbc.md
エンティティから詳細モデルを取得	references/deep-model-based-on-jpa.md
エンティティから DDD モデルを取得	references/ddd-model-based-on-jpa.md
エンティティのリポジトリを取得	references/entity-repositories.md
エンティティのコンポーネントを取得	references/entity-components.md
エンティティのサービスを取得	references/entity-services.md
エンティティのマッパーを取得	references/entity-mappers.md
エンティティの DTO を取得	references/entity-dtos.md
エンティティのコントローラーを取得	references/entity-controllers.md

参照資料を必要とするパスがない場合は、このステップをスキップしてステップ 3 に進みます。

---

ステップ 3 — 統合調査計画を作成する

ユーザーに次のように伝えます：Step 3/6: Building exploration plan...

このステップではツールを呼び出さないでください。

ステップ 1 で選択したパスと、読み込んだ参照資料に記載された手順に基づいて、ステップ 4〜5 で実行する MCP 呼び出しを、単一の番号付き計画として作成します。 各項目には、カテゴリ名ではなく、具体的な MCP ツール呼び出しを記載します。

### Unified exploration plan:
1. get_project_summary
2. list_project_endpoints
3. list_all_domain_entities (regexPattern=Owner) — resolve FQN
4. get_entity_details (Owner FQN)
5. get_entity_details (Pet FQN)
6. get_entity_details (Visit FQN)
7. list_entity_repositories (Owner FQN)
8. list_entity_repositories (Pet FQN)
9. list_entity_repositories (Visit FQN)

---

ステップ 4 — サブエージェント経由で調査計画を実行する

ユーザーに次のように伝えます：Step 4/6: Executing exploration plan...

サブエージェントを起動し、次の指示を渡します。

Execute the exploration plan below by calling each MCP tool in order.
Use MCP tools directly (e.g. get_entity_details, list_entity_repositories).

Collect and return ALL results in full — do not summarize or truncate.

Secret redaction: if any returned value belongs to a key that looks like a credential
(`password`, `passwd`, `secret`, `token`, `api-key`, `apikey`, `access-key`, `private-key`,
`credentials`, `client-secret`, `auth`, or similar), replace only the value with `[REDACTED]`
and keep the key and surrounding structure intact. Never echo credential values verbatim.

Plan:
<paste the numbered plan from step 3 here>

サブエージェントの完了を待ち、先に進む前にすべての結果を収集します。

---

ステップ 5 — 調査レポートを作成する

ユーザーに次のように伝えます：Step 5/6: Building exploration report...

このステップではツールを呼び出さず、サブエージェントの結果だけを基に推論してください。

すべての調査サイクルで収集した調査結果をまとめ、単一のレポートを作成します。タスクにとって本当に価値のある情報のみを含め、ノイズや自明なデフォルトは省きます。

構成：

### Exploration Report

**Stack:** Java 21 · Spring Boot 3.x · Maven
**Persistence:** JPA   

**Domain model:**
- Order (id, status, totalAmount) → has many OrderItem → references Product
- Customer (id, name, email)

**Repositories:**
- OrderRepository — extends JpaRepository, supports pagination
- CustomerRepository — extends JpaRepository

**Services:**
- OrderService — handles order creation and status transitions

**Mappers:**
- OrderMapper (MapStruct) — maps Order ↔ OrderDto

**DTOs:**
- OrderDto, OrderItemDto — already exist

**REST API (relevant endpoints):**
- GET /orders — paginated list
- POST /orders — create order

**Notable findings:**
- SecurityConfig present — all endpoints require authentication
- No mapper for Customer — will need to create one

---

ステップ 5.5 — 暗黙の前提を明確にする

ユーザーに次のように伝えます：Step 5.5/6: Formulating implicit assumptions...

このステップではツールを呼び出さないでください。サブエージェントの結果とユーザーのリクエストだけをもとに推論してください。

調査レポートとユーザーのリクエストをもとに、ユーザーが明示していないものの、実装にあたって期待している可能性が高い内容をすべて特定します。これらは、明言されていない要件、規約、設計上の決定事項で、ユーザーが当然のこととして想定している可能性があります。

次の点に注目してください：

• 動作に関する期待 — 例：「ユーザーは完全削除ではなく論理削除を期待している可能性が高い」「ページネーションはオフセット方式を想定している」
• セキュリティ／アクセス制御 — 例：「このプロジェクトの他のすべてのエンドポイントと同様に、このエンドポイントにも認証が必要と考えられる」
• バリデーション — 例：「メールアドレスや価格などのフィールドにはバリデーションが期待されている可能性が高い」
• エラー処理 — 例：「対象エンティティが見つからない場合は、500 ではなく 404 を返すことが期待されている可能性が高い」
• 規約 — 例：「レスポンス形式は、既存のエンドポイントと同じ形式（キャメルケース、data フィールドでラップ）であることが期待されている可能性が高い」
• 関連する副作用 — 例：「注文の作成時には、在庫の更新や通知の送信も期待されている可能性が高い」
• DTO の形状 — 例：「レスポンスには ID だけでなく、ネストされた項目も含まれることが期待されている可能性が高い」

検証または修正できるよう、すべての前提を明示的に出力します：

### Implicit assumptions:
1. The new endpoint should require authentication — all existing endpoints use SecurityConfig with auth required.
2. Response format should match existing endpoints — camelCase JSON, no wrapper object.
3. Pagination is expected to be offset-based (Pageable) — consistent with other list endpoints.
4. Missing entity should return 404, not 500 — standard REST convention followed elsewhere.
5. Price field is expected to be validated as positive — consistent with other monetary fields in the domain.
6. OrderItem list in response should include product name and quantity — implied by "order details" framing.

暗黙の前提が特定できない場合は、その旨を明示します：

### Implicit assumptions: none identified — the request is fully specified.

---

ステップ 6 — 次のサイクルに進むか判断する

ユーザーに次のように伝えます：Step 6/6: Evaluating next cycle...

このステップではツールを呼び出さないでください。サブエージェントの結果だけをもとに推論してください。

追加サイクルの価値を 0〜100 で予測します。残っているギャップがどれほど重大か、また MCP を通じて解決可能かを示します。スコアと理由を提示してください：

### Additional cycle value: 87/100 → additional exploration cycle required.

スコアが 80 を超える — ステップ 1に進みます。スコアが 80 以下 — 停止します。