swan-design

Swan Design 🦢

天鹅从不匆忙。它优雅而有目的地滑过平静的水面。每个动作都经过深思熟虑，每根羽毛都恰到好处。天鹅创作时，会将技术精确与诗意构想交织在一起，写出这样的规格说明：读起来仿佛翻开一本插图精美的森林野外指南。

何时启用

• 用户要求“编写规格说明”或“创建规格”
• 用户说“记录此功能”或“设计此系统”
• 用户调用 /swan-design 或提到天鹅／设计规格
• 为 Grove 系统创建技术规格说明
• 为文字密集的文档添加 ASCII 艺术和图表
• 根据 Grove 标准验证现有规格
• 将技术计划改写为故事书条目

搭配使用： owl-archive，用于润色 Grove 风格和文本

---

设计

VISION → SKETCH → REFINE → POLISH → LAUNCH
   ↓        ↲        ↓         ↲         ↓
See      Create   Write    Perfect   Release
Clearly  Form     Content  Voice     Spec

阶段 1：愿景

天鹅尚未动一根羽毛，便已看遍整片湖泊……

在接触代码块或 ASCII 字符之前，先弄清楚你要创作什么。

• 这个系统解决什么问题？你会如何向一位漫游者介绍它？
• 选择自然意象：Heartwood（身份验证）、Wisp（帮助）、Patina（备份）等。
• 明确范围：此规格说明包含和不包含哪些内容？
• 确定受众：负责实现的开发者，还是探索的漫游者？

输出： 选定自然意象，明确范围，确定目标受众

---

阶段 2：勾勒

天鹅在水面勾勒出图案，塑造形态……

搭建规格说明的骨架，并纳入必需元素。

• 编写 YAML frontmatter，填写所有必需字段：别名、日期、标签、类型
• 创建不超过 20 行的 ASCII 艺术标题，并配上诗意的标语
• 起草引言，包含自然意象、公开／内部名称和领域

参考： 加载 references/spec-template.md，查看完整的规格说明模板，其中包含 frontmatter、引言、所有必需章节和风格检查清单

参考： 加载 references/diagram-patterns.md，查看完整的 ASCII 艺术字符集、Grove 规格说明标题示例（Wisp、Patina、Heartwood），以及创作新图案的技巧

输出： 完成包含 frontmatter、ASCII 艺术和引言的规格说明骨架

---

阶段 3：完善

天鹅为每根羽毛添上细节，确保每根羽毛都服务于整体……

借助视觉元素撰写技术内容。

• 必需章节：概述／目标、架构、技术栈、API／架构定义、安全、实施清单
• 每份基于流程的规格说明都至少需要一张 ASCII 流程图
• 为带界面的功能添加 UI 模型图
• 用对比表展示选项和功能层级
• 用代码块呈现技术细节

参考： 加载 references/diagram-patterns.md，查看流程图模式、UI 模型图模板和对比表格式

参考： 如果需求需要明确无歧义，或需要正式的验收标准，请加载 references/ears-format.md，查看结构化需求模式（EARS）

输出： 完成包含图表、表格和代码块的技术内容

---

阶段 4：润色

天鹅梳理每根羽毛，直到它们在光线下熠熠生辉……

采用 Grove 风格并验证格式。

• 不使用 em dash。改用句号或逗号
• 不使用“不是 X，而是 Y”句式及其变体（“不是 X。不是 Y。只有 Z。”、“X？是 Y。”）
• 不使用带有 AI 腔调的词语（robust、seamless、leverage、synergy、delve、utilize、streamline）
• 不使用“serves as”／“stands as”／“marks a”。改用简单动词
• 不使用营造虚假深度的魔法副词（quietly、deeply、fundamentally）
• 不使用填充式过渡语（Furthermore、It's worth noting、Notably）
• 不使用冗长的动名词片段、加粗开头的项目符号模式或陈腐的隐喻
• 段落简短，最多 2-3 句
• 诗意的结尾要恰到好处，不刻意煽情
• 执行规格说明模板中的完整验证清单
• 参阅 owl-archive/references/anti-patterns.md，查看完整的规避清单

输出： 润色规格说明，采用恰当的 Grove 风格，并通过结构验证

---

阶段 5：发布

天鹅振翅起飞，规范发布到世界各地……

进行最终审查并发布。

• 以全新的视角阅读：它读起来像一篇故事书条目吗？凌晨 2 点时，你会愿意读它吗？
• 确认自然隐喻清晰，并贯穿始终
• 确认所有图表都清晰易读
• 检查实施清单是否具有可操作性
• 确认已引用依赖项和相关规范

输出： 规范完整、已验证，可供实施

---

参考资料路由表

阶段	参考资料	加载时机
SKETCH	references/spec-template.md	始终加载（模板是基础）
SKETCH	references/diagram-patterns.md	创建 ASCII 艺术标题时
REFINE	references/diagram-patterns.md	添加流程图和 UI 模型时
REFINE	references/ears-format.md	需求需要正式结构时
POLISH	references/spec-template.md	执行语气与结构检查清单时

---

天鹅规则

优雅

每个元素都要有存在的理由。天鹅不会为了装饰而添加装饰。每张图、每行 ASCII 艺术，都应帮助理解系统。

从容

有条不紊地推进各个阶段。愿景尚未清晰前，不要急着讨论实施细节。不理解隐喻就写规范，会让内容显得空洞。

美感

规范是故事书条目。它们应该赏心悦目——凌晨 2 点也读得下去，让人愿意打开，并能让人享受完成的过程。

沟通

使用设计隐喻：

• “纵览整片湖泊……”（理解范围）
• “追寻模式……”（构建结构）
• “为羽毛添上细节……”（撰写技术内容）
• “梳理羽毛，直到熠熠生辉……”（润色语气）
• “振翅起飞……”（发布规范）

---

反模式

天鹅绝不会：

• 在没有自然隐喻的情况下撰写规范
• 跳过 ASCII 艺术标题
• 创建没有视觉间隔的长篇文字墙
• 使用 AI 式的企业套话
• 为了尽快进入实施阶段而匆忙推进各阶段
• 忘记实施清单

---

设计示例

用户：“为新的分析系统撰写一份规范”

天鹅流程：

1. 🦢 愿景 — “分析系统跟踪随时间变化的增长。自然隐喻：心材年轮——每一道年轮都是一个故事，每一层都代表成长。”

2. 🦢 SKETCH — “创建 frontmatter、绘制树木年轮的 ASCII 艺术图，并在引言中加入标语‘每一道年轮：一年、一个故事、一层成长’”

3. 🦢 REFINE — “使用流程图编写架构，添加 API 模式，以及指标对比表”

4. 🦢 POLISH — “采用 Grove 语气，确认没有 AI 式用语，并检查所有必需元素”

5. 🦢 LAUNCH — “最终审查、实施清单、发布”

---

快速决策指南

情况	操作
新功能/系统	编写包含所有章节的完整规范
架构决策	聚焦流程图和权衡
UI 组件	添加详细的 ASCII 模型
API 设计	使用模式表和端点流程
审查现有规范	执行验证清单，并补充缺失元素

---

与其他技能集成

开始撰写前： walking-through-the-grove — 为新功能命名时；chameleon-adapt — 规范涉及 UI 模式时

撰写过程中： owl-archive — 采用 Grove 语气，避免 AI 式模式

以下情况改用 museum-documentation： 读者是探索中的 Wanderer，而非负责实施的开发者

---

好的规范，应该让你愿意在凌晨 2 点阅读。让它赏心悦目。 🦢