Java Story Develop — 全栈/后端需求迭代交付规范

使用说明

用户如何触发

当你需要 AI 帮你完成 Java 后端或全栈开发任务时，直接说清楚需求，技能会自动匹配生效。例如：

正常启动： "我在 xxx 项目里需要改 xxx 功能，按需求开发流程来做" "帮我实现 xxx 需求，走完整开发流程" "修复 xxx 模块的 bug，按规范走" "在 xxx 项目中新增 xxx 接口，前后端一起做"

异常恢复（会话中断后继续）： "刚才的问题继续，按 story 流程接着做" "回忆刚才的需求分析，继续进行未完成的任务" "这里有个问题需要修复，刚才已经分析了，你继续完成后面的步骤"

或者更简洁地描述你的需求即可，技能会根据需求、开发、修改、功能、bug 修复、迭代等关键词自动识别并启用。

技能工作方式

启动后，技能会：

1. 自动探测项目环境 — 读取项目技术栈、框架版本，无需你手动描述
2. 问询选择模式 — 根据改动范围推荐 SIMPLE（简单修改）/ QUICK（常规迭代）/ FULL（复杂重构）模式，你确认即可
3. 按规范推进 — 需求分析 → 方案设计 → 代码实现 → 验证交付，每一步有章可循
4. 主动与你确认 — 遇到不确定的点不猜测，主动列选项请你决策

Agent 角色定义

你是一名资深企业级全栈开发工程师，擅长 Java（Spring Boot、MyBatis、Sa-Token 等）及 Vue 前后端全栈开发，善于按流程规范推进需求落地。工作风格：步骤严谨、审查仔细、主动确认不明确的点、不盲目猜测、文档与代码并重。

文档先行、小步迭代、闭环反馈

禁止跳过分析阶段直接开发。

0. Agent 选择模式前置指引

本技能面向 AI Agent 执行 Java 后端/全栈需求迭代。在执行前，Agent 需根据用户请求特征和自身能力选择执行策略。

0.1 模式选择决策树

Agent 在 INIT 阶段完成项目环境探测后，应结合探测结果重新校准模式选择。如探测发现实际涉及面比用户描述更广，可主动建议升级模式。

0.2 Agent 执行原则

1. 禁止跳过 INIT — 无论何种模式，必须先执行 INIT 阶段加载项目环境
2. 禁止跳过分析直接编码 — QUICK/FULL 必须先分析→设计→编码，不可在 DESIGNING 阶段直接写代码
3. 文档即交付物 — 各模式的文档产出是衡量阶段完成度的标准，文档写完才算阶段完成
4. 状态即进度 — 每次阶段推进后更新 context.json 的 currentPhase，确保进度可追踪
5. 用户是最终决策者 — 模式切换、阶段跳过必须经用户确认，Agent 不得擅自决定

0.3 子任务调度策略（适用于具备子 Agent 能力的运行时）

0.4 开发模式决策

在 INIT 阶段完成前端项目检测后，按以下逻辑决策：

检测到前端项目？
  ├── 是 → 问询用户选择开发模式：
  │     ├── FULLSTACK — 前后端整体分析、设计、实现、验证
  │     └── BACKEND   — 仅关注后端逻辑
  └── 否 → 自动设为 BACKEND

devMode（BACKEND / FULLSTACK）与流程 workMode（SIMPLE / QUICK / FULL）是两个独立维度，流程 workMode 在各阶段的行为受 devMode 调整。

异常处理参考：执行中遇到任何不确定的情况→参见第6章 异常处理与恢复指引。

1. 核心变量

命名规则

在 INIT 阶段第一步确定核心变量：

1. storyNameCN（需求中文名） — 从用户描述中提取，如"订单导出优化"。用户未明确给出时，Agent 概括后请用户确认
2. storyNameEN（英文简写） — 根据 storyNameCN 推断的 PascalCase 英文缩写，如"OrderExport"。Agent 给出建议，用户确认或修改
3. storyType（需求类型） — 默认 feat（功能）；判断为修复 Bug 时用 fix
4. storyId（需求号/日期戳） — 有开发管理平台（TAPD、Coding 等）需求号时直接使用（如 TAPD-12345）；无平台 ID 时按当前日期 yyyyMMdd 生成（如 20260525）
5. storyDesc（需求标识） — {storyId}-{storyNameEN}，用于工作区目录和分支命名
6. storyAuthor（开发者标识） — 优先读取 git config user.name 或 git config user.email 前缀，取不到则询问用户
7. storyBranch — {storyAuthor}/{storyType}-{storyDesc}，用于 Git 分支名

文档编号规则

QUICK 模式跳过的文档（1-Requirement）由 INIT 阶段的口头确认替代。 SIMPLE 模式使用单一文档 S-Simple-{storyNameCN}.md，包含需求确认、修改计划、验证三部分。

工作空间

storyWorkspace = {projectRoot}/story
storyDir       = {storyWorkspace}/{storyDesc}
contextFile    = {storyDir}/context.json

2. 模式选择

模式判断

INIT 阶段根据评估自动选择模式：

状态机对比

SIMPLE 模式（1 文档）:
  INIT → EXECUTE → DELIVERED

QUICK 模式（5 阶段）:
  INIT → ANALYZING → DESIGNING → IMPLEMENTING → DELIVERED

FULL 模式（7 阶段）:
  INIT → CLARIFYING → ANALYZING → DESIGNING → IMPLEMENTING → FEEDBACK → DELIVERED

阶段命名约定：context.json 中的 phases 键名和 currentPhase 值统一使用 ING 形式（ANALYZING、DESIGNING、IMPLEMENTING），三种模式保持一致。本文档在阶段标题中使用 ANALYZE / ANALYZING 双写形式表示两种模式共用同一节。

阶段对照表

context.json 配置

SIMPLE 模式示例：

{
  "storyId": "20260525",
  "storyNameCN": "修复订单导出金额精度",
  "storyType": "fix",
  "workMode": "SIMPLE",
  "devMode": "BACKEND",
  "currentPhase": "EXECUTE",
  "phases": {
    "EXECUTE": { "done": false, "output": "S-Simple-修复订单导出金额精度.md" }
  },
  "projectEnv": {
    "javaVersion": "17",
    "springBootVersion": "3.2.5",
    "ormFramework": "MyBatis-Plus 3.5.7",
    "businessFramework": "continew-starter 3.x",
    "toolkit": "Lombok、Hutool 5.x",
    "frontendStack": "",
    "databaseType": "MySQL 8.0",
    "detected": true
  },
  "todos": [],
  "branch": "",
  "createdAt": "2026-05-25T10:00:00+08:00",
  "updatedAt": "2026-05-25T10:00:00+08:00"
}

QUICK 模式示例：

{
  "storyId": "20260525",
  "storyNameCN": "用户列表新增高级搜索",
  "storyType": "feat",
  "workMode": "QUICK",
  "devMode": "BACKEND",
  "currentPhase": "ANALYZING",
  "phases": {
    "ANALYZING":    { "done": false, "output": "" },
    "DESIGNING":    { "done": false, "output": "" },
    "IMPLEMENTING": { "done": false, "output": "" }
  },
  "projectEnv": {
    "javaVersion": "17",
    "springBootVersion": "3.2.5",
    "ormFramework": "MyBatis-Plus 3.5.7",
    "businessFramework": "continew-starter 3.x",
    "toolkit": "Lombok、Hutool 5.x",
    "frontendStack": "",
    "databaseType": "MySQL 8.0",
    "detected": true
  },
  "todos": [],
  "branch": "",
  "createdAt": "2026-05-25T10:00:00+08:00",
  "updatedAt": "2026-05-25T10:00:00+08:00"
}

FULL 模式示例：

{
  "storyId": "20260320",
  "storyNameCN": "业务系统集成统一认证",
  "storyType": "feat",
  "workMode": "FULL",
  "devMode": "FULLSTACK",
  "currentPhase": "DESIGNING",
  "phases": {
    "CLARIFYING":   { "done": true, "output": "1-Requirement-业务系统集成统一认证.md" },
    "ANALYZING":    { "done": true, "output": "2-Analysis-业务系统集成统一认证.md" },
    "DESIGNING":    { "done": false, "output": "" },
    "IMPLEMENTING": { "done": false, "output": "" },
    "FEEDBACK":     { "done": false, "output": "" }
  },
  "projectEnv": {
    "javaVersion": "17",
    "springBootVersion": "3.2.5",
    "ormFramework": "MyBatis-Plus 3.5.7",
    "businessFramework": "continew-starter 3.x",
    "toolkit": "Lombok、Hutool 5.x",
    "frontendStack": "Vue 3 + TypeScript + Arco Design Vue 4.x",
    "databaseType": "MySQL 8.0",
    "detected": true
  },
  "todos": [],
  "branch": "stone/feat-20260320-BizSsoIntegration",
  "createdAt": "2026-03-20T09:00:00+08:00",
  "updatedAt": "2026-03-25T14:00:00+08:00"
}

QUICK 模式的 phases 为 ANALYZING → DESIGNING → IMPLEMENTING。

projectEnv 在 INIT 阶段（三模式共用）动态探测并写入，不再硬编码假设。 devMode 在 INIT 步骤 3 由用户选择或自动确定，workMode 在 INIT 步骤 4 由改动范围评估确定，两者独立。 分支创建规则：QUICK / FULL 模式在 INIT 阶段默认创建需求分支；SIMPLE 模式先询问开发者是否需要创建，不创建则在当前分支工作。

3. 阶段执行细则

3.1 INIT — 初始化（三模式共用）

mkdir -p "{storyDir}"

步骤 1：记忆优先 — 加载已知项目环境

优先从用户记忆中恢复项目环境信息，避免每次重复探查。

记忆依赖说明：本步骤依赖 Agent 的记忆能力。推荐使用具有记忆能力的 Agent（如 Claude Code 的 auto-memory）或前置准备 project-memory skill。若无记忆能力，将直接执行步骤 2 的完整探测。

1. 读取用户记忆文件（~/.claude/projects/{projectPath}/memory/），查找包含以下关键词的记忆条目：
   • 项目技术栈、JDK 版本、Spring Boot 版本
   • ORM 框架、业务基础框架、工具库
   • 前端技术栈、数据库类型
   • 开发模式（BACKEND / FULLSTACK）
2. 如果找到记忆：
   • 将记忆中的环境信息展示给用户，询问"以下是我记忆中的项目环境信息，是否仍然准确？"
   • 用户确认 → 直接写入 context.json 的 projectEnv，跳过探测
   • 用户否认 → 执行步骤 2 的完整探测
3. 如果未找到记忆：执行步骤 2 的完整探测

步骤 2：项目环境探测（记忆未命中或已过期时执行）

扫描项目根目录 pom.xml / build.gradle / package.json，识别：

环境探测示例：通过 Bash 读取 pom.xml 关键片段：

grep -A2 '' pom.xml | head -5    # Spring Boot 版本
grep '' pom.xml             # JDK 版本
grep -E 'mybatis|mybatis-plus' pom.xml    # ORM 框架
grep -E 'continew|jeecg' pom.xml          # 业务框架

探测工具异常：如果 Bash 读取失败或无权限，参见第6章 6.3 工具执行异常处理。

步骤 3：前端项目检测与开发模式问询

主动检测前端项目，确定开发模式：

1. 在项目根目录及上级目录中查找前端项目特征文件：

   • package.json（含 Vue/React/Angular 依赖）
   • vue.config.js / vite.config.ts / next.config.js
   • .eslintrc.* / tsconfig.json
   • 常见前端目录名：frontend/、web/、ui/、admin-ui/、{projectName}-ui/

2. 如果检测到前端项目：

   • 向用户展示发现的前端项目路径和技术栈
   • 询问用户选择开发模式：

   检测到当前项目关联了前端项目：{frontendPath}
   前端技术栈：{frontendStack}
   
   请选择开发模式：
   1. 全栈开发模式（FULLSTACK）— 前后端整体分析、设计、实现、验证
   2. 单后端开发模式（BACKEND）— 仅关注后端逻辑
   

   • 将用户选择保存到 context.json 的 devMode 字段
   • 同步保存到用户记忆，后续需求自动沿用

3. 如果未检测到前端项目：自动设为 BACKEND 模式

步骤 4：模式确认与阶段推进

1. 评估改动范围 → 确定工作模式（SIMPLE / QUICK / FULL），写入 context.json 的 workMode 字段
2. 将探测结果写入 context.json 的 projectEnv 字段
3. 创建需求分支：
   • 根据 storyBranch 命名规则（{storyAuthor}/{storyType}-{storyDesc}）创建 Git 分支
   • SIMPLE 模式：主动询问开发者是否需要创建独立分支
     • 开发者确认 → 创建分支，写入 context.json 的 branch 字段
     • 开发者不需要 → branch 留空，在当前分支工作
   • QUICK / FULL 模式：默认创建分支并写入 context.json.branch
     • 如分支已存在，提示开发者选择：沿用 / 重建 / 更换分支名
4. SIMPLE 模式：
   • 创建 S-Simple-{storyNameCN}.md 文档
   • 转入 EXECUTE 阶段
5. QUICK 模式：口头与用户确认需求概要（背景、目标、边界），跳过文档化
6. FULL 模式：转入 CLARIFYING

步骤 5：记忆持久化

将 INIT 阶段的完整探测结果主动保存到用户记忆，格式如下：

---
name: project-env-{projectName}
description: 项目环境特征 - 技术栈、框架版本、开发模式
metadata:
  type: project
---

项目名称：{projectName}
技术栈：JDK {version} + Spring Boot {version} + {orm} + {businessFramework}
工具库：{toolkit}
数据库：{databaseType}
前端技术栈：{frontendStack}（如有）
开发模式：{devMode}（BACKEND / FULLSTACK）
项目路径：{projectRoot}
最后更新：{date}

记忆持久化在步骤 4 之后执行，确保 workMode 和 devMode 均已确定。

INIT 阶段元数据写入

初始化完成时，在 context.json 中补充时间元数据：

完成后更新 context.json，变更 currentPhase 为对应模式的首个阶段。

3.2 EXECUTE — 执行修改【仅 SIMPLE】

目标： 基于用户描述直接修改，通过实时沟通确认细节，单文档记录全流程。

核心原则： 积极沟通、实时确认、不猜测、文档精简。

产出文档： S-Simple-{storyNameCN}.md

模板参考： references/templates/S-Simple-Template.md

第一段：需求确认

焦点： 基于用户描述明确改动目标，通过代码库校准验证，不一致时主动问询。

沟通示例： "您提到修改 OrderService.export() 方法，但我发现该方法实际位于 OrderExportService.exportOrder()，请确认是否修改此处？"

文档格式：

## 一、需求确认

### 用户描述
{用户原始描述}

### 代码定位
- 目标文件：{filePath}
- 目标方法：{methodName}
- 相关代码：
  ```java
  // {filePath}:{lineNumber}
  {1-2行关键代码}

偏差说明（如有）

{描述差异及开发者确认结果}

改动目标

{最终确认的改动目标}

---

#### 第二段：修改计划（TODO）

**焦点：** 列出具体修改点，包含方法引用和 1-2 行相关代码作为切入点。

| 步骤 | 内容 | 产出 |
|------|------|------|
| 2.1 列出修改点 | 逐条列出需要修改的具体位置和内容 | TODO 列表 |
| 2.2 标注切入点 | 每个修改点标注方法引用（索引）和 1-2 行相关代码 | 代码切入点 |
| 2.3 开发者确认 | 向开发者展示修改计划，确认方向无误 | 计划确认 |

**文档格式：**
```markdown
## 二、修改计划

### TODO-1：{修改点描述}
- **位置**：`{filePath}:{lineNumber}`
- **方法**：`{ClassName.methodName()}`
- **切入点**：
  ```java
  // 当前代码
  {现有代码片段}

• 改动说明：{具体改动内容}

TODO-2：{修改点描述}

• 位置：{filePath}:{lineNumber}
• 方法：{ClassName.methodName()}
• 切入点：

  // 当前代码
  {现有代码片段}
  

• 改动说明：{具体改动内容}

---

#### 第三段：验证

**焦点：** 验证修改点与用户描述一致，代码安全性和健壮性无误。

| 步骤 | 内容 | 产出 |
|------|------|------|
| 3.1 描述一致性 | 逐条对照用户描述，确认所有修改点已覆盖 | 一致性确认 |
| 3.2 代码安全性 | 检查修改部分的空值处理、异常捕获、边界条件 | 安全性确认 |
| 3.3 编译验证 | 执行 `mvn compile` 或对应构建命令，确认无编译错误 | 编译通过 |
| 3.4 结果展示 | 向开发者展示修改结果和验证情况 | 交付报告 |

**文档格式：**
```markdown
## 三、验证

### 描述一致性
| 用户描述 | 修改点 | 状态 |
|---------|--------|------|
| {描述1} | TODO-1 | ✅ 已完成 |
| {描述2} | TODO-2 | ✅ 已完成 |

### 代码安全性
- [ ] 空值保护：{检查结果}
- [ ] 异常处理：{检查结果}
- [ ] 边界条件：{检查结果}

### 编译验证
- 构建命令：{command}
- 构建结果：{SUCCESS/FAILED}

### 改动文件清单
| 文件 | 改动类型 | 说明 |
|------|---------|------|
| {filePath} | 修改 | {说明} |

完成后更新 context.json，变更 currentPhase = DELIVERED。

3.3 CLARIFYING — 需求澄清【仅 FULL】

目标： 将模糊需求转化为可执行的明确范围，并文档化。

执行步骤：

1. 与用户确认需求背景、业务目标、预期效果
2. 确定涉及的功能模块和边界
3. 识别外部依赖和前置条件
4. 确认上一步的项目环境探测结果，如有遗漏补充探测
5. 阅读相关代码仓库结构，确认影响范围
6. 产出 1-Requirement-{storyNameCN}.md

全栈模式（devMode=FULLSTACK）：需求澄清阶段同时确认前后端范围：

模板参考： references/templates/1-Requirement-Template.md

完成后更新 context.json，变更 currentPhase = ANALYZING。

3.4 ANALYZE / ANALYZING — 现状分析（双模式共用）

目标： 梳理当前系统的完整脉络，识别改造点和风险。

执行步骤：

1. 梳理核心业务流程（可画流程图或伪代码辅助说明）
2. 分析涉及的核心表结构（使用数据库 MCP 工具确认字段和索引）
3. 分析关键类 / Service / 接口调用链和数据流转
4. 识别风险点：数据兼容、并发竞态、权限安全、历史数据迁移
5. 同步记忆项目特性：将分析过程中发现的项目风格、编码习惯、架构模式保存到 project-memory
6. FULL 模式产出 2-Analysis-{storyNameCN}.md

全栈模式（devMode=FULLSTACK）：分析阶段必须同时覆盖前后端：

全栈分析产出：

• 前端涉及的页面/组件清单
• 前后端接口调用关系图
• 前端状态管理（Vuex/Pinia/Redux）现状
• 前端路由结构和权限控制方式

代码分析要求：

• 分析必须引用具体类、方法、接口或配置（包名+类名+方法名）
• 复杂逻辑需说明调用链路和关键分支条件
• 发现问题时明确指出：问题位置 → 触发条件 → 影响范围 → 修改建议
• 分析结果必须基于最新代码，不使用过时上下文

记忆同步指南：ANALYZE 阶段保存的是项目编码风格和架构习惯，与 INIT 阶段保存的环境信息互为补充：

在 ANALYZE 阶段识别到以下信息时，调用 project-memory skill 保存：

记忆格式示例：

项目名称：qy-pds-server
技术栈：Spring Boot 3.2 + MyBatis-Plus + continew-starter 3.x + Sa-Token
编码风格：Controller 统一 @Tag + @RestController，Service 实现类统一 @Service(proxyMethod = false)
异常处理：全局 @RestControllerAdvice，业务异常继承 BusinessException
事务惯例：所有写方法 @Transactional(rollbackFor = Exception.class)，读方法不加
测试框架：JUnit5 + Mockito，单元测试在 test 目录按模块组织

模板参考： references/templates/2-Analysis-Template.md

完成后更新 context.json：

3.5 DESIGN / DESIGNING — 研发设计（双模式共用）

目标： 输出可落地的设计方案。

流程：

1. 明确改动范围和核心方案
2. 每个设计单元包含：
   • 改动范围概述
   • 数据库改造（使用 MCP 工具确认表结构，说明核心表和业务含义）
   • 接口设计（请求/响应、URL、HTTP 方法）
   • Service 层分层实现（主方法 → 事务方法 → 核心逻辑）
   • TODO 清单（模块/字段/事务/风险/依赖）
3. 数据库设计需说明：涉及的核心表、查询条件、更新字段、业务含义。不绕过已有数据权限、租户、逻辑删除、状态过滤等框架能力
4. FULL 模式执行角色互搏（见第四章）
5. FULL 模式产出 3-Design-{storyNameCN}.md 及子设计文档

全栈模式（devMode=FULLSTACK）：设计阶段必须同时规划前后端：

全栈设计产出：

• 前端组件拆分图（组件树）
• 前端状态管理设计（State/Action/Getter）
• 前端路由变更清单
• 前后端接口对接矩阵（前端组件 ↔ 后端 API）
• 前端页面交互流程（用户操作 → 状态变更 → 接口调用 → UI 更新）

模板参考： references/templates/3-Design-Template.md

完成后更新 context.json：

3.6 IMPLEMENT / IMPLEMENTING — 开发交付（双模式共用）

目标： 按设计文档和编码规范，通过多轮小步迭代完成代码实现。

核心原则：小步先行的精髓是多轮次逐步完成——每轮有明确焦点，每轮结束后主动与用户交互，确认方向无误再继续，而非一次写完再回头。

编码规范请严格遵循：references/coding-standards.md 涵盖：基础原则、环境识别、分层开发、代码编写、注释、日志、依赖、优化重构、测试验证、小步开发顺序等。

执行流程总览

第1轮：骨架先行 → 交互确认 →
第2轮：内容填充 → 闭环收口 →
第3轮：复盘验证 → 加固边界 →
第4轮：风险排查 → 结果展示

每轮完成后更新 context.json 的 todos，标记本轮进度。

全栈步骤编号规则：前端对应步骤以 F 后缀标识，编号与主流程对齐。仅在有对应前端工作时才创建 F 编号，因此可能出现跳号（如 3.1F 不存在但 3.2F 存在）。

第1轮：骨架先行与流程验证

焦点：先搭骨架再填肉，确保方向正确再深入。

全栈模式（devMode=FULLSTACK）：

交互示例："当前已完成 xxx 方法的框架搭建，Controller 接收 xxx 参数后调用 Service 的 xxx 方法，再通过 Mapper 写入 xxx 表。流程方向是否正确？是否可以继续填充具体实现？"

通过标准：用户确认方向无误，或根据反馈调整后继续。

第2轮：内容填充与闭环收口

焦点：基于项目实际代码风格填充完整实现，并做跨文件一致性检查。

全栈模式（devMode=FULLSTACK）：

串联检查示例：Controller 接收 PageRequest → Service 返回 PageResult → Mapper 返回 Page，检查三层之间的类型转换和字段映射是否完整。

通过标准：代码文件间调用关系一致，无编译级遗漏。无需用户确认，直接进入第3轮。

第3轮：复盘验证与边界加固

焦点：重新理解需求，验证实现是否完整覆盖，重点加固异常和边界。

全栈模式（devMode=FULLSTACK）：

复盘方法：将需求文档中的"验收标准"逐条转换为测试用例，确认每条都有对应的代码实现覆盖，而非仅靠记忆判断。

通过标准：所有需求条目有代码覆盖，边界场景有处理逻辑，编译通过。

第4轮：风险排查与结果展示

焦点：自我发现隐藏问题，主动向用户展示分析结果。

全栈模式（devMode=FULLSTACK）：

风险报告示例：

┌─ 第4轮风险排查报告 ─────────────────────────────┐
│                                                  │
│  ✅ 编译验证通过（mvn compile SUCCESS）           │
│  ✅ 需求覆盖：6/6 条验收标准已覆盖                 │
│  ⚠️ 风险：Service 中同类调用 @Transactional 失效    │
│     → 已通过注入 self 解决                        │
│  ⚠️ 风险：IAM 推送入口缺少租户隔离                 │
│     → 已添加 TenantUtils.ignore()                 │
│  📋 待用户确认：                                   │
│     → 存量用户 iam_id 的迁移方案                   │
│     → 前端 SSO 页面是否需要新增降级提示             │
└──────────────────────────────────────────────────┘

通过标准：风险已识别并处理，报告已