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 关键片段：

> ```bash

> 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/

1. 如果检测到前端项目：
• 向用户展示发现的前端项目路径和技术栈
• 询问用户选择开发模式：

```

检测到当前项目关联了前端项目：{frontendPath}

前端技术栈：{frontendStack}

请选择开发模式：

1. 全栈开发模式（FULLSTACK）— 前后端整体分析、设计、实现、验证
2. 单后端开发模式（BACKEND）— 仅关注后端逻辑

```

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

1. 如果未检测到前端项目：自动设为 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 行相关代码作为切入点。

文档格式：

## 二、修改计划

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

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

第三段：验证

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

文档格式：

## 三、验证

### 描述一致性
| 用户描述 | 修改点 | 状态 |
|---------|--------|------|
| {描述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 页面是否需要新增降级提示 │

> └──────────────────────────────────────────────────┘

> ```

通过标准：风险已识别并处理，报告已展示给用户，待确认项已标注。

3.7 FEEDBACK — 闭环反馈【仅 FULL】

目标： 确认交付物与设计一致，处理 IMPLEMENT 阶段遗留的待确认项。

> IMPLEMENT 阶段已通过四轮迭代完成自查和风险扫描，FEEDBACK 阶段聚焦于用户视角的最终确认和第4轮风险报告中的待确认项。

执行步骤：

1. 回顾第4轮交付的风险报告，逐条处理用户反馈
2. 重新检查未完成的 TODO（按分类：临时/技债/外部依赖/逻辑补全/暂不明确）
3. 检查设计文档与实际代码的差异，更新文档
4. 给出测试验证建议：
• 正常路径测试
• 边界参数测试
• 异常路径测试
• 涉及数据库、接口、状态流转时，说明验证数据和预期结果
5. 如有必要，回到 DESIGNING 或 IMPLEMENTING 补充

全栈模式（devMode=FULLSTACK）：

全栈测试验证建议：

• 前端组件单元测试（如适用）
• 前后端接口联调测试（Postman / 浏览器 DevTools）
• 端到端测试建议（用户操作 → 前端响应 → 后端处理 → 数据验证）

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

3.8 DELIVERED — 交付（三模式共用）

• 提测或合并分支
• 最终确认
• QUICK 模式可在此步增加简短的验证闭环

全栈模式（devMode=FULLSTACK）：

• 前后端代码同时提交/合并
• 确认前后端接口版本一致
• 提供完整的前后端联调验证清单
• 如有前端部署，说明前端构建和部署步骤

4. 角色互搏机制【仅 FULL 模式】

在 DESIGNING 阶段，必须在两个角色间切换：

开发工程师角色

• 阅读需求/研发设计，标注不明确点、潜在风险、TODO 列表
• 生成"需确认点列表"抛给产品角色

产品/需求提出者角色

• 回答开发提出的确认点
• 给出明确指导、最佳实践、边界说明
• 输出可直接落地的研发设计

执行流程

DESIGNING 阶段：
  1. AI → 扮演开发工程师，阅读需求，生成确认点列表
  2. AI → 扮演产品角色，逐条回答确认点
  3. 将达成一致的方案写入设计文档

FEEDBACK 阶段（如适用）：
  1. AI → 扮演开发工程师，列出与设计文档的差异
  2. AI → 扮演产品角色，判断差异是否可接受
  3. 更新设计文档和 TODO

5. 核心原则

1. 文档先行 — FULL 模式必须有文档才开发；QUICK 模式至少口头确认；SIMPLE 模式单文档记录
2. 环境真实 — 项目环境必须通过读取实际配置文件探测，而非假设
3. 记忆优先 — 优先从记忆中恢复项目环境信息，避免重复探查；探测结果自动持久化到记忆
4. 记忆同步 — 分析过程中发现的项目风格和编码习惯，同步保存到 memory
5. 全栈一体 — 全栈模式下，前后端作为整体进行分析、设计、实现、验证，确保接口契约和数据流一致
6. 多轮小步迭代 — 骨架先行 → 内容填充 → 复盘加固 → 风险排查，每轮有明确焦点，不一次做完
7. 主动交互 — 第1轮骨架完成后主动展示方向；第4轮风险排查后主动输出报告。不闷头做到完才找用户
8. 实事求是 — 分析必须基于实际代码和数据库结构
9. 闭环迭代 — 开发反馈必须更新 TODO，确保无遗漏
10. 最小修改 — 不改无关代码，不引入无关抽象
11. 实时沟通 — SIMPLE 模式下积极与开发者沟通确认细节，不猜测、不擅自决定
12. 代码校准 — SIMPLE 模式下基于实际代码库验证用户描述，发现偏差主动说明
13. Agent 自律 — Agent 必须遵守模式选定的阶段流程，不得跳过 INIT、跳过分析或擅自切换模式；模式调整须经用户确认
14. 子任务复用 — 复杂场景下合理调度子 Agent 并行分析/设计，主 Agent 负责汇总决策和质量把控

6. 异常处理与恢复指引

6.1 核心原则：不猜测、先确认、可恢复

当出现任何异常或不确定情况时，遵循以下优先级：

1. 不猜测 — 遇到不确定的信息（类名、方法名、配置路径、业务流程），禁止编造或假设。宁可中断提示，不做武断臆想决策
2. 先确认 — 主动向开发者描述异常现象和你的分析，请求确认后再继续
3. 可恢复 — 优先利用已有文档和 context.json 自主恢复进度，减少重复劳动

6.2 通用异常场景处理

6.3 工具执行异常处理

6.4 状态恢复指引

当会话中断、超时或需要恢复工作时，Agent 应按以下流程自主恢复，无需等待用户逐项指示：

步骤 1：读取 context.json 判断当前进度

如果 context.json 存在：
  ├── 解析 currentPhase 和各 phases 的 done 状态
  ├── 检查各已完成阶段的 output 文档路径是否有效
  └── → 进入步骤 2

如果 context.json 不存在：
  ├── 检查 story 工作区目录是否存在
  │   ├── 存在 → 扫描目录下所有文档，推断当前状态
  │   └── 不存在 → 告知用户"未找到工作进度文件，是否需要重新初始化？"

步骤 2：读取已产出文档，构建上下文

根据 phases 中标记为 done 的阶段的 output 路径：
  ├── 逐一读取对应的文档文件
  ├── 摘要关键信息：需求目标、设计决策、已完成的 TODO、遗留风险
  └── → 构建恢复上下文后进入步骤 3

步骤 3：根据 currentPhase 确定恢复点

步骤 4：向用户展示恢复报告

┌─ 工作恢复报告 ─────────────────────────────────┐
│                                                  │
│  需求：{storyNameCN}                             │
│  模式：{mode} / {devMode}                        │
│  当前阶段：{currentPhase}                        │
│                                                  │
│  已完成阶段：                                     │
│    ✅ {phase1} → {outputDoc1}                   │
│    ✅ {phase2} → {outputDoc2}                   │
│                                                  │
│  待完成：{待办摘要}                               │
│                                                  │
│  请确认是否从当前阶段继续？                       │
│  [1] 继续 — 从 {currentPhase} 阶段继续工作       │
│  [2] 回退 — 回退到上一阶段重新检查               │
│  [3] 重置 — 清除进度，重新 INIT                  │
└──────────────────────────────────────────────────┘

6.5 各阶段异常处理补充

INIT 阶段异常

ANALYZE 阶段异常

IMPLEMENT 阶段异常

7. 参考与延伸

8. 技能法律

> 主动探索、合理判别、文档组织、小步迭代、闭环反馈、实事求是

>

> 禁止猜测、禁止捏造

9. 场景问题解答

9.1 如何选择 SIMPLE / QUICK / FULL 模式？

看改动范围：改 1-2 个文件、简单 bug 修、字段调整 → SIMPLE；3-5 个文件、正常功能迭代 → QUICK；涉及多模块、改表、对接外部系统、流程重构 → FULL。如果拿不准，先按 QUICK 跑 INIT 阶段，探测完环境再定。

9.2 做到一半发现选错模式了，能换吗？

能。告知 AI"模式需要升级/降级"，AI 会评估当前进度、保留已完成文档，调整阶段状态机继续推进。模式切换需经你确认。

9.3 我不想要文档，只想直接改代码行吗？

行。但建议至少走 SIMPLE 模式——它只有一份精简文档（需求确认 + 修改计划 + 验证），记录关键决策点方便后续回溯，写完代码也就顺手填完了。

9.4 会话中断后如何恢复？

直接说"刚才的问题继续，按 story 流程接着做"。AI 会自动执行状态恢复流程：读取 context.json → 确认当前阶段 → 展示恢复报告 → 从断点继续。

9.5 context.json 丢了或损坏了怎么办？

AI 会检查 story 工作区目录下是否有已产出的文档，通过文档推断当前进度。如果没有任何文档，只能重新 INIT。建议不要手动删除 story/ 目录。

9.6 前端项目没被自动检测到怎么办？

手动告知 AI 前端项目路径和技术栈，AI 会将其写入 projectEnv.frontendStack，后续按 FULLSTACK 模式工作。

9.7 分支创建时提示已存在怎么办？

AI 会提示你选择：沿用（切到已有分支继续）/ 重建（删除旧分支重新创建）/ 更换分支名（另起一个）。

9.8 做完一个需求，做下一个时 context.json 需要重建吗？

需要。每个需求有独立的 storyDir，新需求会创建新的 context.json。INIT 阶段会自动读取上一次保存的项目环境记忆，环境探测这一步可以跳过。

9.9 技能法律的"禁止猜测、禁止捏造"具体指什么？

遇到不确定的信息（类名、方法名、配置路径、业务流程、表结构），不要编造。展示已有的依据和你对问题的理解，列出选项请用户决策。详见第 6 章异常处理指引。

9.10 为什么技能这么长？

因为我们需要对各种各样的工作场景给 AI 明确的处理指引：什么情况用什么模式、遇到异常怎么恢复、什么时候该记忆、什么时候该问用户、文档怎么写、代码怎么查。技能长的目的是让你用起来短——你只需要说"我要改个功能"，AI 就能自主完成环境探测→模式判断→分析设计→编码交付全流程。所有篇幅都是为了提升随手即用、开箱即用、自主判断、自主推进的综合化能力，最大化 Agent 能力，最小化你的沟通成本。