spring-planning

事前確認：Spring MCP

このスキルは Spring Agent Toolkit の一部であり、Spring MCP server（Amplicode IntelliJ プラグインが提供）と連携するように設計されています。ほかの作業を始める前に、ツール一覧に 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 クライアントを再起動してください。"

---

実装計画の作成

対話形式でコンテキストを収集し、docs/plans/yyyymmdd-<task-name>.md に実装計画を作成します。

ステップ 0：意図を把握してコンテキストを収集する

質問をする前に、ユーザーが取り組んでいる内容を把握します。

1. ユーザーのコマンド引数を解析して意図を特定します。

   • 「機能 Z を追加」／「W を実装」→ 機能開発
   • 「バグを修正」／「問題をデバッグ」→ バグ修正計画
   • 「X をリファクタリング」／「Y を改善」→ リファクタリング計画
   • 「Z に移行」／「W をアップグレード」→ 移行計画
   • 一般的な依頼 → 現在の作業を調査

2. 関連するコンテキストをすばやく収集します — Explore エージェントではなく、spring-explore スキルを直接使用してください。調査は30秒以内に収めます。

   重要：Explore エージェントを起動しないでください。目的は網羅的な分析ではなく、すばやく確認することです。さらにコンテキストが必要な場合は、ステップ 1 でユーザーに尋ねてください。

ステップ 1：コンテキストを提示し、的を絞った質問をする

見つかったコンテキストを示してから、AskUserQuestion ツールを使い、一度に1つずつ質問します。

「ご依頼に基づいて、次の内容が見つかりました：[コンテキストの概要]」

質問は一度に1つずつ行ってください（複数の質問を一度に提示して、ユーザーを困らせないでください）。

1. 計画の目的：AskUserQuestion を使用 — 「主な目標は何ですか？」

   • 見つかった意図に基づく回答候補を選択肢として提示します
   • 次の質問に進む前に回答を待ちます

2. 範囲：AskUserQuestion を使用 — 「どのコンポーネント／ファイルが関係しますか？」

   • 見つかったファイルや領域を候補として含む選択肢を提示します
   • 次の質問に進む前に回答を待ちます

3. 制約：AskUserQuestion を使用 — 「特定の要件や制限はありますか？」

   • 制約が多岐にわたる場合は自由回答形式にできます
   • 次の質問に進む前に回答を待ちます

4. テスト方法：AskUserQuestion を使用 — 「TDD、通常の進め方、テストなしのどれを希望しますか？」

   • 選択肢：「TDD（先にテスト）」、「通常（先にコードを書き、その後テスト）」、「なし（テストなし）」
   • 実装中に参照できるよう、希望を記録します
   • 次の質問に進む前に回答を待ちます

5. 計画のタイトル：AskUserQuestion を使用 — 「短く内容がわかるタイトルは何ですか？」

   • 意図に基づく名前を候補として提示します

すべての質問への回答を得たら、回答をまとめて計画のコンテキストを作成します。

ステップ 1.5：アプローチを検討する

問題を理解したら、実装アプローチを提案します。

1. トレードオフを含めて、2～3 種類のアプローチを提案します
2. 推奨する選択肢を最初に示し、その理由を説明します
3. 会話形式で提示します。まだ正式なドキュメントにはしません。

形式の例：

i see three approaches:

**Option A: [name]** (recommended)
- how it works: ...
- pros: ...
- cons: ...

**Option B: [name]**
- how it works: ...
- pros: ...
- cons: ...

which direction appeals to you?

AskUserQuestion ツールを使って、計画を作成する前にユーザーに希望するアプローチを選んでもらいます。

以下の場合はこのステップをスキップします。

• 実装アプローチが明白な場合（明確な方法が 1 つだけの場合）
• ユーザーが実装方法を明示的に指定している場合
• 明確な解決策があるバグ修正の場合

ステップ 2：計画ファイルを作成する

既存のファイルがないか docs/plans/ を確認してから、docs/plans/yyyymmdd-<task-name>.md を作成します（現在の日付を使用）。

計画の構成

# [Plan Title]

## Overview
- clear description of the feature/change being implemented
- problem it solves and key benefits
- how it integrates with existing system

## Context (from discovery)
- files/components involved: [list from step 0]
- related patterns found: [patterns discovered]
- dependencies identified: [dependencies]

## Development Approach
- **testing approach**: [TDD / Regular - from user preference in planning]
- complete each task fully before moving to the next
- make small, focused changes
- **CRITICAL: every task MUST include new/updated tests** for code changes in that task
    - tests are not optional - they are a required part of the checklist
    - write unit tests for new functions/methods
    - write unit tests for modified functions/methods
    - add new test cases for new code paths
    - update existing test cases if behavior changes
    - tests cover both success and error scenarios
- **CRITICAL: all tests must pass before starting next task** - no exceptions
- **CRITICAL: update this plan file when scope changes during implementation**
- run tests after each change
- maintain backward compatibility

## Testing Strategy
- **unit tests**: required for every task (see Development Approach above)
- **e2e tests**: if project has UI-based e2e tests (Playwright, Cypress, etc.):
    - UI changes → add/update e2e tests in same task as UI code
    - backend changes supporting UI → add/update e2e tests in same task
    - treat e2e tests with same rigor as unit tests (must pass before next task)
    - store e2e tests alongside unit tests (or in designated e2e directory)
    - example: if task implements new form field, add e2e test checking form submission

## Progress Tracking
- mark completed items with `[x]` immediately when done
- add newly discovered tasks with `[+]` prefix
- document issues/blockers with `[!]` prefix
- update plan if implementation deviates from original scope
- keep plan in sync with actual work done

## Solution Overview
- high-level approach and architecture chosen
- key design decisions and rationale
- how it fits into the existing system

## Technical Details
- data structures and changes
- parameters and formats
- processing flow

## What Goes Where
- **Implementation Steps** (`[ ]` checkboxes): tasks achievable within this codebase - code changes, tests, documentation updates
- **Post-Completion** (no checkboxes): items requiring external action - manual testing, changes in consuming projects, deployment configs, third-party verifications

## Implementation Steps



### Task 1: [specific name - what this task accomplishes]

**Files:**
- Create: `exact/path/to/new_file`
- Modify: `exact/path/to/existing`

- [ ] [specific action with file reference - code implementation]
- [ ] [specific action with file reference - code implementation]
- [ ] write tests for new/changed functionality (success cases)
- [ ] write tests for error/edge cases
- [ ] run tests - must pass before next task

### Task N-1: Verify acceptance criteria
- [ ] verify all requirements from Overview are implemented
- [ ] verify edge cases are handled
- [ ] run full test suite: `<project test command>`
- [ ] run e2e tests if project has them: `<project e2e test command>`
- [ ] verify test coverage meets project standard

### Task N: [Final] Update documentation
- [ ] update README.md if needed
- [ ] update CLAUDE.md if new patterns discovered
- [ ] move this plan to `docs/plans/completed/`

## Post-Completion
*Items requiring manual intervention or external systems - no checkboxes, informational only*

**Manual verification** (if applicable):
- manual UI/UX testing scenarios
- performance testing under load
- security review considerations

**External system updates** (if applicable):
- consuming projects that need updates after this library change
- configuration changes in deployment systems
- third-party service integrations to verify

ステップ 2.1：ドメインの永続化作業について計画を分析する

計画ファイルを作成したら、ドメインエンティティに関するタスクがないか確認します。該当するタスクがなければ、このステップは完全にスキップします。

エンティティ関連のタスクがある場合は、list_module_dependencies で永続化スタックを検出します。

検出された依存関係	スタック	有効にするスキル
spring-boot-starter-data-jpa / hibernate-core	JPA	spring-data-jpa
spring-boot-starter-data-jdbc / spring-data-jdbc	JDBC	spring-data-jdbc
いずれも該当しない	なし	このステップをスキップ

スタック（JPA または JDBC）が確定したら、次の手順を実行します。

1. 対応するスキルを有効にします。
2. スキルの環境設定手順に従います。
3. 計画に含まれるスタック固有の決定事項について、AskUserQuestion を使って 1 つずつユーザーに質問します。質問は焦点を絞ります（例：JPA の場合はフェッチタイプやカスケード、JDBC の場合は集約境界や @MappedCollection と AggregateReference のどちらを使うか）。
4. 回答をすべて収集したら、計画を修正します。
   • 関連するタスクにスタック固有の注意事項を追加します。
   • 各エンティティタスクに、次のリマインダーを追加します。"> スキルが必要です（）。 エンティティのコードを書く前にスキルを有効にし、実装がそのルールに従っていることを確認してください。ルールから逸脱する場合は、続行する前に開発者に確認してください。"
   • まだ含まれていない場合は、対応する DB マイグレーションタスクを追加します。

計画がドメインエンティティに関係しない場合、またはプロジェクトが JPA も JDBC も使用していない場合は、このステップを完全にスキップします。

ステップ 3：次のステップ

ファイルを作成したら、ユーザーに次のように伝えます。"計画を作成しました：docs/plans/yyyymmdd-<task-name>.md"

続いて AskUserQuestion を使います。

{
  "questions": [{
    "question": "Plan created. What's next?",
    "header": "Next step",
    "options": [
      {"label": "Interactive review", "description": "Open plan in IDE for review and feedback"},
      {"label": "Implement", "description": "Commit plan and start implementing"},
      {"label": "Done", "description": "Commit plan, no further action"}
    ],
    "multiSelect": false
  }]
}

• 対話形式でレビュー：mcp__ide__getDiagnostics を計画ファイルの uri（file:// を先頭に付けた絶対パス）とともに呼び出し、IDE で計画ファイルを開きます。これにより、IDE がそのファイルに移動します。その後、ユーザーに次のように伝えます。"計画を IDE で開きました。内容を確認して、変更したい点をお知らせください。" 会話でフィードバックを待ち、希望された変更を反映してから、同じ選択肢（「対話形式でレビュー」を除く）でもう一度質問します。
• 実装する：計画を「docs: add implementation plan」のようなメッセージでコミットしてから、このセッションでタスク 1 の実装を対話形式で開始します。進捗の追跡には TodoWrite ツールを使い、各 Todo はまとめてではなく、完了した時点ですぐに完了済みにします。
• 完了：計画を「docs: add implementation plan」のようなメッセージでコミットして、終了します。

実装の強制ルール

実装中のルール：

1. 次に進む前に、各タスクを完全に終わらせる：

   • 次のタスクに進む前に停止する
   • テスト方法が TDD または Regular の場合：新機能すべてのテストを追加／更新し、実行する
   • テスト方法が None の場合：実行中のアプリケーションで手動確認する
   • 完了した項目には、計画ファイルで [x] を付ける

2. テストを実施して失敗した場合：

   • 先に失敗を修正する
   • テストが失敗している状態で次のタスクに進まない

3. 実装中の計画の追跡：

   • タスクが完了したら、すぐにチェックボックスを更新する
   • 新たに見つかったタスクには [+] 接頭辞を付ける
   • ブロッカーには [!] 接頭辞を付ける
   • スコープが大きく変わった場合は、計画を変更する

4. 完了時：

   • 計画を docs/plans/completed/ に移動する
   • 必要に応じてディレクトリを作成する：mkdir -p docs/plans/completed

これにより、各タスクを確実に完了してから、その上に次の作業を積み重ねられます。

主な原則

• 一度に質問は1つだけ — 1つのメッセージで複数の質問をして、ユーザーを圧倒しない
• 選択肢を示す — 可能な場合は、自由回答よりも回答しやすい選択式を優先する
• DRY と YAGNI を徹底する — 不要な重複や機能を避け、スコープを最小限に保つ（ただし、結合度を下げられる場合は、早まった抽象化より重複を優先する）
• 推奨案から提示する — 明確な意見を持ち、理由を説明する。ただし、最終判断はユーザーに委ねる
• 代替案を検討する — 明白な場合を除き、決定する前に常に2〜3案を提示する
• 重複か抽象化か — コードが繰り返される場合は、重複（よりシンプルで、結合がない）と抽象化（DRY だが複雑さが増す）のどちらを優先するか、ユーザーに確認する。決定する前に、トレードオフを説明する