chore(skill): 清理全部 23 条历史校验警告
- 11 个超 20KB 的 SKILL.md 拆分，大章节移入 references/details.md - 7 处非标准字段（arguments/user_invocable）移入 metadata - 修 req-dev 4 条相对链接；validate 跳过行内代码避免  误报 - validate-skills.py: 23 warns -> 0 warns，0 errors
This commit is contained in:
johnQ
@@ -1,7 +1,8 @@
|
||||
---
|
||||
name: req-design
|
||||
description: 需求开发设计技能。用于 PRD 到开发设计的转换：API 契约定义、数据模型变更方案、变更文件清单、开发任务拆分、技术风险评估。当用户执行 /req doc 或需要编写开发设计文档时自动激活。
|
||||
arguments: <REQ-ID>
|
||||
metadata:
|
||||
arguments: <REQ-ID>
|
||||
---
|
||||
|
||||
# 需求开发设计 Skill (req-design)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -1,13 +1,9 @@
|
||||
---
|
||||
name: req
|
||||
description: 需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。
|
||||
arguments: <subcommand> [args]
|
||||
metadata:
|
||||
arguments: <subcommand> [args]
|
||||
---
|
||||
|
||||
# req - 需求工作流管理
|
||||
|
||||
需求全流程工作流管理，与 ai-proj CLI 深度集成。
|
||||
|
||||
## 需求生命周期
|
||||
|
||||
**审批状态**（status）：
|
||||
@@ -254,191 +250,6 @@ Deploy Gate 3: 证据完整 ── 验收任务有文档，含检查项表格 +
|
||||
{通过 / 有条件通过 / 需修改}
|
||||
```
|
||||
|
||||
## 命令参考
|
||||
|
||||
### 撰写命令
|
||||
|
||||
**`/req new [标题]`** — 对话式创建需求（仅 draft）
|
||||
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
|
||||
- 流程：描述→提取关键信息→用户故事→验收标准→`ai-proj req create`→ Gate 1 需求讨论
|
||||
|
||||
**`/req draft <描述>`** — 一句话快速创建 draft，AI 自动补全
|
||||
|
||||
**`/req edit [REQ-ID]`** — 编辑需求：`ai-proj req get` → 询问修改点 → `ai-proj req update` → 显示变更摘要
|
||||
|
||||
**`/req check [REQ-ID]`** — 完整性检查（Gate 4）：
|
||||
```
|
||||
✅ 三段式结构完整 / ✅ 验收标准: 4 条 / ✅ 讨论结论已记录 / ❌ PRD 文档缺失
|
||||
```
|
||||
|
||||
**`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联
|
||||
|
||||
### 原型设计
|
||||
|
||||
**`/req prototype [REQ-ID]`** — 基于 PRD 生成 Stitch 原型：
|
||||
1. 读取 PRD 文档，提取 UI 相关描述
|
||||
2. 创建 Stitch 项目 + 生成页面（调用 req-prototype 子技能）
|
||||
3. 截图回填 PRD「4.2 界面原型」章节
|
||||
- 参数：`--device [desktop|mobile|tablet]`，`--model [pro|flash]`
|
||||
|
||||
**`/req prototype edit [REQ-ID] --prompt "..."`** — 修改已有原型
|
||||
|
||||
**`/req prototype variant [REQ-ID]`** — 生成设计变体供选择
|
||||
|
||||
### 提交评审
|
||||
|
||||
**`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
|
||||
1. Gate 1: description 末尾有「## 讨论结论」
|
||||
2. Gate 2: 讨论结论经过用户确认
|
||||
3. Gate 3: 有 linkRole=prd 任务且附有文档
|
||||
4. Gate 4: 执行 `/req check` 全部通过
|
||||
5. → `ai-proj req submit --id <id>` → 展示 PRD 摘要 → 等待评审
|
||||
|
||||
**`/req review pass [REQ-ID]`** — 评审通过（必须用户明确确认后才调用 `ai-proj req approve --id <id>`）
|
||||
|
||||
**`/req review reject [REQ-ID] [原因]`** — 评审驳回，必须提供原因
|
||||
|
||||
### 阶段管理
|
||||
|
||||
**`/req` 或 `/req list`** — 按状态分组列出所有需求（`ai-proj req list`）
|
||||
|
||||
**`/req status [REQ-ID]`** — 查看需求详情（`ai-proj req get --id <id>`）、进度、关联任务
|
||||
|
||||
**`/req next [REQ-ID]`** — 推进到下一阶段：
|
||||
1. 检查当前阶段任务完成度
|
||||
2. 智能跳阶段检测（无 implementation 任务时建议跳过 review/testing）
|
||||
3. `ai-proj req advance --id <id> --to <stage>`（门禁检查，未通过→AskUserQuestion，**禁止 AI 自动 force**）
|
||||
4. ⭐ 内容门禁检查（review/testing/staging 阶段）
|
||||
5. 自动创建目标阶段建议任务
|
||||
6. 展示：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
|
||||
|
||||
**dev → review 门禁**：
|
||||
- `pr_created`: PR 已创建
|
||||
- `quality_gate`: CI 质量门禁通过记录（质量门禁未通过时提示：「CI 质量门禁未通过，请先运行 `/req ci`」）
|
||||
|
||||
**阶段顺序**：`analysis → design → dev → review → testing → [待部署池] → released`
|
||||
|
||||
**`/req resume [REQ-ID]`** — 会话断点恢复：`ai-proj req get --id <id>` 获取 delivery_stage + 任务状态 + 建议操作
|
||||
|
||||
### 开发命令
|
||||
|
||||
**`/req dev [REQ-ID]`** — 启动开发：
|
||||
1. `ai-proj req tasks --id <id>` 找 implementation 任务
|
||||
2. `ai-proj task start --id <task_id>` 更新任务状态为开发中
|
||||
3. `/pr start` 从 origin/main 建分支
|
||||
|
||||
**`/req cr [REQ-ID]`** — 代码评审（前置：开发任务完成）：
|
||||
1. `ai-proj req tasks --id <id>` 确认所有 implementation 任务已完成
|
||||
2. `git diff` / `find` 确定变更范围（文件数、行数）
|
||||
3. 读取所有变更文件源码（非 test 文件）
|
||||
4. **五视角扫描**：逐一用攻击者/泄露者/并发者/边界者/依赖者视角审查
|
||||
5. **约定检查**：运行所有 `scripts/check-*.sh --ci`，将结果写入 CR 报告
|
||||
6. **⭐ Bug 约定建议**（bug 类需求自动触发：category=bug，或标题含 fix/修复/bug，或描述含根因/复现步骤）：
|
||||
- 分析本次 bug 的根因模式
|
||||
- 判断可检测性：能写 grep 找到同类问题？（规则见 convention-flow.md「可检测性判断」）
|
||||
- 不可检测 → 仅在 CR 报告记录根因，跳过
|
||||
- 可检测 → 检查已有 `scripts/check-*.sh` 是否已覆盖 → 已覆盖则跳过
|
||||
- 扫描代码库统计同类模式数量 N
|
||||
- AskUserQuestion（N=0: 防未来复发；N>0: 防恶化+逐步清理）
|
||||
- 是 → 执行 convention flow → 产出物**单独 commit**（`chore: 建立 {name} 约定`）
|
||||
7. `ai-proj task create` 创建【代码评审】任务并关联需求（linkRole=code_review）
|
||||
8. `ai-proj create-and-attach` 附加 CR 报告文档（必须含五视角扫描结果 + 约定检查结果）
|
||||
9. 展示发现摘要，AskUserQuestion 确认是否创建 bug 修复任务
|
||||
10. 若有 High/Critical 发现 → `ai-proj task create` 创建关联修复任务
|
||||
|
||||
**`/req ci [REQ-ID]`** — CI 质量门禁检查与自动修复：
|
||||
1. `check-ci-status.sh` 检查当前分支 CI 状态
|
||||
- 通过 → 写入 `quality_gate` 门禁证据（`gate-callback.sh`）→ 完成
|
||||
- 运行中 → `--wait` 等待最多 5 分钟
|
||||
- 失败 → 进入自动修复循环
|
||||
2. 自动修复循环（最多 3 轮）：
|
||||
a. `fetch-ci-logs.sh --failed-only` 获取失败 job 日志
|
||||
b. AI 诊断根因（见错误模式目录）
|
||||
c. 自动修复代码
|
||||
d. 本地验证（`go vet ./...` / `npx tsc --noEmit`）
|
||||
e. `git commit && git push`
|
||||
f. `check-ci-status.sh --trigger --wait` 等待新 CI
|
||||
g. 通过 → 写入门禁证据 → 完成
|
||||
h. 仍失败 → 下一轮（超过 3 轮 → AskUserQuestion 是否继续）
|
||||
- 参数：`--trigger` 手动触发 CI，`--wait` 等待完成，`--no-fix` 仅诊断不修复
|
||||
|
||||
**错误模式目录**：
|
||||
|
||||
| 失败 Job | 错误模式 | 修复策略 |
|
||||
|----------|---------|---------|
|
||||
| architecture-gate | 架构 ratchet 违规 | 读取违规文件，用 service 层替代直接 database import |
|
||||
| backend-lint (go vet) | `file.go:42: unreachable code` | 读取文件，修复具体问题 |
|
||||
| backend-lint (gofmt) | `Files need gofmt:` | 运行 `gofmt -s -w` |
|
||||
| backend-lint (go test) | `--- FAIL: TestXxx` | 读取测试和实现，修复根因 |
|
||||
| frontend-lint (ESLint) | `warnings N > 4600` | 对比 main，只修复新增警告 |
|
||||
| frontend-lint (Prettier) | `unformatted N > 1000` | `npx prettier --write` 变更文件 |
|
||||
| frontend-lint (TS) | `errors N > 60` | 对比 main，只修复新增类型错误 |
|
||||
|
||||
**`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程
|
||||
|
||||
**`/req deploy [--project <name>] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）：
|
||||
1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
|
||||
2. AskUserQuestion 确认范围
|
||||
3. `ai-proj task create` 创建【部署】批次任务（linkRole=deploy）
|
||||
4. 部署前检查（变更检测、数据库迁移）
|
||||
5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify`
|
||||
6. **Deploy Gate 1: 健康检查** — `/health` 返回 200
|
||||
7. **Deploy Gate 2+3: PDV 验收**（为每个需求创建独立验收任务）：
|
||||
a. `ai-proj task create --title "【验收】PDV: {需求标题}"` 创建验收任务
|
||||
b. `ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification` 关联需求
|
||||
c. 从需求关联任务中提取前端变更范围（页面路由、菜单项、关键 API）
|
||||
d. 生成验收检查清单（页面可达 + 菜单可见 + 基础渲染 + API 连通）
|
||||
e. 用 Playwright 对部署环境执行冒烟测试：`E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium`
|
||||
f. 收集截图证据
|
||||
g. `ai-proj task append-doc --id <task_id>` 附加验收文档（检查项表格 + 截图 + 结论）
|
||||
h. **全部通过** → `ai-proj task complete --id <task_id>` → Gate 2+3 放行
|
||||
i. **任一失败** → 任务保持 in_progress，**阻断推进**，报告失败项
|
||||
8. `ai-proj task append-doc` 记录【部署】任务文档（构建日志 + 健康检查 + PDV 结果摘要）
|
||||
9. `ai-proj req advance --id <id> --to released` 批量推进（仅 Gate 1-3 全部通过的需求）
|
||||
|
||||
**`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
|
||||
|
||||
**Gate 0（强制）：AC 验收逐条确认** — 在所有类型检查之前执行：
|
||||
1. `ai-proj req get --id <id>` 获取需求描述
|
||||
2. 提取 `## 验收标准` 章节下的所有 `- [ ]` / `- [x]` 条目
|
||||
3. **无验收标准**：AskUserQuestion 警告并要求用户确认为何无 AC，必须说明跳过原因才能继续
|
||||
4. **有未勾选项（`- [ ]`）**：逐条列出，AskUserQuestion 请用户对每条提供验证证据（截图/curl 输出/日志）或明确标记为 N/A + 说明原因
|
||||
5. **全部已勾选（`- [x]`）**：展示 AC 摘要，直接继续
|
||||
6. AC 确认通过后，将每条 AC 的验证结果追加到需求描述（`ai-proj req update`），格式：`- [x] {原AC内容}（验证于 YYYY-MM-DD）`
|
||||
|
||||
**类型检查（Gate 0 通过后）**：
|
||||
- **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
|
||||
- **code 检查**：delivery_stage=released + deploy 任务完成 + verification 任务完成（PDV 通过） + 部署文档 + 所有任务完成
|
||||
- **skill 检查**：delivery_stage≥testing + 所有任务完成
|
||||
- **ops 检查**：deploy 任务完成 + 所有任务完成
|
||||
|
||||
### PRD 文档创建（通过任务中转）
|
||||
|
||||
```bash
|
||||
# create-and-attach 只支持任务 ID（task_documents 外键约束）
|
||||
# 1. 创建任务
|
||||
ai-proj task create --title "【评审】PRD: 用户认证功能"
|
||||
|
||||
# 2. 关联需求
|
||||
ai-proj req link --id 711 --task-ids 5214
|
||||
|
||||
# 3. 附加文档到任务
|
||||
ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
|
||||
```
|
||||
|
||||
### 阶段任务 Checklist
|
||||
|
||||
| 阶段 | 建议任务 | linkRole |
|
||||
|------|----------|----------|
|
||||
| analysis | 【评审】PRD: {需求标题} | prd |
|
||||
| design | 【评审】技术设计: {需求标题} | design |
|
||||
| dev | 【开发-后端】{需求标题}、【开发-前端】{需求标题} | implementation |
|
||||
| review | 【代码评审】{需求标题} | code_review |
|
||||
| review | 【约定】{约定名称}（bug 类需求，convention flow 自动创建） | documentation |
|
||||
| testing | 【测试】集成测试: {需求标题} | test |
|
||||
| deploy | 由 `/req deploy` 批量创建 | deploy |
|
||||
| released | 【验收】PDV: {需求标题}（`/req deploy` 自动创建） | verification |
|
||||
|
||||
## 测试环境流程
|
||||
|
||||
```
|
||||
@@ -506,3 +317,9 @@ ai-proj req tasks --id <id> # 查看关联任务
|
||||
| `req-prototype` | Stitch 原型生成 + 迭代 |
|
||||
| `dev-test` | 测试 + 质量门禁 |
|
||||
| `req-test-gate` (harness) | 工程约束方法论。Gate 0-2 的约定检查由项目本地脚本定义，方法论见 `/harness` 命令 |
|
||||
|
||||
## 详细内容
|
||||
|
||||
以下章节已移到 [references/details.md](references/details.md)：
|
||||
|
||||
- 命令参考
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
# skills 详细内容
|
||||
|
||||
## 命令参考
|
||||
|
||||
### 撰写命令
|
||||
|
||||
**`/req new [标题]`** — 对话式创建需求（仅 draft）
|
||||
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
|
||||
- 流程：描述→提取关键信息→用户故事→验收标准→`ai-proj req create`→ Gate 1 需求讨论
|
||||
|
||||
**`/req draft <描述>`** — 一句话快速创建 draft，AI 自动补全
|
||||
|
||||
**`/req edit [REQ-ID]`** — 编辑需求：`ai-proj req get` → 询问修改点 → `ai-proj req update` → 显示变更摘要
|
||||
|
||||
**`/req check [REQ-ID]`** — 完整性检查（Gate 4）：
|
||||
```
|
||||
✅ 三段式结构完整 / ✅ 验收标准: 4 条 / ✅ 讨论结论已记录 / ❌ PRD 文档缺失
|
||||
```
|
||||
|
||||
**`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联
|
||||
|
||||
### 原型设计
|
||||
|
||||
**`/req prototype [REQ-ID]`** — 基于 PRD 生成 Stitch 原型：
|
||||
1. 读取 PRD 文档，提取 UI 相关描述
|
||||
2. 创建 Stitch 项目 + 生成页面（调用 req-prototype 子技能）
|
||||
3. 截图回填 PRD「4.2 界面原型」章节
|
||||
- 参数：`--device [desktop|mobile|tablet]`，`--model [pro|flash]`
|
||||
|
||||
**`/req prototype edit [REQ-ID] --prompt "..."`** — 修改已有原型
|
||||
|
||||
**`/req prototype variant [REQ-ID]`** — 生成设计变体供选择
|
||||
|
||||
### 提交评审
|
||||
|
||||
**`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
|
||||
1. Gate 1: description 末尾有「## 讨论结论」
|
||||
2. Gate 2: 讨论结论经过用户确认
|
||||
3. Gate 3: 有 linkRole=prd 任务且附有文档
|
||||
4. Gate 4: 执行 `/req check` 全部通过
|
||||
5. → `ai-proj req submit --id <id>` → 展示 PRD 摘要 → 等待评审
|
||||
|
||||
**`/req review pass [REQ-ID]`** — 评审通过（必须用户明确确认后才调用 `ai-proj req approve --id <id>`）
|
||||
|
||||
**`/req review reject [REQ-ID] [原因]`** — 评审驳回，必须提供原因
|
||||
|
||||
### 阶段管理
|
||||
|
||||
**`/req` 或 `/req list`** — 按状态分组列出所有需求（`ai-proj req list`）
|
||||
|
||||
**`/req status [REQ-ID]`** — 查看需求详情（`ai-proj req get --id <id>`）、进度、关联任务
|
||||
|
||||
**`/req next [REQ-ID]`** — 推进到下一阶段：
|
||||
1. 检查当前阶段任务完成度
|
||||
2. 智能跳阶段检测（无 implementation 任务时建议跳过 review/testing）
|
||||
3. `ai-proj req advance --id <id> --to <stage>`（门禁检查，未通过→AskUserQuestion，**禁止 AI 自动 force**）
|
||||
4. ⭐ 内容门禁检查（review/testing/staging 阶段）
|
||||
5. 自动创建目标阶段建议任务
|
||||
6. 展示：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
|
||||
|
||||
**dev → review 门禁**：
|
||||
- `pr_created`: PR 已创建
|
||||
- `quality_gate`: CI 质量门禁通过记录（质量门禁未通过时提示：「CI 质量门禁未通过，请先运行 `/req ci`」）
|
||||
|
||||
**阶段顺序**：`analysis → design → dev → review → testing → [待部署池] → released`
|
||||
|
||||
**`/req resume [REQ-ID]`** — 会话断点恢复：`ai-proj req get --id <id>` 获取 delivery_stage + 任务状态 + 建议操作
|
||||
|
||||
### 开发命令
|
||||
|
||||
**`/req dev [REQ-ID]`** — 启动开发：
|
||||
1. `ai-proj req tasks --id <id>` 找 implementation 任务
|
||||
2. `ai-proj task start --id <task_id>` 更新任务状态为开发中
|
||||
3. `/pr start` 从 origin/main 建分支
|
||||
|
||||
**`/req cr [REQ-ID]`** — 代码评审（前置：开发任务完成）：
|
||||
1. `ai-proj req tasks --id <id>` 确认所有 implementation 任务已完成
|
||||
2. `git diff` / `find` 确定变更范围（文件数、行数）
|
||||
3. 读取所有变更文件源码（非 test 文件）
|
||||
4. **五视角扫描**：逐一用攻击者/泄露者/并发者/边界者/依赖者视角审查
|
||||
5. **约定检查**：运行所有 `scripts/check-*.sh --ci`，将结果写入 CR 报告
|
||||
6. **⭐ Bug 约定建议**（bug 类需求自动触发：category=bug，或标题含 fix/修复/bug，或描述含根因/复现步骤）：
|
||||
- 分析本次 bug 的根因模式
|
||||
- 判断可检测性：能写 grep 找到同类问题？（规则见 convention-flow.md「可检测性判断」）
|
||||
- 不可检测 → 仅在 CR 报告记录根因，跳过
|
||||
- 可检测 → 检查已有 `scripts/check-*.sh` 是否已覆盖 → 已覆盖则跳过
|
||||
- 扫描代码库统计同类模式数量 N
|
||||
- AskUserQuestion（N=0: 防未来复发；N>0: 防恶化+逐步清理）
|
||||
- 是 → 执行 convention flow → 产出物**单独 commit**（`chore: 建立 {name} 约定`）
|
||||
7. `ai-proj task create` 创建【代码评审】任务并关联需求（linkRole=code_review）
|
||||
8. `ai-proj create-and-attach` 附加 CR 报告文档（必须含五视角扫描结果 + 约定检查结果）
|
||||
9. 展示发现摘要，AskUserQuestion 确认是否创建 bug 修复任务
|
||||
10. 若有 High/Critical 发现 → `ai-proj task create` 创建关联修复任务
|
||||
|
||||
**`/req ci [REQ-ID]`** — CI 质量门禁检查与自动修复：
|
||||
1. `check-ci-status.sh` 检查当前分支 CI 状态
|
||||
- 通过 → 写入 `quality_gate` 门禁证据（`gate-callback.sh`）→ 完成
|
||||
- 运行中 → `--wait` 等待最多 5 分钟
|
||||
- 失败 → 进入自动修复循环
|
||||
2. 自动修复循环（最多 3 轮）：
|
||||
a. `fetch-ci-logs.sh --failed-only` 获取失败 job 日志
|
||||
b. AI 诊断根因（见错误模式目录）
|
||||
c. 自动修复代码
|
||||
d. 本地验证（`go vet ./...` / `npx tsc --noEmit`）
|
||||
e. `git commit && git push`
|
||||
f. `check-ci-status.sh --trigger --wait` 等待新 CI
|
||||
g. 通过 → 写入门禁证据 → 完成
|
||||
h. 仍失败 → 下一轮（超过 3 轮 → AskUserQuestion 是否继续）
|
||||
- 参数：`--trigger` 手动触发 CI，`--wait` 等待完成，`--no-fix` 仅诊断不修复
|
||||
|
||||
**错误模式目录**：
|
||||
|
||||
| 失败 Job | 错误模式 | 修复策略 |
|
||||
|----------|---------|---------|
|
||||
| architecture-gate | 架构 ratchet 违规 | 读取违规文件，用 service 层替代直接 database import |
|
||||
| backend-lint (go vet) | `file.go:42: unreachable code` | 读取文件，修复具体问题 |
|
||||
| backend-lint (gofmt) | `Files need gofmt:` | 运行 `gofmt -s -w` |
|
||||
| backend-lint (go test) | `--- FAIL: TestXxx` | 读取测试和实现，修复根因 |
|
||||
| frontend-lint (ESLint) | `warnings N > 4600` | 对比 main，只修复新增警告 |
|
||||
| frontend-lint (Prettier) | `unformatted N > 1000` | `npx prettier --write` 变更文件 |
|
||||
| frontend-lint (TS) | `errors N > 60` | 对比 main，只修复新增类型错误 |
|
||||
|
||||
**`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程
|
||||
|
||||
**`/req deploy [--project <name>] [--env production]`** — 项目级批量部署（Staging 已自动化，push develop 即触发）：
|
||||
1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
|
||||
2. AskUserQuestion 确认范围
|
||||
3. `ai-proj task create` 创建【部署】批次任务（linkRole=deploy）
|
||||
4. 部署前检查（变更检测、数据库迁移）
|
||||
5. 执行 `./scripts/build-and-push.sh prod --detect --deploy --wait --verify`
|
||||
6. **Deploy Gate 1: 健康检查** — `/health` 返回 200
|
||||
7. **Deploy Gate 2+3: PDV 验收**（为每个需求创建独立验收任务）：
|
||||
a. `ai-proj task create --title "【验收】PDV: {需求标题}"` 创建验收任务
|
||||
b. `ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification` 关联需求
|
||||
c. 从需求关联任务中提取前端变更范围（页面路由、菜单项、关键 API）
|
||||
d. 生成验收检查清单（页面可达 + 菜单可见 + 基础渲染 + API 连通）
|
||||
e. 用 Playwright 对部署环境执行冒烟测试：`E2E_BASE_URL=<部署环境URL> npx playwright test e2e/pdv/ --project=chromium`
|
||||
f. 收集截图证据
|
||||
g. `ai-proj task append-doc --id <task_id>` 附加验收文档（检查项表格 + 截图 + 结论）
|
||||
h. **全部通过** → `ai-proj task complete --id <task_id>` → Gate 2+3 放行
|
||||
i. **任一失败** → 任务保持 in_progress，**阻断推进**，报告失败项
|
||||
8. `ai-proj task append-doc` 记录【部署】任务文档（构建日志 + 健康检查 + PDV 结果摘要）
|
||||
9. `ai-proj req advance --id <id> --to released` 批量推进（仅 Gate 1-3 全部通过的需求）
|
||||
|
||||
**`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
|
||||
|
||||
**Gate 0（强制）：AC 验收逐条确认** — 在所有类型检查之前执行：
|
||||
1. `ai-proj req get --id <id>` 获取需求描述
|
||||
2. 提取 `## 验收标准` 章节下的所有 `- [ ]` / `- [x]` 条目
|
||||
3. **无验收标准**：AskUserQuestion 警告并要求用户确认为何无 AC，必须说明跳过原因才能继续
|
||||
4. **有未勾选项（`- [ ]`）**：逐条列出，AskUserQuestion 请用户对每条提供验证证据（截图/curl 输出/日志）或明确标记为 N/A + 说明原因
|
||||
5. **全部已勾选（`- [x]`）**：展示 AC 摘要，直接继续
|
||||
6. AC 确认通过后，将每条 AC 的验证结果追加到需求描述（`ai-proj req update`），格式：`- [x] {原AC内容}（验证于 YYYY-MM-DD）`
|
||||
|
||||
**类型检查（Gate 0 通过后）**：
|
||||
- **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
|
||||
- **code 检查**：delivery_stage=released + deploy 任务完成 + verification 任务完成（PDV 通过） + 部署文档 + 所有任务完成
|
||||
- **skill 检查**：delivery_stage≥testing + 所有任务完成
|
||||
- **ops 检查**：deploy 任务完成 + 所有任务完成
|
||||
|
||||
### PRD 文档创建（通过任务中转）
|
||||
|
||||
```bash
|
||||
# create-and-attach 只支持任务 ID（task_documents 外键约束）
|
||||
# 1. 创建任务
|
||||
ai-proj task create --title "【评审】PRD: 用户认证功能"
|
||||
|
||||
# 2. 关联需求
|
||||
ai-proj req link --id 711 --task-ids 5214
|
||||
|
||||
# 3. 附加文档到任务
|
||||
ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
|
||||
```
|
||||
|
||||
### 阶段任务 Checklist
|
||||
|
||||
| 阶段 | 建议任务 | linkRole |
|
||||
|------|----------|----------|
|
||||
| analysis | 【评审】PRD: {需求标题} | prd |
|
||||
| design | 【评审】技术设计: {需求标题} | design |
|
||||
| dev | 【开发-后端】{需求标题}、【开发-前端】{需求标题} | implementation |
|
||||
| review | 【代码评审】{需求标题} | code_review |
|
||||
| review | 【约定】{约定名称}（bug 类需求，convention flow 自动创建） | documentation |
|
||||
| testing | 【测试】集成测试: {需求标题} | test |
|
||||
| deploy | 由 `/req deploy` 批量创建 | deploy |
|
||||
| released | 【验收】PDV: {需求标题}（`/req deploy` 自动创建） | verification |
|
||||
|
||||
@@ -2,9 +2,6 @@
|
||||
name: req-prd
|
||||
description: 产品设计与需求管理。用于 PRD、需求分析、用户故事、功能设计和原型规划，并将正式需求文档双写到本地仓库与 ai-proj Task Document。
|
||||
---
|
||||
|
||||
# 产品需求设计 Skill (req-prd)
|
||||
|
||||
## 概述
|
||||
|
||||
本技能用于辅助产品设计和需求管理工作，包括：
|
||||
@@ -469,104 +466,6 @@ mcp__ai-proj__export_task_document_to_file
|
||||
|
||||
---
|
||||
|
||||
## 功能设计流程
|
||||
|
||||
### 1. 需求收集
|
||||
|
||||
```
|
||||
输入：
|
||||
- 用户反馈
|
||||
- 业务需求
|
||||
- 数据分析
|
||||
- 竞品分析
|
||||
|
||||
输出：
|
||||
- 需求池（ai-proj 需求列表）
|
||||
```
|
||||
|
||||
若命中“模块设计访谈模式”，本阶段改为执行访谈协议并持续写入 ai-proj 讨论文档；访谈未确认前不进入 PRD 定稿。
|
||||
|
||||
### 2. 需求分析
|
||||
|
||||
```
|
||||
方法：
|
||||
- 5W1H 分析法
|
||||
- 用户访谈
|
||||
- 数据验证
|
||||
|
||||
输出：
|
||||
- 需求文档
|
||||
- 优先级排序
|
||||
```
|
||||
|
||||
### 3. 方案设计
|
||||
|
||||
```
|
||||
内容：
|
||||
- 功能架构
|
||||
- 交互流程
|
||||
- 界面原型
|
||||
- 技术方案
|
||||
|
||||
输出：
|
||||
- PRD 文档
|
||||
- 可生成原型的界面状态与交互规格
|
||||
```
|
||||
|
||||
### 4. 缺陷收敛
|
||||
|
||||
```
|
||||
输入：
|
||||
- 已确认讨论结论
|
||||
- 最新版完整 PRD
|
||||
|
||||
执行：
|
||||
- defect-analysis 全维度审计
|
||||
- 接受项修订 PRD
|
||||
- 对修订后的完整 PRD 重新审计，直至一轮 0 个新缺陷
|
||||
|
||||
输出：
|
||||
- 已收敛 PRD
|
||||
- 缺陷处置记录
|
||||
```
|
||||
|
||||
### 5. HTML 原型与反馈闭环
|
||||
|
||||
```
|
||||
适用：
|
||||
- 所有包含界面、用户操作或可视状态的模块
|
||||
|
||||
执行：
|
||||
- 调用 req-prototype 的 upload 模式生成独立 HTML
|
||||
- 上传并关联 Requirement
|
||||
- iframe 回填 PRD，验证访问和关键交互
|
||||
- 请用户评审；行为性反馈回到问答 → PRD → defect-analysis → 新原型版本
|
||||
|
||||
输出：
|
||||
- 已验证、已关联的 HTML 原型
|
||||
- PRD 与讨论文档中的版本/反馈/确认记录
|
||||
```
|
||||
|
||||
### 6. 评审验证
|
||||
|
||||
```
|
||||
评审维度：
|
||||
- 业务价值
|
||||
- 技术可行性
|
||||
- 资源评估
|
||||
- 风险评估
|
||||
|
||||
输出：
|
||||
- 评审结论
|
||||
- 修改意见
|
||||
```
|
||||
|
||||
模块设计访谈模式下，本阶段必须调用 `defect-analysis`，并按访谈协议将每轮发现、处置、PRD 修订和收敛结论回写到同一讨论文档。
|
||||
|
||||
UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用户对二者的联合确认；无 UI 模块则核对已记录的不适用理由和用户确认。
|
||||
|
||||
---
|
||||
|
||||
## 竞品分析
|
||||
|
||||
> 竞品分析模板已移至 `req-compare` 插件。涉及竞品对比时自动激活。
|
||||
@@ -605,51 +504,6 @@ UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用
|
||||
|
||||
---
|
||||
|
||||
## 设计检查清单
|
||||
|
||||
### PRD 完整性检查
|
||||
|
||||
- [ ] 模块/系统设计已完成单轮单问访谈，且全过程已写入 ai-proj 讨论文档
|
||||
- [ ] 讨论记录与 PRD 均已保存到仓库本地 Markdown 和对应 ai-proj Task Document
|
||||
- [ ] 两端复读正文一致，交付说明包含本地路径、task/document 标识和远程版本
|
||||
- [ ] 讨论结论已由用户明确确认
|
||||
- [ ] `defect-analysis` 已基于最新版 PRD 收敛到一轮 0 个新缺陷
|
||||
- [ ] 无未处置的致命/高严重度缺陷
|
||||
- [ ] UI 模块 HTML 原型已生成、上传并关联 Requirement；无 UI 模块已记录不适用理由和用户确认
|
||||
- [ ] 原型基线指向最新版 PRD，PRD `4.2` 已回填 iframe、版本说明和验证结果
|
||||
- [ ] 原型反馈导致的行为变更已回到问答、PRD 和 defect 全量重审，并生成新原型版本
|
||||
- [ ] 用户已联合确认最终 PRD 与 HTML 原型
|
||||
- [ ] 背景与目标明确
|
||||
- [ ] 用户群体定义清晰
|
||||
- [ ] 功能需求完整
|
||||
- [ ] 验收标准可测试（每条 AC 附带 VP-Data / VP-Steps / VP-Pass）
|
||||
- [ ] 异常情况已考虑
|
||||
- [ ] 性能要求已定义
|
||||
- [ ] 上线计划合理
|
||||
- [ ] 风险已评估
|
||||
|
||||
### 交互设计检查
|
||||
|
||||
- [ ] 用户流程完整
|
||||
- [ ] HTML 原型覆盖核心入口、主流程及 PRD 指定的关键状态
|
||||
- [ ] 原型 URL 可访问，Requirement 关联可读取，iframe 可展示，核心交互可操作
|
||||
- [ ] 边界情况处理
|
||||
- [ ] 错误提示友好
|
||||
- [ ] 反馈及时
|
||||
- [ ] 操作可撤销
|
||||
- [ ] 符合用户习惯
|
||||
|
||||
### 非功能需求检查
|
||||
|
||||
- [ ] 性能要求已量化（响应时间、并发量）
|
||||
- [ ] 安全需求已明确（权限、数据保护）
|
||||
- [ ] 兼容性要求已定义（浏览器、设备）
|
||||
- [ ] 可用性目标已设定
|
||||
|
||||
> **技术方案可行性检查**在 design 阶段由 `req-design` 技能完成。
|
||||
|
||||
---
|
||||
|
||||
## 常用工具
|
||||
|
||||
### 原型设计
|
||||
@@ -696,31 +550,11 @@ UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用
|
||||
|
||||
---
|
||||
|
||||
## Memory 隔离规则（强制，源自 devflow-claude 借鉴）
|
||||
|
||||
**规则：本 skill 涉及模板/文档产出的命令禁止受 auto-memory 影响产出物。**
|
||||
## 详细内容
|
||||
|
||||
### 禁止行为
|
||||
1. 不得根据 memory 中的偏好跳过或合并 PRD 模板章节
|
||||
2. 不得用 memory 里的历史需求/项目内容填充当前 PRD
|
||||
3. 不得根据 memory 反馈调整 PRD 章节顺序、表格列数、标题层级
|
||||
4. 不得读取 `~/.claude/projects/*/memory/` 辅助生成 PRD 正文
|
||||
以下章节已移到 [references/details.md](references/details.md)：
|
||||
|
||||
### 允许行为
|
||||
- memory 可影响**交互风格**（提问详略、确认节奏、语气）
|
||||
- memory 可指导**命令选择**（如根据用户习惯推荐先走 req-compare 还是 req-prd）
|
||||
- memory 可影响**非产出文本**（如对话中的说明）
|
||||
|
||||
### Why
|
||||
auto-memory 设计用于跨会话建立用户画像。但 PRD/需求文档是正式产出物，必须由**模板结构 + 当前输入**决定，不能因 memory 中的偏好自作主张调整结构，否则会导致：
|
||||
- 模板章节漂移（用户不知道为什么这次少了一章）
|
||||
- 历史项目内容污染（张冠李戴）
|
||||
- 产出不可复现
|
||||
|
||||
### How to apply
|
||||
执行 `/req prd` / PRD 编写 / 需求描述生成等命令时：
|
||||
- 仅读取：模板文件、用户当前输入、引用的已有需求文档
|
||||
- 不读取：memory 目录下的任何文件
|
||||
- 产出前自检：章节数量和顺序与模板完全一致
|
||||
|
||||
**参考**：devflow-claude 的 `plugins/req/commands/_common.md` 同名规则。
|
||||
- 功能设计流程
|
||||
- 设计检查清单
|
||||
- Memory 隔离规则（强制，源自 devflow-claude 借鉴）
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
# skills 详细内容
|
||||
|
||||
## 功能设计流程
|
||||
|
||||
### 1. 需求收集
|
||||
|
||||
```
|
||||
输入：
|
||||
- 用户反馈
|
||||
- 业务需求
|
||||
- 数据分析
|
||||
- 竞品分析
|
||||
|
||||
输出：
|
||||
- 需求池（ai-proj 需求列表）
|
||||
```
|
||||
|
||||
若命中“模块设计访谈模式”，本阶段改为执行访谈协议并持续写入 ai-proj 讨论文档；访谈未确认前不进入 PRD 定稿。
|
||||
|
||||
### 2. 需求分析
|
||||
|
||||
```
|
||||
方法：
|
||||
- 5W1H 分析法
|
||||
- 用户访谈
|
||||
- 数据验证
|
||||
|
||||
输出：
|
||||
- 需求文档
|
||||
- 优先级排序
|
||||
```
|
||||
|
||||
### 3. 方案设计
|
||||
|
||||
```
|
||||
内容：
|
||||
- 功能架构
|
||||
- 交互流程
|
||||
- 界面原型
|
||||
- 技术方案
|
||||
|
||||
输出：
|
||||
- PRD 文档
|
||||
- 可生成原型的界面状态与交互规格
|
||||
```
|
||||
|
||||
### 4. 缺陷收敛
|
||||
|
||||
```
|
||||
输入：
|
||||
- 已确认讨论结论
|
||||
- 最新版完整 PRD
|
||||
|
||||
执行：
|
||||
- defect-analysis 全维度审计
|
||||
- 接受项修订 PRD
|
||||
- 对修订后的完整 PRD 重新审计，直至一轮 0 个新缺陷
|
||||
|
||||
输出：
|
||||
- 已收敛 PRD
|
||||
- 缺陷处置记录
|
||||
```
|
||||
|
||||
### 5. HTML 原型与反馈闭环
|
||||
|
||||
```
|
||||
适用：
|
||||
- 所有包含界面、用户操作或可视状态的模块
|
||||
|
||||
执行：
|
||||
- 调用 req-prototype 的 upload 模式生成独立 HTML
|
||||
- 上传并关联 Requirement
|
||||
- iframe 回填 PRD，验证访问和关键交互
|
||||
- 请用户评审；行为性反馈回到问答 → PRD → defect-analysis → 新原型版本
|
||||
|
||||
输出：
|
||||
- 已验证、已关联的 HTML 原型
|
||||
- PRD 与讨论文档中的版本/反馈/确认记录
|
||||
```
|
||||
|
||||
### 6. 评审验证
|
||||
|
||||
```
|
||||
评审维度：
|
||||
- 业务价值
|
||||
- 技术可行性
|
||||
- 资源评估
|
||||
- 风险评估
|
||||
|
||||
输出：
|
||||
- 评审结论
|
||||
- 修改意见
|
||||
```
|
||||
|
||||
模块设计访谈模式下，本阶段必须调用 `defect-analysis`，并按访谈协议将每轮发现、处置、PRD 修订和收敛结论回写到同一讨论文档。
|
||||
|
||||
UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用户对二者的联合确认；无 UI 模块则核对已记录的不适用理由和用户确认。
|
||||
|
||||
---
|
||||
|
||||
## 设计检查清单
|
||||
|
||||
### PRD 完整性检查
|
||||
|
||||
- [ ] 模块/系统设计已完成单轮单问访谈，且全过程已写入 ai-proj 讨论文档
|
||||
- [ ] 讨论记录与 PRD 均已保存到仓库本地 Markdown 和对应 ai-proj Task Document
|
||||
- [ ] 两端复读正文一致，交付说明包含本地路径、task/document 标识和远程版本
|
||||
- [ ] 讨论结论已由用户明确确认
|
||||
- [ ] `defect-analysis` 已基于最新版 PRD 收敛到一轮 0 个新缺陷
|
||||
- [ ] 无未处置的致命/高严重度缺陷
|
||||
- [ ] UI 模块 HTML 原型已生成、上传并关联 Requirement；无 UI 模块已记录不适用理由和用户确认
|
||||
- [ ] 原型基线指向最新版 PRD，PRD `4.2` 已回填 iframe、版本说明和验证结果
|
||||
- [ ] 原型反馈导致的行为变更已回到问答、PRD 和 defect 全量重审，并生成新原型版本
|
||||
- [ ] 用户已联合确认最终 PRD 与 HTML 原型
|
||||
- [ ] 背景与目标明确
|
||||
- [ ] 用户群体定义清晰
|
||||
- [ ] 功能需求完整
|
||||
- [ ] 验收标准可测试（每条 AC 附带 VP-Data / VP-Steps / VP-Pass）
|
||||
- [ ] 异常情况已考虑
|
||||
- [ ] 性能要求已定义
|
||||
- [ ] 上线计划合理
|
||||
- [ ] 风险已评估
|
||||
|
||||
### 交互设计检查
|
||||
|
||||
- [ ] 用户流程完整
|
||||
- [ ] HTML 原型覆盖核心入口、主流程及 PRD 指定的关键状态
|
||||
- [ ] 原型 URL 可访问，Requirement 关联可读取，iframe 可展示，核心交互可操作
|
||||
- [ ] 边界情况处理
|
||||
- [ ] 错误提示友好
|
||||
- [ ] 反馈及时
|
||||
- [ ] 操作可撤销
|
||||
- [ ] 符合用户习惯
|
||||
|
||||
### 非功能需求检查
|
||||
|
||||
- [ ] 性能要求已量化（响应时间、并发量）
|
||||
- [ ] 安全需求已明确（权限、数据保护）
|
||||
- [ ] 兼容性要求已定义（浏览器、设备）
|
||||
- [ ] 可用性目标已设定
|
||||
|
||||
> **技术方案可行性检查**在 design 阶段由 `req-design` 技能完成。
|
||||
|
||||
---
|
||||
|
||||
## Memory 隔离规则（强制，源自 devflow-claude 借鉴）
|
||||
|
||||
**规则：本 skill 涉及模板/文档产出的命令禁止受 auto-memory 影响产出物。**
|
||||
|
||||
### 禁止行为
|
||||
1. 不得根据 memory 中的偏好跳过或合并 PRD 模板章节
|
||||
2. 不得用 memory 里的历史需求/项目内容填充当前 PRD
|
||||
3. 不得根据 memory 反馈调整 PRD 章节顺序、表格列数、标题层级
|
||||
4. 不得读取 `~/.claude/projects/*/memory/` 辅助生成 PRD 正文
|
||||
|
||||
### 允许行为
|
||||
- memory 可影响**交互风格**（提问详略、确认节奏、语气）
|
||||
- memory 可指导**命令选择**（如根据用户习惯推荐先走 req-compare 还是 req-prd）
|
||||
- memory 可影响**非产出文本**（如对话中的说明）
|
||||
|
||||
### Why
|
||||
auto-memory 设计用于跨会话建立用户画像。但 PRD/需求文档是正式产出物，必须由**模板结构 + 当前输入**决定，不能因 memory 中的偏好自作主张调整结构，否则会导致：
|
||||
- 模板章节漂移（用户不知道为什么这次少了一章）
|
||||
- 历史项目内容污染（张冠李戴）
|
||||
- 产出不可复现
|
||||
|
||||
### How to apply
|
||||
执行 `/req prd` / PRD 编写 / 需求描述生成等命令时：
|
||||
- 仅读取：模板文件、用户当前输入、引用的已有需求文档
|
||||
- 不读取：memory 目录下的任何文件
|
||||
- 产出前自检：章节数量和顺序与模板完全一致
|
||||
|
||||
**参考**：devflow-claude 的 `plugins/req/commands/_common.md` 同名规则。
|
||||
@@ -1,11 +1,9 @@
|
||||
---
|
||||
name: req-test-gate
|
||||
description: 测试与质量门禁制度。覆盖需求级测试(Gates 1-5)、部署级验证(Deploy Gates)、持续回归(Regression)、Harness Engineering 工程约束方法论（Ratchet、约定建立、门禁层级）。当用户提到质量门禁、架构约束、约定检查、ratchet、harness 相关任务时自动激活。
|
||||
arguments: <subcommand> [args]
|
||||
metadata:
|
||||
arguments: <subcommand> [args]
|
||||
---
|
||||
|
||||
# 测试与质量门禁制度 (req-test-gate) v2.1
|
||||
|
||||
## 概述
|
||||
|
||||
三层质量门禁架构，确保从需求到上线每个阶段都有结构化验证。
|
||||
@@ -348,48 +346,6 @@ Task({
|
||||
### 完整模板（scope = backend / fullstack）
|
||||
|
||||
```markdown
|
||||
## 测试报告 - {需求标题}
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| 需求 | REQ-XXXX |
|
||||
| 类型 | {code/skill/ops} |
|
||||
| 时间 | {YYYY-MM-DD HH:MM} |
|
||||
| 门禁版本 | test-gate v2 |
|
||||
|
||||
### 前置条件 (Gate 1)
|
||||
- CR 状态: ✅ 已通过
|
||||
- 开发任务: ✅ 全部完成 ({N}/{N})
|
||||
|
||||
### 测试执行 (Gate 2)
|
||||
| 序号 | 阶段 | 测试项 | 命令/方法 | 结果 | 备注 |
|
||||
|------|------|--------|----------|------|------|
|
||||
| T1 | 2A | 后端编译 | ... | ✅/❌/⏭️ | ... |
|
||||
| IT1 | 2C | 前端代理连通 | ... | ✅/❌/⏭️ | ... |
|
||||
| SM1 | 2D | 健康检查 | ... | ✅/❌/⏭️ | ... |
|
||||
| PC1 | 2E | 结构完整性 | ... | ✅/❌/⏭️ | ... |
|
||||
|
||||
### 跳过的测试
|
||||
⏭️ {测试项}: {原因}
|
||||
（无则写「无」）
|
||||
|
||||
### 质量验证 (Gate 3)
|
||||
{子代理结果摘要，或「未触发（ops 类型）」}
|
||||
|
||||
### 回归贡献 (Gate 5)
|
||||
{贡献的回归用例数，或「无需贡献」或「⏭️ 跳过: 过渡期」}
|
||||
|
||||
### 总结
|
||||
通过: {N}/{M} | 跳过: {K} | 结论: ✅ 通过 / ❌ 未通过
|
||||
```
|
||||
|
||||
### 文档质量门禁（被 `/req next` 检查）
|
||||
|
||||
- 含测试项表格（`|` 分隔符 ≥ 3 行）
|
||||
- 含通过/失败结论（`✅ 通过` 或 `❌ 未通过`）
|
||||
- 总字符数 ≥ 200
|
||||
- 门禁版本标记（`test-gate v2` 或 `test-gate v2.1`）
|
||||
|
||||
## Gate 5: 回归贡献检查
|
||||
|
||||
**确保 code 类型需求为回归池贡献测试用例。按 scope 区分贡献形式。**
|
||||
@@ -504,49 +460,10 @@ v3: Gate 0A(scope) + 0B(约定检查) → Gate 1 → Gate 2(按scope裁剪)
|
||||
|
||||
---
|
||||
|
||||
## Harness Engineering — 工程约束方法论
|
||||
|
||||
**项目级基础设施**的建立和维护方法论，与上述需求级门禁互补。
|
||||
## 详细内容
|
||||
|
||||
> 详见 [harness-engineering.md](harness-engineering.md) 完整文档。
|
||||
以下章节已移到 [references/details.md](references/details.md)：
|
||||
|
||||
### 核心理念
|
||||
|
||||
**建立自动化护栏防止新违规，同时允许渐进式清理遗留问题。**
|
||||
|
||||
三大支柱：
|
||||
1. **Ratchet** — 遗留违规数只能减不能增 → [ratchet-pattern.md](ratchet-pattern.md)
|
||||
2. **约定建立** — 每个 bug 修复后立即建立约定和检测 → [convention-flow.md](convention-flow.md)
|
||||
3. **门禁层级** — 按项目成熟度逐级引入 → [project-bootstrap.md](project-bootstrap.md)
|
||||
|
||||
### `/harness` 命令集（手动可用 + 自动嵌入）
|
||||
|
||||
| 命令 | 手动 | 自动触发 |
|
||||
|------|------|---------|
|
||||
| `/harness assess` | 随时 | 首次 `/req dev` |
|
||||
| `/harness init [level]` | 随时 | — |
|
||||
| `/harness convention [name]` | 随时 | `/req cr` + bug 类型需求 |
|
||||
| `/harness report` | 随时 | `/req test` Gate 0B |
|
||||
|
||||
### 模板
|
||||
|
||||
`templates/` 目录提供可复用的脚本模板：
|
||||
- [ratchet-script.md](templates/ratchet-script.md) — Ratchet 脚本模板（check/baseline/report 三命令）
|
||||
- [convention-script.md](templates/convention-script.md) — 约定检测脚本模板（grep 模式匹配）
|
||||
- [gates-doc.md](templates/gates-doc.md) — GATES.md 文档模板
|
||||
- [pre-commit-config.md](templates/pre-commit-config.md) — husky + lint-staged 配置（Node.js/Go/Monorepo）
|
||||
|
||||
### 与需求级门禁的关系
|
||||
|
||||
```
|
||||
Harness（项目级护栏） req-test-gate（需求级门禁）
|
||||
├── .husky/ pre-commit ├── Gate 0A: scope 分级
|
||||
├── CI lint workflow ├── Gate 0B: 运行 harness 的 check-*.sh ←─ 连接点
|
||||
├── scripts/check-*.sh ├── Gate 1: 前置条件
|
||||
├── CLAUDE.md 约定 ├── Gate 2: 测试执行
|
||||
│ ├── Gate 3: 质量验证
|
||||
│ ├── Gate 4: 文档持久化
|
||||
│ └── Gate 5: 回归贡献
|
||||
```
|
||||
|
||||
> Harness 不使用 Gate 编号。它的产出物（check-*.sh 脚本）通过 Gate 0B 接入 req-test-gate 流程。
|
||||
- 测试报告 - {需求标题}
|
||||
- Harness Engineering — 工程约束方法论
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# skills 详细内容
|
||||
|
||||
## 测试报告 - {需求标题}
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| 需求 | REQ-XXXX |
|
||||
| 类型 | {code/skill/ops} |
|
||||
| 时间 | {YYYY-MM-DD HH:MM} |
|
||||
| 门禁版本 | test-gate v2 |
|
||||
|
||||
### 前置条件 (Gate 1)
|
||||
- CR 状态: ✅ 已通过
|
||||
- 开发任务: ✅ 全部完成 ({N}/{N})
|
||||
|
||||
### 测试执行 (Gate 2)
|
||||
| 序号 | 阶段 | 测试项 | 命令/方法 | 结果 | 备注 |
|
||||
|------|------|--------|----------|------|------|
|
||||
| T1 | 2A | 后端编译 | ... | ✅/❌/⏭️ | ... |
|
||||
| IT1 | 2C | 前端代理连通 | ... | ✅/❌/⏭️ | ... |
|
||||
| SM1 | 2D | 健康检查 | ... | ✅/❌/⏭️ | ... |
|
||||
| PC1 | 2E | 结构完整性 | ... | ✅/❌/⏭️ | ... |
|
||||
|
||||
### 跳过的测试
|
||||
⏭️ {测试项}: {原因}
|
||||
（无则写「无」）
|
||||
|
||||
### 质量验证 (Gate 3)
|
||||
{子代理结果摘要，或「未触发（ops 类型）」}
|
||||
|
||||
### 回归贡献 (Gate 5)
|
||||
{贡献的回归用例数，或「无需贡献」或「⏭️ 跳过: 过渡期」}
|
||||
|
||||
### 总结
|
||||
通过: {N}/{M} | 跳过: {K} | 结论: ✅ 通过 / ❌ 未通过
|
||||
```
|
||||
|
||||
### 文档质量门禁（被 `/req next` 检查）
|
||||
|
||||
- 含测试项表格（`|` 分隔符 ≥ 3 行）
|
||||
- 含通过/失败结论（`✅ 通过` 或 `❌ 未通过`）
|
||||
- 总字符数 ≥ 200
|
||||
- 门禁版本标记（`test-gate v2` 或 `test-gate v2.1`）
|
||||
|
||||
## Harness Engineering — 工程约束方法论
|
||||
|
||||
**项目级基础设施**的建立和维护方法论，与上述需求级门禁互补。
|
||||
|
||||
> 详见 [harness-engineering.md](harness-engineering.md) 完整文档。
|
||||
|
||||
### 核心理念
|
||||
|
||||
**建立自动化护栏防止新违规，同时允许渐进式清理遗留问题。**
|
||||
|
||||
三大支柱：
|
||||
1. **Ratchet** — 遗留违规数只能减不能增 → [ratchet-pattern.md](ratchet-pattern.md)
|
||||
2. **约定建立** — 每个 bug 修复后立即建立约定和检测 → [convention-flow.md](convention-flow.md)
|
||||
3. **门禁层级** — 按项目成熟度逐级引入 → [project-bootstrap.md](project-bootstrap.md)
|
||||
|
||||
### `/harness` 命令集（手动可用 + 自动嵌入）
|
||||
|
||||
| 命令 | 手动 | 自动触发 |
|
||||
|------|------|---------|
|
||||
| `/harness assess` | 随时 | 首次 `/req dev` |
|
||||
| `/harness init [level]` | 随时 | — |
|
||||
| `/harness convention [name]` | 随时 | `/req cr` + bug 类型需求 |
|
||||
| `/harness report` | 随时 | `/req test` Gate 0B |
|
||||
|
||||
### 模板
|
||||
|
||||
`templates/` 目录提供可复用的脚本模板：
|
||||
- [ratchet-script.md](templates/ratchet-script.md) — Ratchet 脚本模板（check/baseline/report 三命令）
|
||||
- [convention-script.md](templates/convention-script.md) — 约定检测脚本模板（grep 模式匹配）
|
||||
- [gates-doc.md](templates/gates-doc.md) — GATES.md 文档模板
|
||||
- [pre-commit-config.md](templates/pre-commit-config.md) — husky + lint-staged 配置（Node.js/Go/Monorepo）
|
||||
|
||||
### 与需求级门禁的关系
|
||||
|
||||
```
|
||||
Harness（项目级护栏） req-test-gate（需求级门禁）
|
||||
├── .husky/ pre-commit ├── Gate 0A: scope 分级
|
||||
├── CI lint workflow ├── Gate 0B: 运行 harness 的 check-*.sh ←─ 连接点
|
||||
├── scripts/check-*.sh ├── Gate 1: 前置条件
|
||||
├── CLAUDE.md 约定 ├── Gate 2: 测试执行
|
||||
│ ├── Gate 3: 质量验证
|
||||
│ ├── Gate 4: 文档持久化
|
||||
│ └── Gate 5: 回归贡献
|
||||
```
|
||||
|
||||
> Harness 不使用 Gate 编号。它的产出物（check-*.sh 脚本）通过 Gate 0B 接入 req-test-gate 流程。
|
||||
Reference in New Issue
Block a user