# Arkweb Spec Gen

> ArkWeb 统一 Spec + 执行计划生成。从 proposal/requirement/design/review/analysis 聚合生成 4 合 1 的 spec.md 和 AC→Task 追溯的 task.md。触发词：生成 Spec、生成执行计划、生成 spec.md。

- Skill: `openharmonyinsight/arkweb-spec-gen` (Agent Skill)
- Install (CLI): `npx skillmds@latest add openharmonyinsight/arkweb-spec-gen`
- Raw SKILL.md: https://api.skillmd.com/api/skills/openharmonyinsight/arkweb-spec-gen/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: openharmonyinsight (https://skillmd.com/u/openharmonyinsight)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/openharmonyinsight/arkweb-spec-gen

---


# ArkWeb Spec 生成

**Announce at start:** "我正在使用 arkweb-spec-gen skill 生成 spec.md 和 task.md。"

## 输入

必须读取以下 5 个文档：
1. `proposal.md` — 需求基线（Phase 1+3）
2. `requirement.md` — 需求基线评审（Phase 4）
3. `design.md` — 架构设计（Phase 4）
4. `review.md` — 评审报告（Phase 5）
5. `analysis.md` — 代码分析报告（Phase 2）

## 输出

1. `spec.md` — 统一规格文档（4 合 1），保存到 `docs/features/{feature-name}/spec.md`
2. `task.md` — 执行计划，保存到 `docs/features/{feature-name}/task.md`

## 模板

**【强制】生成文档前，必须先 Read 模板文件，严格按模板的章节结构、中文章节标题、表格格式填充内容。不得自行改为英文结构或英文标题。这是硬性要求，不是建议。**

- **spec.md：** 读取 `{DOCS_REPO}/assets/templates/spec.md`，按模板结构填充
- **task.md：** 读取 `{DOCS_REPO}/assets/templates/task.md`，按模板结构填充

## 流程

### Step 1: 读取全部输入文档

并行读取 5 个输入文档，提取关键信息：
- 从 proposal.md 提取：问题陈述、核心目标、不做范围、P0 AC、用户故事
- 从 requirement.md 提取：功能设计、接口定义、DFX 分析、设备矩阵、验收标准
- 从 design.md 提取：涉及仓和模块、关键设计决策（ADR）、设计骨架、适用架构规则
- 从 review.md 提取：确认的设计决策、🟡 遗留项（记录到 spec.md 已知限制章节）
- 从 analysis.md 提取：受影响文件清单、模块路径、代码可行性结论

### Step 2: 生成 spec.md

按模板结构生成 4 合 1 统一规格文档，包含四个章节：

**第 1 章：架构设计**（从 design.md 提取）
- 设计元数据（Design ID / title / parent_requirement / target_feature / owner / status）
- 需求基线摘要（问题陈述 / 核心目标 / 目标发行版本 / 不做范围 / P0 验收标准）
- 涉及仓和模块（仓库 / 模块路径 / 当前职责 / 本 Feature 影响）
- 适用架构规则（Rule ID / 适用原因 / 设计结论 / 验证方式）
- 设计目标和非目标
- 不涉及项确认
- 方案概览 + 架构图 + 数据流/控制流
- 关键设计决策（ADR）
- 设计骨架（API 骨架 / 模块骨架 / 测试骨架 + 验证方式）
- 风险和开放问题

**第 2 章：接口规格**（从 requirement.md 提取）
- 接口定义（参数表四段式：参数名/类型/必填/说明）
- 行为场景（输入→输出→副作用）
- 约束条件（性能/安全/兼容性）

**第 3 章：特性规格**（从 proposal.md + requirement.md 提取）
- 概述表（特性名称/编号/Epic/优先级/版本/SIG/状态）
- 用户故事 + 验收标准（WHEN/THEN）
- 业务规则表（BR）
- 异常规则表（AR）
- 豁免规则表（EX）
- 恢复契约表（RC）
- 验证映射表（VM）
- 验收追溯表（AC → 业务规则 → Task → 测试）
- API 变更分析（Public/System/Internal）
- 构建系统影响（BUILD.gn / bundle.json）
- 兼容性声明
- 质量门禁计划

**第 4 章：任务规格**（从 design.md + analysis.md 提取）
- 受影响文件清单（操作/路径/说明）
- 依赖关系（阻塞/被阻塞/外部）
- 代码变更规格（新增/修改/删除）
- BUILD.gn 变更
- repo-mapping
- 验证清单（编译/单测/接口/代码质量）

**已知限制章节：**
- 从 review.md 中提取 🟡 未处理项，记录在此

### Step 3: 生成 task.md

基于 spec.md 的 AC 和规则表，拆解为可独立执行的 Task：

- AC 到 Task 追溯表（确保每个 P0/P1 AC 至少映射到一个 Task）
- 首批实现边界（必须实现 / 可后置 / 不建议延后）
- 阶段计划
- Task 列表（Task ID / 目标 / 文件范围 / AC 映射 / 前置依赖 / 完成判据 / 验证命令）
- Task 详情（每个 Task 自包含：目标 / AC 映射 / 前置依赖 / 非目标 / 完成判据 / 停止条件 / 文件清单 / Spec Context / Design Context / Required Rules）

**Task 粒度原则：**
- 每个 Task 形成最小能力闭环
- Task 粒度控制在 AI 可独立完成的范围
- 没有 TBD/TODO/占位符
- 没有跨 Task 隐式依赖
- 没有"与 Task-N 类似"等引用

### Step 4: 自检

**spec.md 自检：**
- [ ] 无 TBD/TODO/占位符
- [ ] 所有 AC 使用 WHEN/THEN 格式
- [ ] 范围边界明确
- [ ] 接口定义参数表四段式完整
- [ ] 涉及仓和模块与 analysis.md 一致

**task.md 自检：**
- [ ] 每个 P0/P1 AC 至少映射到一个 Task
- [ ] 每个 Task 文件范围明确
- [ ] 每个 Task 有完成判据和停止条件
- [ ] Task 验证命令可执行
- [ ] 交接信息自包含

## 回复格式

```
✅ spec-gen 完成
📄 spec.md：{file_path}
📄 task.md：{file_path}
📋 spec.md 结构：
- 第1章 架构设计：涉及 {N} 仓，ADR {N} 项
- 第2章 接口规格：{N} 个接口定义
- 第3章 特性规格：{N} 条 AC，规则表 {N} 条
- 第4章 任务规格：{N} 个受影响文件
📋 task.md 结构：
- Task 总数：{N}
- AC 覆盖：{N}/{N}（P0: {N}/{N}）
- 阶段数：{N}
```