| 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日志
