spring-planning

Preflight：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 工具可用——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 客户端。”

---

创建实施计划

通过交互式上下文收集，在 docs/plans/yyyymmdd-<task-name>.md 中创建实施计划。

步骤 0：理解意图并收集上下文

提问前，先了解用户正在处理的内容：

1. 解析用户的命令参数以确定意图：

   • “添加功能 Z”／“实现 W” → 功能开发
   • “修复 Bug”／“调试问题” → Bug 修复计划
   • “重构 X”／“改进 Y” → 重构计划
   • “迁移到 Z”／“升级 W” → 迁移计划
   • 通用请求 → 探索当前工作

2. 快速收集相关上下文——使用直接的 spring-explore 技能，而不是 Explore Agent。将探索时间控制在 30 秒以内：

   重要：不要启动 Explore Agent。目标是快速浏览，而非详尽分析。如果需要更多上下文，请在步骤 1 中询问用户。

步骤 1：展示上下文并提出有针对性的问题

展示已发现的上下文，然后使用 AskUserQuestion 工具一次提出一个问题：

“根据你的请求，我发现：[上下文摘要]”

一次只问一个问题（不要一次提出多个问题）：

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 工具，让用户在创建计划前选择偏好的方案。

以下情况跳过此步骤：

• 实现方案显而易见（只有一条明确路径）
• 用户明确指定了实现方式
• 这是一个解决方案明确的 bug 修复

步骤 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 一次询问一个问题，针对计划所涉及的特定技术栈决策向用户提出具体问题（例如，JPA：获取类型、级联；JDBC：聚合边界、@MappedCollection 与 AggregateReference）
4. 收集完所有回答后，修改计划：
   • 在相关任务中添加特定于技术栈的说明
   • 在每个实体任务中添加提醒："> 需要使用 技能（）。 编写任何实体代码前：激活该技能，并确认实现遵循其规则。如需偏离规则，请先询问开发者，再继续。"
   • 如果尚未包含相应的数据库迁移任务，则添加该任务

**如果计划不涉及领域实体，或项目既未使用 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 打开 IDE 中的计划文件，并传入该文件的 uri（以 file:// 为前缀的绝对路径）。这会让 IDE 跳转到该文件。然后告知用户："计划已在 IDE 中打开，请审阅并告诉我需要修改的内容。"等待用户在对话中反馈，按要求修改后，使用相同选项再次询问（去掉“交互式审阅”）。
• 实现：使用类似 "docs: add implementation plan" 的消息提交计划，然后在本次会话中交互式地开始实现任务 1。使用 TodoWrite 工具跟踪进度，并立即将已完成的待办事项标记为完成（不要批量处理）。
• 完成：使用类似 "docs: add implementation plan" 的消息提交计划，然后停止

执行约束

实施期间的规则：

1. 完成每项任务后再开始下一项：

   • 开始下一项任务前先暂停
   • 如果测试方式是 TDD 或常规测试：为所有新功能添加或更新测试，并运行测试
   • 如果测试方式为无：通过正在运行的应用进行手动验证
   • 在计划文件中将已完成的项目标记为 [x]

2. 如果使用了测试且测试失败：

   • 继续之前先修复失败项
   • 测试未通过时，不要开始下一项任务

3. 实施期间跟踪计划：

   • 任务完成后立即更新复选框
   • 为新发现的任务添加 [+] 前缀
   • 为阻塞项添加 [!] 前缀
   • 如果范围发生重大变化，则修改计划

4. 完成后：

   • 将计划移至 docs/plans/completed/
   • 如有需要，创建目录：mkdir -p docs/plans/completed

这样可以确保每项任务都经过充分落实，再以此为基础开展后续工作。

核心原则

• 一次只问一个问题——不要在一条消息中用多个问题让用户应接不暇
• 优先采用选择题——条件允许时，选择题比开放式问题更容易回答
• 严格遵循 DRY 和 YAGNI——避免不必要的重复和功能，将范围控制在最小限度（但如果过早抽象会增加耦合，则宁可重复代码）
• 先给出建议——明确表达看法并说明原因，同时让用户自行决定
• 探索备选方案——确定方案前始终提出 2–3 种方法（显而易见时除外）
• 重复与抽象——代码重复时，询问用户更倾向于重复代码（更简单、无耦合）还是抽象（符合 DRY 原则，但会增加复杂度）；在决定前说明权衡