games-development-ai/.agents/skills/feature-design-doc.md

name, description

name	description
feature-design-doc	当新功能/跨模块/改用户可见行为/触及外部服务·支付·数据进入设计阶段时使用:产出 WHAT+HOW 合一的功能设计文档——文字+Mermaid 为事实源、SVG/HTML 给人看,含第 0 步 SoT 注册表查证、sot-impact/上级申报、防漂移单源与文档骨架。

功能设计文档作业手册（feature-design-doc）

每个有真实复杂度的功能，开工前产出一份「功能设计文档」，取代旧的 -review.md + -execution.md 双档。一份文档同时承载 WHAT（意图/目标/边界/验证）与 HOW（方案/步骤），并以一式两份的表达服务两类读者：文字 + Mermaid 给人和 AI（AI 主靠它），SVG / HTML 给人（更重要，看图即懂边界与核心思想）。

何时用

• 新功能、跨模块、改变用户可见行为、触及外部服务 / 支付 / 数据的设计阶段。
• 简单、局部、低风险任务不需要——直接做，别为一次性改动套重型文档。

第 0 步(强制):先查 SoT 注册表

写任何设计前,先读 docs/architecture/README.md §2 注册表与 docs/agent-specs/_index.md 在飞板:本设计触及哪些既有 topic?是修订某个 SoT、新建 topic,还是纯留痕?把结论写进 frontmatter 的 sot-impact 字段(docs-gate G6 机器强制)。这一步治的是"新设计漏读既有设计/全局设计"——跳过它,门会把设计档拦在提交外。收口时按申报把可存留结论折进对应 SoT,设计档降为留痕。

这份文档承载什么（WHAT + HOW 合一）

段	回答	要点
意图	为什么做	解决什么真实问题、不做会怎样
目标	要达成什么	尽量可量化（指标 / 验收线）
边界	做 / 不做	in scope / out of scope 一眼分清，挡住范围蔓延
方案	怎么实现（架构级）	模块如何协作、关键设计决策与取舍
步骤计划	分几步落地	每阶段：交付物 / 验证 / 依赖 / 风险
验证	怎么算成功	验收标准、可观测信号

禁令（硬约束）：禁代码细节（函数签名 / 伪代码 / 具体实现——那是写代码时的事）；禁黑话 / AI 味 / 元叙述；方案与步骤只写架构级 HOW（做什么、谁产出什么、怎么验），不写代码级 HOW。

一式两份：四种表达的分工

媒介	读者	角色	在 md 里
文字（中文散文）	人 + AI	事实源，自洽——脱离图也能读懂全部设计；后续 AI 主要消费它	正文
Mermaid	人 + AI	结构图（流程 / 状态 / 时序 / 依赖），文本可 diff、随文档同源	内联 mermaid 块
SVG	人（更重要）	核心概览 / 边界 / 关系大图，看图即懂；颜色舒适、留白、核心路径高亮	assets/ 引用 inline
HTML	人（可选增强）	需交互 / 超丰富排版时的独立澄清页	链接打开，不内联

渲染现实（别踩）：Markdown 渲染器（GitHub / Gitea）直渲 Mermaid 与 inline SVG，但不内联渲染独立 .html（md 内的 html 标签多被过滤）。所以——md 阅读流里能直接看到的 = Mermaid + SVG；HTML 只作「🔗 在浏览器打开交互版」的链接，非必需：SVG 能讲清就不上 HTML。

媒介怎么选：结构关系 / 流程 → Mermaid；「一眼看懂全局 / 边界 / 核心思想」→ SVG（本文档的门面）；确需交互（可展开、可切换、可点选）→ HTML 独立页。

House style（复用，不另起）

功能设计文档的所有图，配色 / 三线语义 / 徽章 / 脚注 / 转义 / 复验脚本一律照 architecture-diagram-atlas.md：浅底 #f8fafc、主字 #0f172a、实线=现行 / 虚线=自建远期、远期紫 #7c3aed、红线 #dc2626、圆角 rx 7~12、脚注全角「：」、SVG 文字内 < > & 必转义。

侧重差异：atlas 面向「据图找缝」，功能设计文档面向「快速理解」——更重留白、层次分明、核心路径高亮，别堆信息密度。颜色要舒适、对比柔和。

• SVG 在 6c6g 出文本；PNG 批量转在 mini-desktop（6c6g 禁 chrome）。见 staging-ops.md。

防漂移：一式两份的单一事实源

「两份」绝不能平等维护，否则必漂移（本项目反复踩的坑）：

• 文字 + Mermaid = 事实源（随 md 走、可 diff）；SVG / HTML = 派生视觉。
• 设计变更：先改文字 + Mermaid，再据此更新 SVG / HTML；图文冲突以文字为准。
• frontmatter 防漂移门（复用 atlas）：记关联代码 / 契约的 commit hash + 图清单；收口比对 hash，对不上标「待复核」。
• 权威细节只写在文字里（图里重复一份 = 又一个漂移面）；图只承载结构与边界的直觉。

文档结构骨架

---
date / topic / status（草稿 | 评审中 | 已批准 | 已实现）
sot-impact: 新建 topic X | 修订 topic Y | 纯留痕     # G6 申报(第 0 步的产出)
上级: <仓根相对路径>     # G7 谱系单指针:本档的直接上级(通常是所属执行线的计划/SoT);填不出来 = 上级还没认领这条线,先回写上级再开工(§10.8)
关联: <代码 / 契约路径 + commit hash>     # 防漂移门
图清单: [图1 概览, 图2 边界, ...]
---
# <功能> 功能设计

## 0 一图看懂      # 顶部放最重要的 SVG 概览 + 三句话：核心思想 / 边界 / 怎么算成功
## 1 意图与目标    # 为什么做、要达成什么（可量化）
## 2 边界          # 做什么 / 不做什么（配边界图）
## 3 方案          # 架构级，关键决策与取舍（配结构图）
## 4 步骤计划      # 分阶段：交付物 / 验证 / 依赖 / 风险（配阶段图）
## 5 验证方式      # 验收标准、可观测信号
## 6 风险与回滚
## 附 图清单与状态 · HTML 增强页链接

§0「一图看懂」是门面：一张 SVG + 三句话，让人 30 秒抓住意图、边界、核心思想；这是本文档「给人读、更重要」的承诺所在。

生产与评审

• 文字层由主会话 / opus 写，务必自洽——后续 AI 消费它，缺图也要能读懂全部设计。
• 图层每图一 opus 子代理：克隆 atlas 金样板 → 画 → 跑复验脚本 → 对抗自检；house style 与散文铁律（连同正反例）随 prompt 一起传下去（只传「画图」不够，输出会回退 AI 味）。
• 评审：这份文档仍过双评审门（Codex + Opus，Codex 挂回落 Opus 单评），对象 = 这一份文档。
• 命名 docs/agent-specs/YYYY-MM-DD-<功能>-设计.md；SVG / HTML 入同名或共享 assets/（顶层文档 → 子目录 assets 单向下引，别跨子目录引图）。

取代关系

取代旧的 -review.md + -execution.md 双档（2026-06-24 创始人定）。存量双档作 trace 留 git / _archive，不强行合并历史；新功能一律产这一份。

相关：architecture-diagram-atlas.md（house style / 复验脚本 / 三范式防漂移）、wave-close-checklist.md（收口同步纪律）、../workflows/ai-development-protocol.md（设计在协议中的位置）。