dev-guide

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

### 11.1 数据模型

#### 新增表

| 表名 | 说明 | 关键字段 |
|------|------|---------|
| xxx_table | 描述 | field1, field2 |

#### 修改表

| 表名 | 变更 | 说明 |
|------|------|------|
| existing_table | 新增 field_x | 用于 xxx |

#### 实体关系

描述表间关联（一对多、多对多等）

检查要点（根据 architecture.md 中的开发规范补充具体检查项）：

• 字段类型和约束与业务规则一致
• 索引设计（查询场景驱动）
• architecture.md 中定义的其他数据模型规范（如多租户字段、审计字段等）

4.2 API 设计（11.2）

基于第五章「接口需求」的业务语义，结合项目代码和 CLAUDE.md API 风格，生成具体技术方案：

### 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 中定义的分层架构表顺序列出需要新增/修改的文件：

### 11.3 文件改动清单

| 层级 | 文件路径 | 操作 | 改动说明 |
|------|---------|------|---------|
| <层1名称> | <CLAUDE.md中的目录>/xxx.<ext> | 新增 | <层1职责> |
| <层2名称> | <CLAUDE.md中的目录>/xxx.<ext> | 新增 | <层2职责> |
| ... | ... | ... | ... |

文件命名：遵循 architecture.md 中定义的文件命名规范。

4.4 实现步骤（11.4）

按 architecture.md 分层架构的顺序拆解为有序步骤，每层一个步骤：

### 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. 都未找到：根据交互逻辑的数据需求推断接口签名，标注 ⚠️ 待确认

### 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）

列出涉及的页面和组件，不做架构层级约束：

### 11.3 文件改动清单

| 文件路径 | 操作 | 改动说明 |
|---------|------|---------|
| src/pages/xxx.vue | 新增 | xxx 页面 |
| src/components/xxx.vue | 新增 | xxx 组件 |
| src/api/xxx.ts | 新增/修改 | 接口定义 |

4.3 实现步骤（11.4）

按功能点拆解步骤，不按技术层拆分：

### 11.4 实现步骤

- [ ] 步骤 1：实现 xxx 功能
  - 需要开发的页面/组件
  - 调用的接口和数据处理
  - 交互细节和异常处理

- [ ] 步骤 2：实现 yyy 功能
  - ...

关键原则：功能点描述清楚后，按项目自身的技能、组件库、代码规范来实现，dev-guide 不约束前端技术栈细节。

---

全栈项目方案

分两部分生成：后端部分按分层架构引导，前端部分按功能点引导。

### 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 - 进入测试