Skills
skills/ab300819/skills/devdocs-retrofit

devdocs-retrofit

SKILL.md

项目改造

将已有工程改造为 DevDocs 流程，或将旧版 DevDocs 迁移到新规范。

语言规则

  • 支持中英文提问
  • 统一中文回复
  • 使用中文生成文档

触发条件

  • 用户希望将现有项目适配 DevDocs 流程
  • 用户需要标准化项目文档
  • 用户要迁移或升级已有 DevDocs 文档
  • 项目缺少文档，需要从代码逆向生成

工作流程

1. 扫描项目结构
   │
   ▼
2. 检测项目状态
   │
   ├── 无 DevDocs ──────────────────┐
   │                                │
   ├── 有 DevDocs（旧版）────┐      │
   │                         │      │
   └── 有 DevDocs（符合规范）│      │
       → 无需改造            │      │
                             ▼      ▼
3a. 版本迁移流程      3b. 新项目改造流程
    │                       │
    ├── 规范检查            ├── 自动识别文档
    ├── 生成差异清单        ├── 用户确认/手动指定
    ├── 用户确认            ├── 代码逆向推导（可选）
    └── 执行迁移            └── 生成 DevDocs 文档
                             │
                             ▼
4. 生成改造报告

项目状态检测

检测逻辑

1. 检查 docs/devdocs/ 目录是否存在
   │
   ├── 不存在 → 新项目改造流程
   │
   └── 存在 → 检查规范符合性
       │
       ├── 符合当前规范 → 无需改造
       │
       └── 不符合 → 版本迁移流程

规范符合性检查清单

检查项 检查内容 规范要求
编号体系 F-XXX, US-XXX, AC-XXX 必须
测试编号 UT-XXX, IT-XXX, E2E-XXX 必须
追溯矩阵 F → US → AC → 测试 映射 必须
文件命名 01-requirements.md, 03-test-cases.md 等 必须
章节完整性 各文档必要章节 必须
Skill 协作 标注协作 Skill 建议

版本迁移流程

当检测到已有 DevDocs 文档但不符合当前规范时执行。

Step M1: 规范检查

扫描现有 DevDocs 文档，检查规范符合性：

## 规范检查报告

### 检测结果

| 文件 | 状态 | 问题 |
|------|------|------|
| 01-requirements.md | ⚠️ 需迁移 | 缺少 F/US/AC 编号 |
| 02-system-design.md | ✅ 符合 | - |
| 03-test-plan.md | ❌ 需重命名 | 应为 03-test-cases.md |
| 04-dev-tasks.md | ⚠️ 需迁移 | 缺少 T-XX 编号 |

Step M2: 生成差异清单

详细列出需要迁移的内容：

## 迁移差异清单

### 编号体系

| 文档 | 当前状态 | 迁移动作 |
|------|----------|----------|
| 01-requirements.md | 无编号 | 为功能点添加 F-001, F-002... |
| 01-requirements.md | 无编号 | 为用户故事添加 US-001, US-002... |
| 01-requirements.md | 无编号 | 为验收标准添加 AC-001, AC-002... |
| 03-test-*.md | 无编号 | 为测试用例添加 UT/IT/E2E-XXX |
| 04-dev-tasks.md | 无编号 | 为任务添加 T-01, T-02... |

### 文件结构

| 当前文件 | 迁移动作 | 目标文件 |
|----------|----------|----------|
| 03-test-plan.md | 重命名 + 拆分 | 03-test-cases.md |
| - | 新建 | 03-test-unit.md |
| - | 新建 | 03-test-integration.md |
| - | 新建 | 03-test-e2e.md |

### 追溯矩阵

| 当前状态 | 迁移动作 |
|----------|----------|
| 不存在 | 在 03-test-cases.md 中新建追溯矩阵章节 |

### 章节补充

| 文档 | 缺失章节 | 迁移动作 |
|------|----------|----------|
| 02-system-design.md | 需求追溯 | 添加第 13 节 |
| 04-dev-tasks.md | Skill 协作约束 | 添加编码约束说明 |

Step M3: 用户确认

使用 AskUserQuestion 展示迁移计划：

## 迁移计划确认

检测到当前 DevDocs 文档需要迁移到新规范。

### 迁移内容

1. **编号体系**：为所有功能点、用户故事、验收标准、测试用例添加编号
2. **文件重命名**：03-test-plan.md → 03-test-cases.md
3. **新建追溯矩阵**：建立 F → US → AC → 测试 的追溯关系
4. **章节补充**：补充缺失的规范章节

### 迁移选项

1. **完整迁移**（推荐）- 自动执行所有迁移动作
2. **选择性迁移** - 选择要执行的迁移项
3. **仅生成报告** - 不执行迁移，仅输出差异报告

请选择迁移方式。

Step M4: 执行迁移

编号迁移

为现有内容添加编号：

### 迁移前
- 用户注册功能
  - 作为新用户，我希望注册账号
  - 验收标准：邮箱格式正确

### 迁移后
- **F-001**: 用户注册功能
  - **US-001**: 作为新用户，我希望注册账号，以便使用系统
  - **AC-001**: 邮箱格式正确时注册成功
  - **AC-002**: 邮箱格式错误时提示错误信息

文件重命名

# 使用 git mv 保留历史
git mv docs/devdocs/03-test-plan.md docs/devdocs/03-test-cases.md

追溯矩阵生成

## 追溯矩阵

| 功能点 | 用户故事 | 验收标准 | 单元测试 | 集成测试 | E2E测试 |
|--------|----------|----------|----------|----------|---------|
| F-001 | US-001 | AC-001 | UT-001 | - | E2E-001 |
| F-001 | US-001 | AC-002 | UT-002 | - | E2E-001 |
| F-001 | US-002 | AC-003 | UT-003 | IT-001 | - |

新项目改造流程

当项目没有 DevDocs 文档时执行。

Step 1: 扫描项目结构

扫描常见文档位置：

# 文档目录
docs/ doc/ documentation/

# 根目录文档
README.md CHANGELOG.md

# 设计文档
design/ architecture/

# 测试文档
tests/ test/ __tests__/

Step 2: 自动识别文档

识别规则

DevDocs 阶段 识别关键词 常见文件名
需求文档 requirement, PRD, 需求, spec *requirement*.md, *prd*.md
系统设计 design, architecture, 设计, 架构 *design*.md, *architecture*.md
测试用例 test, QA, 测试, case *test*.md, *qa*.md
开发任务 task, todo, 任务, backlog *task*.md, *todo*.md

Step 3: 用户确认

## 文档识别结果

| 阶段 | 识别状态 | 识别到的文件 |
|------|----------|--------------|
| 需求文档 | ✅ 已识别 | `docs/requirements.md` |
| 系统设计 | ✅ 已识别 | `docs/architecture.md` |
| 测试用例 | ❌ 未找到 | - |
| 开发任务 | ⚠️ 待确认 | `TODO.md` (相似度 60%) |

### 选项

1. **确认识别结果** - 使用自动识别的映射
2. **手动指定文档** - 提供各阶段文档路径
3. **代码逆向推导** - 从代码分析生成文档（适用于无文档项目）

Step 4: 代码逆向推导（可选）

当项目缺少文档时，从代码分析生成文档。

需求推导

分析对象 推导内容 编号分配
路由/页面 功能模块 → F-XXX 按模块顺序
API 端点 业务操作 归属到 F-XXX
测试描述 用户故事 → US-XXX 按 F-XXX 分组
测试断言 验收标准 → AC-XXX 按 US-XXX 分组

推导示例

## 功能清单 [从代码推导]

### F-001: 用户模块

**用户故事**：
- **US-001**: 作为用户，我可以注册新账号
  - 来源：`POST /api/users` + `auth.test.ts`
- **US-002**: 作为用户，我可以登录系统
  - 来源：`POST /api/auth/login`

**验收标准**：
- **AC-001**: 邮箱格式正确时注册成功
  - 来源：`auth.test.ts: "should register with valid email"`
- **AC-002**: 密码少于 6 位时提示错误
  - 来源：`auth.test.ts: "should reject short password"`

测试用例推导

分析对象 推导内容 编号分配
单元测试文件 UT-XXX 按文件顺序
集成测试文件 IT-XXX 按文件顺序
E2E 测试文件 E2E-XXX 按文件顺序 
## 测试用例 [从代码推导]

### 单元测试

| 编号 | 关联 AC | 测试描述 | 来源 |
|------|---------|----------|------|
| UT-001 | AC-001 | should register with valid email | auth.test.ts:12 |
| UT-002 | AC-002 | should reject short password | auth.test.ts:24 |

Step 5: 生成 DevDocs 文档

按 DevDocs 规范生成完整文档：

docs/devdocs/
├── 01-requirements.md      # 含 F/US/AC 编号
├── 02-system-design.md     # 含模块-功能点映射
├── 03-test-cases.md        # 含追溯矩阵
├── 03-test-unit.md         # 含 UT-XXX 编号
├── 03-test-integration.md  # 含 IT-XXX 编号
├── 03-test-e2e.md          # 含 E2E-XXX 编号
├── 04-dev-tasks.md         # 含 T-XX 编号
└── 00-retrofit-report.md   # 改造报告

改造报告

# DevDocs 改造报告

## 改造概览

- **项目名称**：<project>
- **改造时间**：<timestamp>
- **改造类型**：新项目改造 / 版本迁移

## 改造结果

### 文档状态

| 文档 | 改造前 | 改造后 | 动作 |
|------|--------|--------|------|
| 需求文档 | docs/req.md | docs/devdocs/01-requirements.md | 转换 + 编号 |
| 系统设计 | - | docs/devdocs/02-system-design.md | 新建 |
| 测试用例 | tests/README.md | docs/devdocs/03-test-cases.md | 转换 + 编号 |
| 开发任务 | TODO.md | docs/devdocs/04-dev-tasks.md | 标准化 |

### 编号分配

| 类型 | 数量 | 范围 |
|------|------|------|
| 功能点 (F) | 5 | F-001 ~ F-005 |
| 用户故事 (US) | 12 | US-001 ~ US-012 |
| 验收标准 (AC) | 28 | AC-001 ~ AC-028 |
| 单元测试 (UT) | 15 | UT-001 ~ UT-015 |
| 集成测试 (IT) | 4 | IT-001 ~ IT-004 |
| E2E 测试 (E2E) | 3 | E2E-001 ~ E2E-003 |

### 待完善项

以下内容标记为 [待补充]：

- [ ] AC-015 ~ AC-020 验收标准细化
- [ ] 非功能性需求-性能指标
- [ ] API 响应示例

## 下一步建议

1. 完善标记为 [待补充] 的内容
2. 运行 `/devdocs-requirements` 审查需求文档
3. 运行 `/devdocs-test-cases` 完善测试用例
4. 使用 `/devdocs-feature` 添加新功能

Skill 协作

场景 协作 Skill 说明
需求审查 /devdocs-requirements 审查改造后的需求文档
设计审查 /devdocs-system-design 审查系统设计
测试用例 /devdocs-test-cases 完善测试用例设计
新增功能 /devdocs-feature 改造后添加新功能
Bug 修复 /devdocs-bugfix 改造后修复问题
测试质量 /testing-guide 检查测试有效性
文件操作 /git-safety 重命名文件时使用 git mv

约束

检测约束

  • 必须先检测项目状态（无 DevDocs / 旧版 / 符合规范）
  • 必须扫描常见文档目录
  • 识别结果必须让用户确认

迁移约束

  • 迁移前必须生成差异清单
  • 迁移前必须用户确认
  • 文件重命名必须使用 git mv
  • 不得删除原有文档的有效内容

编号约束

  • 必须为所有功能点分配 F-XXX 编号
  • 必须为所有用户故事分配 US-XXX 编号
  • 必须为所有验收标准分配 AC-XXX 编号
  • 必须为所有测试用例分配 UT/IT/E2E-XXX 编号
  • 编号必须连续，不得跳号

输出约束

  • 输出目录统一为 docs/devdocs/
  • 文件命名遵循 DevDocs 规范
  • 必须生成改造报告
  • 逆向推导内容必须标注 [从代码推导]

错误处理

无法识别文档

未能自动识别到相关文档。

请选择：
1. 手动指定各阶段文档路径
2. 使用代码逆向推导生成文档
3. 使用 /devdocs-requirements 从头创建

项目无文档

当前项目未检测到任何文档。

推荐：使用代码逆向推导功能，从代码自动生成文档。

是否开始代码分析？

迁移冲突

检测到迁移冲突：

| 冲突项 | 说明 | 建议 |
|--------|------|------|
| 编号重复 | F-001 已存在 | 重新分配编号 |
| 文件覆盖 | 03-test-cases.md 已存在 | 备份后覆盖 |

请确认处理方式。

输出文件

docs/devdocs/
├── 00-retrofit-report.md    # 改造报告
├── 01-requirements.md       # 需求文档（含编号）
├── 02-system-design.md      # 系统设计
├── 02-system-design-api.md  # API 设计（如需要）
├── 03-test-cases.md         # 测试用例概览 + 追溯矩阵
├── 03-test-unit.md          # 单元测试（含 UT-XXX）
├── 03-test-integration.md   # 集成测试（含 IT-XXX）
├── 03-test-e2e.md           # E2E 测试（含 E2E-XXX）
└── 04-dev-tasks.md          # 开发任务（含 T-XX）
Weekly Installs
6
Repository
ab300819/skills
First Seen
3 days ago
Installed on
claude-code5
opencode4
antigravity4
gemini-cli4
windsurf3
codex3