spec-writer

name	spec-writer
description	game-dev-studio 项目的标准化 spec 设计文档编写规范。当用户提出"设计一个新功能"、"写spec"、"设计规范文档"、或任何新功能的设计/架构决策时使用。本 skill 提供标准化的章节模板、编号规则、INDEX.md 更新流程，确保所有 spec 文档保持一致的格式和完整性。触发词：设计、spec、规范、设计文档、设计方案。
agent_created	true

Spec Writer

Overview

为 game-dev-studio 项目编写标准化设计规范文档（spec）。确保所有 spec 文档遵循统一的章节结构、编号规则和完整性要求。

When to Use

• 设计新功能或架构变更
• 用户说"写spec"、"设计规范"、"设计方案"
• 任何涉及多文件改动、新组件、新API的设计任务

Spec 编号规则

格式：SPEC-XXX，三位数字从 001 递增。查看 .agent/specs/INDEX.md 获取当前最新编号，分配下一个可用编号。

Spec 文件位置

.agent/specs/<kebab-case-name>.md

文件名使用 kebab-case，简洁描述主题（如 tool-call-chain.md、image-service.md）。

通用章节模板

以下为 spec 文档的完整章节结构。标注 （必需） 的章节所有 spec 都必须包含，（条件） 的章节根据具体情况选择，（可选） 的章节仅在需要时添加。

文档头部（必需）

# <中文标题>

> **SPEC-XXX** | 状态：设计中 | 状态：已实现

状态取值：设计中 → 已实现

1. 目标（必需）

用 1-3 句话说明这个 spec 要解决什么问题、实现什么功能。

## 目标

在 <场景> 中，<做什么> 以实现 <目标>。

2. 背景（条件）

以下情况需要写背景章节：

• 现状描述：说明现有实现的不足或问题
• 问题分析：列举具体痛点（用编号项）
• 设计动机：解释为什么需要这个变更

## 背景

### 现状

<当前的问题描述>

**问题**：
1. **问题1**：<说明>
2. **问题2**：<说明>

纯新增功能（如新微服务）可以省略本节，或合并到"目标"中。

3. 架构概述（条件）

涉及系统架构、多服务交互、容器化部署的 spec 需要本节：

## 架构概述

<项目文件树>

### 与现有服务的对照

| 维度 | 已有服务A | 新服务 |
|------|-----------|--------|
| 镜像 | ... | ... |
| 端口 | ... | ... |

纯前端组件 spec 可省略。

4. API 设计（条件）

涉及 REST API、MCP 工具接口的 spec 需要本节：

## API 设计

### <端点分组>

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/xxx` | <说明> |

5. 设计方案（条件）

前端 UI 功能 spec 需要本节，包含：

## 设计方案

### 整体布局

<ASCII 布局图>

### 展示形式

<多种模式的对比>

### 配置项

| 配置项 | 默认值 | 范围 | 说明 |
|--------|--------|------|------|

6. 详细设计（条件）

包含具体实现细节的 spec 需要本节，按子编号组织：

## 详细设计

### 1. 数据流

<数据流图>

### 2. 组件/模块设计

**文件**：`src/components/Xxx.tsx`

<接口定义和关键逻辑>

### 3. 样式设计

<CSS/Tailwind 样式定义>

### 4. 交互行为

| 行为 | 描述 |
|------|------|
| **行为名** | <描述> |

### N. 可选增强

<标记为后续迭代的功能>

7. 可行性分析（必需）

## 可行性分析

| 检查项 | 结论 |
|--------|------|
| 是否需要后端改动 | 是/否 + 说明 |
| 数据是否已存在 | 是/否 + 说明 |
| 是否需要新 DB 表 | 是/否 + 说明 |
| 是否影响现有功能 | 是/否 + 说明 |
| 性能影响 | <评估> |
| 是否需要新增 SSE 事件 | 是/否 + 说明 |
| 是否需要 E2E 测试 | 是/否 + 说明 |

### 结论

<一句话总结可行性和风险>

8. 相关文件（必需）

只列出实际需要变更的文件，不列"无改动"或"复用已有"的文件。

## 相关文件

| 文件 | 角色 | 变更幅度 |
|------|------|---------|
| `path/to/file.ts` | <说明> | 新增 / 低（~N行） / 中 / 高 |

9. 测试策略（条件）

涉及代码变更的 spec 需要：

## 测试策略

1. **单元测试**：
   - <场景1>
   - <场景2>

2. **集成测试**：
   - <场景1>

3. **E2E 测试**：
   - 参考 UI-007/008 事件循环模式编写新用例
   - <验证点>

10. UI Test 验收规则（必需）

## UI Test 验收规则

提交代码前必须跑通 ui test。
如遇网络或依赖问题，可临时修改代码解决网络问题，但禁止提交为了解决网络依赖问题所做的变更。

11. 主动补全 UI Test 规范（必需）

## 主动补全 UI Test 规范

新增前端交互功能时，必须同步编写对应的 E2E 测试用例，并更新以下文档：
1. `tests/ui/e2e/studio.spec.ts` — 添加 UI-XXX 测试用例
2. `.agent/memory/E2E_TESTING.md` — **必须同步更新以下 3 处**：
   - 测试矩阵标题数字（如"12 个用例" → "13 个用例"）
   - 测试矩阵表格（新增 UI-XXX 行）
   - ui-coverage 覆盖率引用（如有）
3. `.agent/specs/<spec-file>.md` — 更新本文档测试策略章节
4. `.agent/specs/INDEX.md` — 新增 SPEC-XXX 索引条目

**⚠️ 测例数更新规则**：
每次新增 E2E 测试用例后，必须检查 `.agent/memory/E2E_TESTING.md` 中「测试矩阵总览」的标题数字
（如 `N 个用例`）是否与实际表格行数一致。忘记更新此数字是高频失误，会导致 ui-coverage
摘要数据与实际测试不相符。

**文件列表变更时的同步规则**：
新增 spec 相关文件后，必须更新所有受影响文档中的文件路径、行数统计、端口号、列名等硬编码数字。
检查范围包括：
- `.agent/memory/INDEX.md` — 快速参考中的工具/服务列表
- `.agent/memory/ARCHITECTURE.md` — 架构详解中的模块清单
- `.agent/memory/MEMORY.md` — 长期记忆中的工程决策记录
- `README.md` + `README.zh-CN.md` — 功能概览
- `docs/ARCHITECTURE.md` + `docs/ARCHITECTURE.zh-CN.md` — 架构文档

**⚠️ 实现后强制使用 doc-sync skill 执行全量文档检查**：
spec 实现完成后，加载 `.agent/skills/doc-sync/SKILL.md` 强制执行 A→G 区域全量遍历检查，
确保 README、架构文档、memory、spec INDEX、架构图等所有文档与最新代码保持一致。
此为强制步骤，不可跳过。

12. 详细 Debug 日志规范（必需）

## 详细 Debug 日志规范

### 前端组件日志

组件名：
\`\`\`
[DEBUG:ComponentName] <具体日志行>
\`\`\`

### E2E 测试日志

UI-XXX 测试用例：
\`\`\`
[UI-XXX] step1: <描述>
[UI-XXX] step2: <描述>
\`\`\`

如无前端/E2E 相关内容，注明"本节不适用"即可。

13. 验证标准（必需）

## 验证标准

1. <可验证的标准1>
2. <可验证的标准2>
...

每项标准必须是可验证的、具体的（不是"功能正常"这种模糊描述）。

14. 注意事项（可选）

## 注意事项

- **要点1**：<说明>
- **要点2**：<说明>

章节选择速查表

Spec 类型	必需章节	条件章节
新微服务	目标、架构概述、API设计、可行性分析、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、验证标准	测试策略
前端 UI 功能	目标、背景、设计方案、详细设计、可行性分析、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、验证标准、注意事项	测试策略
后端功能优化	目标、背景、详细设计、可行性分析、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、验证标准	测试策略
安全/过滤规则	目标、适用范围、过滤规则、处理流程、实现、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、验证标准	—
工具/MCP 功能	目标、背景、API设计、详细设计、可行性分析、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、测试策略、验证标准	—
架构重构	目标、背景、架构概述、详细设计、可行性分析、相关文件、UI Test验收规则、主动补全UI Test规范、Debug日志规范、测试策略、验证标准	注意事项

Spec 编写流程

Step 1: 确定编号

读取 .agent/specs/INDEX.md，取当前最大编号 +1。

Step 2: 选择章节

根据上方的"章节选择速查表"确定需要哪些章节。核心原则：

• 必需章节一个不能少
• 条件章节根据 spec 类型决定
• 不加不需要的章节（避免废话）

Step 3: 编写内容

逐章节填充，遵循以下原则：

• 先写目标：明确要解决什么问题，防止跑偏
• 数据流优先：先搞清楚数据从哪来、怎么流动，再设计 UI
• 可行性分析前置验证：编写详细设计前先确认方案可行（数据是否已有、是否需要新库表等）
• 验证标准量化：每项标准必须可测试、可度量

Step 4: 更新 INDEX.md

在 .agent/specs/INDEX.md 的索引表中新增一行：

| SPEC-XXX | <中文标题> | [<文件路径>.md](<文件路径>.md) | 设计中 |

Step 5: 提交

git add .agent/specs/<file>.md .agent/specs/INDEX.md
git commit -m "docs: SPEC-XXX <简短描述>"

Step 6: 使用 doc-sync skill 同步所有相关文档（强制）

spec 实现后必须强制执行。加载 .agent/skills/doc-sync/SKILL.md skill，按 A→G 区域逐项检查：

• 项目根 README (A) — spec 状态、功能描述
• docs/ 架构文档 (B) — 新服务、端口、数据流
• .agent/memory/ (C) — 架构、索引、E2E、约定
• .agent/specs/ (D) — INDEX 状态、相关 spec 一致性
• .agent/ 根 (E) — AI_AGENT_COMMON_INSTRUCTIONS
• 工作区记忆 (F) — 工程决策记录
• 架构图 (G) — SVG 更新 + PNG 导出

如 spec 仍在设计阶段，此步骤标记为 N/A 即可。

格式约定

• 中文内容：标题、说明文字用中文
• 代码/文件名：保持原始英文
• 表格首列加粗：| **名称** | ... |
• 代码块标注语言：```typescript
• 路径引用：使用反引号包裹，如 `server/db.ts`
• COMMIT 消息：docs: SPEC-XXX <英文简短描述>

参考

完整 spec 示例（按复杂度递增）：

• 简单型：.agent/specs/proposal-xss-sanitize.md (SPEC-001) — 安全规则类
• 中型：.agent/specs/github-ci-agent.md (SPEC-014) — 流程规范类
• 复杂型：.agent/specs/image-service.md (SPEC-008) / .agent/specs/video-service.md (SPEC-009) — 微服务架构类
• 前端 UI 型：.agent/specs/tool-call-chain.md (SPEC-019) — 带数据流+组件设计+配置项+Debug日志