@zhouhao4221/devflow-skills 0.2.0 → 0.3.1

package/plugins/req/skills/dev-guide/SKILL.md

@@ -0,0 +1,530 @@
+---
+name: dev-guide
+description: |
+  开发引导助手。仅在执行 /req:dev 命令时触发。按项目分层架构引导开发。
+---
+
+# 开发引导助手
+
+仅在 `/req:dev` 命令执行时激活，负责实现方案生成、开发引导和进度跟踪。
+
+根据需求类型（后端/前端/全栈）采用不同的开发引导策略：
+- **后端**：读取 docs/prompt/architecture.md 的分层架构，按配置的层级顺序详细引导
+- **前端**：聚焦功能点描述，依赖项目自身的技能和规范引导实现
+- **全栈**：后端分层 + 前端功能点，分阶段引导
+
+> **重要**：本 skill 不内置任何项目架构细节。分层顺序、目录结构、命名规范、开发规范
+> 均从 docs/prompt/architecture.md 读取。如文件不存在，
+> 会发出警告并建议用户通过 `/req:init --reinit` 补充。
+
+---
+
+## 一、前置准备
+
+### 1. 读取模块上下文
+
+如果需求元信息中指定了模块，先读取模块文档：
+
+```
+docs/requirements/modules/<模块名>.md
+```
+
+从中提取：
+- 模块职责和边界（确定实现范围）
+- 已有数据模型和 API（避免重复建设）
+- 相关需求列表（识别依赖）
+
+### 2. 识别需求类型
+
+| 类型 | 流程差异 |
+|------|---------|
+| REQ-XXX（正式需求） | 必须先通过评审，有完整的需求定义章节 |
+| QUICK-XXX（快速修复） | 跳过评审，方案确认后直接开发 |
+
+### 3. 识别项目类型
+
+从需求元信息的「类型」字段判断：
+
+| 类型 | 开发引导策略 |
+|------|------------|
+| 后端 | 完整分层架构引导（四~六章节） |
+| 前端 | 功能点清单引导（四-前端章节），实现交给项目自身技能 |
+| 全栈 | 后端分层 + 前端功能点，分阶段引导 |
+
+### 4. 仓库角色检查
+
+读取 `.claude/settings.local.json` 的 `requirementRole`：
+
+| 角色 | 行为 |
+|------|------|
+| `primary` | 本地读写，修改后自动同步缓存 |
+| `readonly` | 从缓存读取，允许基于已完成需求开发，不写入需求文档 |
+
+### 5. 加载项目知识
+
+**架构文件（prompt）**：Read `docs/prompt/architecture.md`，获取技术栈、分层架构、开发规范、测试规范。
+
+- 文件存在 → 读取，静默注入
+- 文件不存在 → 打印一次提示（非阻塞）：
+  ```
+  ⚠️  未找到 docs/prompt/architecture.md
+      /req:dev 依赖此文件了解项目分层和开发规范
+      可执行 /req:init --reinit 自动生成
+  ```
+
+**项目 Skills（具体约定）**：扫描 `.claude/skills/` 目录，读取所有 `.md` 文件。
+
+- 目录存在且有文件 → 全部读取，静默注入
+- 目录不存在或为空 → 静默跳过
+
+> `docs/prompt/architecture.md` 提供宽泛的架构知识；`.claude/skills/` 提供窄的具体约定（如路径变量）。两者互补，后续步骤直接使用，无需重复读取。
+
+---
+
+## 二、前置状态检查
+
+**在开始开发前必须检查需求状态，不通过则立即终止。**
+
+### REQ-XXX（正式需求）— 必须通过评审
+
+| 当前状态 | 处理方式 |
+|---------|---------|
+| 📝 草稿 | ❌ 拒绝：`需求尚未评审，请先执行 /req:review 提交评审` |
+| 👀 待评审 | ❌ 拒绝：`需求正在评审中，请等待评审通过后再开发` |
+| ❌ 评审驳回 | ❌ 拒绝：`需求评审未通过，请先修改后重新提审：/req:edit → /req:review` |
+| ✅ 评审通过 | ✅ 允许，首次进入 |
+| 🔨 开发中 | ✅ 允许，继续开发 |
+| 🧪 测试中 | ✅ 允许，修复测试问题 |
+| 🎉 已完成 | readonly → ✅ 允许；primary → ⚠️ 警告：`需求已完成，如需修改请创建新需求` |
+
+### QUICK-XXX（快速修复）— 跳过评审
+
+| 当前状态 | 处理方式 |
+|---------|---------|
+| 📝 草稿 | ✅ 允许，方案确认后直接开发 |
+| 方案确认 | ✅ 允许 |
+| 🔨 开发中 | ✅ 允许，继续开发 |
+| 🎉 已完成 | readonly → ✅ 允许；primary → ⚠️ 警告 |
+
+### `--reset` 标志
+
+带 `--reset` 参数时，清除已有实现方案（十一、实现方案），从头重新生成。
+
+---
+
+## 二-B、分支管理
+
+> 仅 `primary` 仓库执行，`readonly` 仓库跳过。
+
+### 1. 工作区清洁检查
+
+执行 `git status --porcelain`。若有未提交改动，列出改动文件，提示用户先 commit 或 stash，**终止流程**。
+
+### 2. 检测主分支
+
+优先 `git symbolic-ref refs/remotes/origin/HEAD`，失败时依次尝试 `origin/main`、`origin/master`，都失败回退 `main`。
+
+### 3. 分支切换或创建
+
+**已有 branch 字段**（元信息 `branch` 非 `-`）：
+- 本地存在 → `git checkout <branch>`
+- 仅远程存在 → `git checkout -b <branch> origin/<branch>`
+- 都不存在 → 从主分支创建 `git checkout -b <branch> <主分支>`
+
+**首次进入**（`branch` 为 `-` 或缺失）：
+1. 从需求标题生成英文 slug（小写 kebab-case，最多 5 词，ASCII only）
+2. 分支名格式：
+   - REQ → `feat/REQ-XXX-<slug>`
+   - QUICK → `fix/QUICK-XXX-<slug>`
+3. 若需求文档元信息 `issue` 字段非 `-` 且非空（如 `#12`），在分支名末尾追加 `-i<N>`（如 `-i12`）
+4. 展示分支名，等待用户确认（可修改）
+5. 创建分支 `git checkout -b <branch> <主分支>`
+6. 将分支名写入需求文档元信息 `branch` 字段
+
+### 4. 分支命名规则
+
+| 规则 | 说明 |
+|------|------|
+| 前缀 | REQ → `feat/`，QUICK → `fix/` |
+| 编号 | 保留完整编号（REQ-001、QUICK-003） |
+| slug | 英文翻译，lowercase kebab-case |
+| 长度 | slug 部分最多 5 个单词 |
+| 字符 | 仅 `[a-z0-9-/]` |
+| issue 后缀 | 当需求关联了 Git 平台 issue 时，末尾追加 `-i<N>`（如 `feat/REQ-001-user-points-i12`） |
+
+---
+
+## 三、加载需求上下文
+
+### 读取需求定义
+
+加载需求文档的业务定义章节，作为实现方案的输入：
+
+| 章节 | 用途 |
+|------|------|
+| 一、需求描述 | 理解背景和目标 |
+| 二、功能清单 | 确定开发范围和功能点 |
+| 三、业务规则 | 数据校验、状态转换、权限控制 |
+| 四、使用场景 | 理解用户操作流程 |
+| 五、接口需求 | 接口能力和业务语义（技术方案在实现阶段生成） |
+| 六、测试要点 | 后续测试参考 |
+
+### 读取领域规约（Specs）
+
+读取需求文档后，检查项目是否存在领域规约：
+
+- **primary 仓库**：扫描 `docs/requirements/specs/` 目录，读取所有 `.md` 文件
+- **readonly 仓库**：读取 `~/.claude-requirements/projects/<requirementProject>/specs/`（`requirementProject` 取自 `.claude/settings.local.json`）
+
+目录存在且有文件 → 全部读取，作为开发约束注入上下文，不打印提示。  
+目录不存在或为空 → 静默跳过。
+
+---
+
+### 检查已有实现方案
+
+检查需求文档「十一、实现方案」章节：
+
+- **已有完整内容**（非占位文本） → 直接展示，请用户确认是否沿用
+- **无内容或仅占位文本** → 进入方案生成流程
+- **带 `--reset` 标志** → 忽略已有内容，重新生成
+
+---
+
+## 四、生成实现方案（Plan Mode）
+
+进入 Plan Mode，基于需求定义和代码分析生成实现方案。
+
+**根据项目类型选择对应的方案生成流程**：
+
+---
+
+### 后端项目方案
+
+> **前置步骤**：读取 docs/prompt/architecture.md，获取分层架构表、目录结构、命名规范。
+> 步骤 5 未找到该文件时已输出警告，此处仍继续但方案可能不够准确。
+
+#### 4.1 数据模型（11.1）
+
+分析需求中涉及的数据实体，生成：
+
+> **需要生成 migration SQL 时（后端 / 全栈项目）**，从前置准备步骤 5 已加载的 Skills 中解析 `MIGRATIONS_DIR`：
+> 1. 已加载 `.claude/skills/migration.md` → 取其 `MIGRATIONS_DIR` 值
+> 2. 未配置 → 自动检测（`db/migrations`、`database/migrations`、`migrations`、`src/migrations`）
+> 3. 兜底：`docs/migrations`
+>
+> **未找到 `MIGRATIONS_DIR` 配置时**，打印一次警告（非阻塞，继续执行）：
+>
+> ```
+> ⚠️  未找到 .claude/skills/migration.md，当前使用 MIGRATIONS_DIR=<auto-detected or default>
+>     如需固定路径，创建 .claude/skills/migration.md 并写入：
+>     - **MIGRATIONS_DIR**: `<路径>`
+> ```
+>
+> SQL 文件写入路径：`$MIGRATIONS_DIR/<req-id>-<描述>.sql`
+
+```markdown
+### 11.1 数据模型
+
+#### 新增表
+
+| 表名 | 说明 | 关键字段 |
+|------|------|---------|
+| xxx_table | 描述 | field1, field2 |
+
+#### 修改表
+
+| 表名 | 变更 | 说明 |
+|------|------|------|
+| existing_table | 新增 field_x | 用于 xxx |
+
+#### 实体关系
+
+描述表间关联（一对多、多对多等）
+```
+
+**检查要点**（根据 architecture.md 中的开发规范补充具体检查项）：
+- 字段类型和约束与业务规则一致
+- 索引设计（查询场景驱动）
+- architecture.md 中定义的其他数据模型规范（如多租户字段、审计字段等）
+
+#### 4.2 API 设计（11.2）
+
+基于第五章「接口需求」的业务语义，结合项目代码和 CLAUDE.md API 风格，生成具体技术方案：
+
+```markdown
+### 11.2 API 设计
+
+| 接口 | 方法 | 路径 | 请求参数 | 响应 | 说明 |
+|------|------|------|---------|------|------|
+| 创建XXX | POST | /api/v1/xxx | { field1, field2 } | { id, ... } | 业务说明 |
+| 查询XXX | GET | /api/v1/xxx | ?page&size&filter | { list, total } | 业务说明 |
+```
+
+**生成依据**：
+- 路径风格：遵循 architecture.md 中的 API 风格（RESTful / GraphQL 等）
+- 参数设计：从业务规则中的数据校验提取字段约束
+- 错误码：按项目规范定义异常响应
+
+#### 4.3 文件改动清单（11.3）
+
+**按 docs/prompt/architecture.md 中定义的分层架构表顺序**列出需要新增/修改的文件：
+
+```markdown
+### 11.3 文件改动清单
+
+| 层级 | 文件路径 | 操作 | 改动说明 |
+|------|---------|------|---------|
+| <层1名称> | <CLAUDE.md中的目录>/xxx.<ext> | 新增 | <层1职责> |
+| <层2名称> | <CLAUDE.md中的目录>/xxx.<ext> | 新增 | <层2职责> |
+| ... | ... | ... | ... |
+```
+
+**文件命名**：遵循 architecture.md 中定义的文件命名规范。
+
+#### 4.4 实现步骤（11.4）
+
+**按 architecture.md 分层架构的顺序**拆解为有序步骤，每层一个步骤：
+
+```markdown
+### 11.4 实现步骤
+
+- [ ] 步骤 1：实现 <层1名称>（<层1职责>）
+  - 根据 CLAUDE.md 开发规范列出具体任务
+
+- [ ] 步骤 2：实现 <层2名称>（<层2职责>）
+  - ...
+
+- [ ] 步骤 N：实现 <层N名称>（<层N职责>）
+  - ...
+```
+
+**关键原则**：步骤数量和名称完全由 architecture.md 的分层架构表决定，不硬编码任何层级。
+
+---
+
+### 前端项目方案
+
+前端项目**不做分层架构引导**，聚焦于把交互逻辑和接口映射说清楚，具体实现交给项目自身的技能和规范。
+
+#### 4.1 接口映射（11.1）
+
+**自动匹配接口**：读取需求文档第五章「前端：交互逻辑」中的每个操作，按以下优先级匹配后端接口：
+
+1. **关联后端 REQ**：十、关联信息中的关联需求 → 读取其 11.2 API 设计
+2. **规范文档 specs**：`docs/requirements/specs/` 或缓存中的接口契约
+3. **Swagger/OpenAPI**：项目配置的 API 文档源（如有）
+4. **都未找到**：根据交互逻辑的数据需求推断接口签名，标注 `⚠️ 待确认`
+
+```markdown
+### 11.1 接口映射
+
+| 页面/操作 | 用户行为 | 匹配接口 | 请求参数 | 响应字段 | 来源 |
+|----------|---------|---------|---------|---------|------|
+| 订单列表 | 进入页面 | GET /api/v1/orders | page, size | list, total | 后端 REQ-001 |
+| 搜索 | 输入关键词 | GET /api/v1/orders | keyword, status | list, total | 后端 REQ-001 |
+| 审核按钮 | 点击通过/驳回 | POST /api/v1/orders/:id/audit | action, reason | result | 后端 REQ-001 |
+| 导出 | 点击导出 | GET /api/v1/orders/export | 同搜索条件 | 文件下载 | ⚠️ 待确认 |
+```
+
+**每个映射必须包含**：
+- **匹配接口**：方法 + 路径（匹配到的写实际接口，未匹配到的写推断值并标注）
+- **请求参数**：从交互逻辑���「数据需求」提取
+- **响应字段**：页面展示需要的字段
+- **来源**：标注接口来源（哪个 REQ / spec / swagger），方便联调时追溯
+
+#### 4.2 文件改动清单（11.3）
+
+列出涉及的页面和组件，不做架构层级约束：
+
+```markdown
+### 11.3 文件改动清单
+
+| 文件路径 | 操作 | 改动说明 |
+|---------|------|---------|
+| src/pages/xxx.vue | 新增 | xxx 页面 |
+| src/components/xxx.vue | 新增 | xxx 组件 |
+| src/api/xxx.ts | 新增/修改 | 接口定义 |
+```
+
+#### 4.3 实现步骤（11.4）
+
+按功能点拆解步骤，**不按技术层拆分**：
+
+```markdown
+### 11.4 实现步骤
+
+- [ ] 步骤 1：实现 xxx 功能
+  - 需要开发的页面/组件
+  - 调用的接口和数据处理
+  - 交互细节和异常处理
+
+- [ ] 步骤 2：实现 yyy 功能
+  - ...
+```
+
+**关键原则**：功能点描述清楚后，按项目自身的技能、组件库、代码规范来实现，dev-guide 不约束前端技术栈细节。
+
+---
+
+### 全栈项目方案
+
+分两部分生成：后端部分按分层架构引导，前端部分按功能点引导。
+
+```markdown
+### 11.1 数据模型
+（按后端项目方案的 11.1 格式）
+
+### 11.2 API 设计
+（按后端项目方案的 11.2 格式）
+
+### 11.3 文件改动清单
+（后端 + 前端文件合并列出）
+
+### 11.4 实现步骤
+（建议先后端再前端，后端按分层、前端按功能点）
+```
+
+---
+
+### 方案确认
+
+实现方案生成后：
+1. 展示完整方案供用户审核
+2. 用户确认后，将方案写入需求文档「十一、实现方案」章节（仅 `primary` 仓库，`readonly` 仓库不写入）
+
+---
+
+## 五、状态更新
+
+> 仅 `primary` 仓库执行，`readonly` 仓库跳过此步骤（不修改需求文档）。
+
+| 场景 | 操作 |
+|------|------|
+| 首次进入开发（状态为评审通过/草稿） | 状态改为「🔨 开发中」 |
+| 继续开发（状态已是开发中/测试中） | 状态不变 |
+
+状态更新时同步更新需求文档中的「生命周期」章节。
+
+---
+
+## 六、开发执行引导
+
+### 生成任务列表
+
+根据实现步骤（11.4）生成 TodoWrite 任务列表，每个步骤对应一个任务。
+
+---
+
+### 后端开发规范
+
+> **从 CLAUDE.md 读取**：以下规范从 docs/prompt/architecture.md 的「开发规范」章节获取。
+> 不同项目的规范不同，此处仅定义检查框架。
+
+按 docs/prompt/architecture.md 分层架构表中定义的顺序逐层实现。
+
+**每层实现时**：
+1. 读取 architecture.md 中该层的目录路径和命名规范
+2. 读取 architecture.md 中的开发规范（错误处理、日志、API 风格等）
+3. 按规范实现代码
+
+#### 后端检查清单
+
+每层实现后，根据 CLAUDE.md「开发规范」章节核对：
+
+- [ ] 文件命名遵循项目规范
+- [ ] 错误处理遵循项目规范
+- [ ] 日志规范
+- [ ] API/接口规范
+- [ ] architecture.md 中定义的其他规范项
+
+---
+
+### 前端开发引导
+
+前端开发**不做技术栈层面的约束**，按功能点逐个实现：
+
+1. **读取项目自身的技能和规范**：检查项目的 CLAUDE.md、skills/ 目录，了解项目的组件库、代码规范、目录结构等约定
+2. **按功能点顺序开发**：每个功能点作为一个独立任务
+3. **关注业务逻辑正确性**：确保交互行为、接口调用、异常处理与需求描述一致
+
+#### 前端检查清单
+
+每个功能点完成后核对：
+
+- [ ] 交互行为与需求描述一致
+- [ ] 接口调用正确（路径、参数、响应处理）
+- [ ] 异常状态处理（加载中、空数据、错误提示）
+- [ ] 遵循项目自身的代码规范和组件约定
+
+---
+
+## 七、开发中文档维护
+
+> 仅 `primary` 仓库执行，`readonly` 仓库跳过此步骤（不修改需求文档）。
+
+开发过程中需求文档应保持与实际开发同步。
+
+### AI 主动发现偏差
+
+开发过程中如果发现实际情况与需求文档不一致，**主动提示用户**：
+
+| 发现场景 | 涉及章节 | 处理方式 |
+|---------|---------|---------|
+| 代码中存在需求未描述的业务规则 | 三、业务规则 | 提示用户确认后补充 |
+| 实现中需要额外功能点 | 二、功能清单 | 提示用户确认后追加 |
+| 数据需求或交互逻辑有调整 | 五、数据与交互 | 提示用户确认后更新 |
+| 发现新的异常场景 | 六、测试要点 | 提示用户确认后补充 |
+| 实现步骤/文件清单有调整 | 十一、实现方案 | 直接更新，无需确认 |
+
+### 修改规则
+
+- **一~六章**：修改前提示用户确认，确认后同时在「九、变更记录」追加一条记录（日期、变更内容、影响范围）
+- **十一章**：开发过程中可直接更新（步骤调整、文件增减等属于实现细节）
+- **格式约束不变**：修改仍须遵循模板结构
+
+### 用户主动修改
+
+用户在开发过程中说"更新功能清单"、"加一条业务规则"等，按上述规则直接修改对应章节。
+
+---
+
+## 八、进度跟踪
+
+### 更新规则
+
+每完成一个实现步骤：
+
+1. **TodoWrite 任务状态** → 标记为 completed
+2. **需求文档 checkbox** → `- [ ]` 改为 `- [x]`（仅 `primary` 仓库，`readonly` 仓库跳过）
+
+### 开发概览格式
+
+```
+REQ-001 需求标题
+
+进度：2/N 步骤已完成
+实现步骤：
+- [x] 步骤 1：实现 <层1>
+- [x] 步骤 2：实现 <层2>
+- [ ] 步骤 3：实现 <层3> ← 当前
+- [ ] ...
+```
+
+---
+
+## 九、开发完成
+
+所有步骤完成后输出摘要：
+
+```
+开发完成！
+
+REQ-001 部门渠道关联
+- 实现步骤：5/5
+- 新增文件：4 个
+- 修改文件：1 个
+
+下一步：
+- /req:test REQ-001 - 进入测试
+```