software-design

软件设计

此技能会将 PRD 和已发布的待办事项列表转化为清晰的设计：命名明确的模块、定位清楚的接缝、明确的测试策略，以及可直接用于 TDD 的议题正文，让 /tdd 或 /implement 能够一次处理一个行为。

它是一个编排封装层：深模块／接缝相关词汇和可测试性原则由 /codebase-design 提供；通用语言基础由 /domain-modeling 提供。此技能会调用这两者，并补上它们缺少的衔接部分——前置条件检查、前端路由标记、确认循环，以及批量修改跟踪器。

后端服务和具有真实 I/O 边界的代码是最适合使用此技能的场景。UI 组件树应路由至 /frontend-design——此技能会添加路由区块并移交，不负责设计组件。

---

何时运行

在以下条件满足后运行：

• 已有 PRD 或史诗（位于对话中、文件中或作为父议题）。
• /to-issues 已为该史诗发布待办事项列表。
• 已有 CONTEXT.md，其中包含议题将使用的领域词汇。

当待办事项列表看起来合理地涉及两个或更多模块，且模块／接缝的选择仍未明确时，此技能最能发挥作用。如果不满足这些条件，请应用下文的提前退出规则，或建议用户运行缺少的前置技能。

---

何时跳过

满足以下任一条件时，此技能会提前退出：

• 此更改属于单模块调整、文案编辑、单行错误修复，或任何能在一个现有模块内完成且不跨越接缝的工作。
• 待办事项列表中有 ≤2 个议题，且它们涉及同一个领域概念。
• 工作属于探索性或临时性工作，且边界有意设计为可随时舍弃。

提前退出时有两种处理路径：

• 后端单模块——在每个受影响的议题上发布 design-skipped: single-module change，并告知用户直接运行 /tdd 或 /implement。
• 仅 UI——在每个受影响的议题上发布 routed-to: /frontend-design，并告知用户接下来运行 /frontend-design，然后运行 /tdd 或 /implement。

即使提前退出，第 2 步的标记处理仍会针对每个前端相关议题执行。

---

调用时的自检

开始任何操作前，先验证前置条件：

1. PRD 或史诗上下文——是否存在 PRD 文件、父议题，或说明该功能的对话上下文？如果没有，请停止并告知用户先建立 PRD（例如通过 /to-prd）。
2. 存在 CONTEXT.md——如果文件不存在，请停止并告知用户先运行 /grill-with-docs 来建立领域词汇。
3. 待设计的议题——根据 docs/agents/issue-tracker.md，通过跟踪器获取该史诗的未关闭议题。如果没有议题，请停止并告知用户先运行 /to-issues。
4. 可能涉及多个模块——阅读议题集合。如果看起来可能涉及 2 个或更多模块，则继续。否则应用上述提前退出规则。

---

工作流

1. 收集上下文

按顺序阅读：

• CONTEXT.md，了解议题中使用的领域词汇
• docs/adr/，了解受影响领域此前的架构决策
• PRD（议题正文、文件或对话上下文）
• 该史诗中所有未关闭的议题，包括评论和标签

在阅读词汇表之前，不要开始设计。所有模块名称、接口和改写后的议题都必须使用其中的术语。

质疑沿袭下来的选择。 CONTEXT.md、ADR 和当前技术栈往往早于此技能。如果既有决策不适合当前待办事项列表——例如持久化模型不合适、同步／异步边界不合适，或技术栈与即将划定的接缝相冲突——请明确指出这种不匹配。提出一个方案，并用浅显的语言说明权衡；让用户选择接受（并将修订工作交由 /grill-with-docs 处理，以更新 ADR）或否决。不要仅仅因为某个不合适的选择已经被记录下来，就默默沿用。

2. 为带有前端特征的问题添加路由信息块

在进行任何模块／接缝工作之前，先扫描所有未关闭的问题。当以下三个信号中有两个成立时，该问题即为带有前端特征的问题：

1. 输出界面可见 — 页面、屏幕、组件、模态框、表单、图表、主题或布局。关键词线索：renders、displays、shows、page、screen、component、modal、form、button、layout、theme、responsive。
2. 模块职责是呈现 — 该问题所属的集群落在一个其变更原因只有呈现的模块中。纯数据模块即使有下游 UI 消费者，也不计入。
3. 验收标准提到了视觉或交互行为 — 颜色、间距、焦点状态、悬停、动画、无障碍、响应式断点。

对于每个带有前端特征的问题，都要在正文中添加 **Frontend design** 路由信息块 — 即使待办事项足够少，技能的其余部分会提前退出，也要添加。统一性胜过优化。

信息块包含：Stack（取自项目的包清单）、Intent（转述 Behavior 行）、Aesthetic direction（docs/design/direction.md 的路径）、Token authority（从该文件中读取的路径），以及 Review（仅当 AC 明确提及 a11y／对比度／设计审查时才需要）。完整字段规范见 skills/engineering/frontend-design/direction-doc-format.md。

根据项目的清单和方向文档，按原样填写字段值。不要询问用户有关字体、颜色或动效的问题。仅涉及后端的问题无需添加信息块。

3. 按领域概念对问题进行分组

按问题涉及的概念进行分组。一个集群是一组连贯的职责，因相同原因而发生变化。使用 CONTEXT.md 中的领域名词为每个集群命名。

确定切分位置的一个信号是：哪些问题跨越通信边界（同步／异步、外部系统）？这属于接缝，而不是模块切分依据 — 它告诉你适配器应放在哪里。

4. 调用 /codebase-design，获取模块／接缝术语并进行设计

调用 /codebase-design，将深模块／接缝框架应用于已分组的问题集。模块／接缝术语、删除测试、分解启发式、适配器策略和可测试性原则都在其中 — 而不在本文档中。

对于每个模块，列出：

• 名称 — 来自领域词汇
• 职责 — 一个变更原因
• 接口 — 命令、查询、事件（而非实现）
• 不变量 — 该模块负责的规则
• 依赖于 — 其他模块或接缝
• 不得依赖 — 例如传输层、持久化层

5. 调用 /domain-modeling，以通用语言为依据

将以下内容交给 /domain-modeling：

• 第 4 步中的候选模块名称
• 设计过程中确定的所有接口操作名称和事件名称
• 当前 CONTEXT.md 术语表，作为参考

预期返回：

• 根据项目的通用语言确认或纠正每个术语（例如“OrderPlaced，而非 OrderCreated — 参见 CONTEXT.md §Events”）
• 列出所有已提出但尚未收录在 CONTEXT.md 中的术语；每个术语都需要在本次会话之前或之后通过 /grill-with-docs 提取

向用户展示模块映射之前，先纳入规范术语。任何标记为新增的术语都在第 7 步中列出。

6. 与用户确认

仅使用第 5 步确认的规范术语，以简短摘要的形式展示模块映射。询问：

• 职责划分是否合理？
• 是否缺少模块，或是否有职责合并得过于宽泛？
• 接缝位置是否符合预期的变更位置？

反复迭代。未经批准，不要继续第 7 步。

7. 提取值得长期记录的内容

当设计讨论中出现新的领域术语或难以取舍的权衡时，不要自行记录。提出这些内容，并交由负责的技能处理：

• 新的领域术语 → “这个术语不在 CONTEXT.md 中。现在按 /grill-with-docs 的规范记录，还是暂缓？”
• 难以撤销且确有其他选项的权衡 → “这似乎值得写入 ADR。现在通过 /grill-with-docs 编写 ADR，还是暂缓？”

CONTEXT.md 和 docs/adr/ 由 /grill-with-docs 负责维护。

8. 调用 /council 进行对抗性设计评审（仅供参考）

将第 6 步确认的模块图，以及迄今提出的最有力的未解决异议交给 /council——包括难以撤销的边界决策、尚未解决的权衡，或团队已经自我说服而接受的任何结论。随着第 3–7 步逐步划分集群、命名模块并标记值得长期记录的内容，这些异议会自然浮现。

/council 会返回标准的四段式输出（Synthesis、Rationale、Panel Dissent、Confidence）。将 Panel Dissent 部分，以及任何指出设计讨论中尚未提及风险的综合观点，作为建议性的“评审小组异议”部分附上。将其与已确认的设计一并呈现给用户。询问用户是继续进行第 9 步，还是重新审视任何模块决策。由用户确认；此技能不负责确认。

仅供参考。 council 的输出不会阻止拆分 issue。它是额外证据，而非否决权。

优雅降级。 如果 Workflow 工具不可用、明确跳过 /council，或调用因任何原因失败，请在对话中注明跳过，并直接继续第 9 步。此子步骤是建议性补充，并非结构性要求。

9. 将 issue 正文改写为适用于 TDD 的格式

为每个 issue 改写正文。每个改写后的 issue 应描述一种可观察行为。必填字段按以下顺序排列：Module（采用第 5 步中的规范名称）、Behavior（行为主体 / 行为 / 价值）、Acceptance criteria（Given/When/Then，可独立验证）、Frontend design（第 2 步中盖章确认；纯后端 issue 省略）、TDD notes（按名称而非路径注明入口点、测试优先目标、边界情况、替身策略、必须不测试的内容列表）。

为行为、接口和类型命名，不要写文件路径或行号。用可观察的 Given/When/Then 形式说明系统应当做什么，而不是说明如何连接各部分。

拆分混合多个模块的 issue。拆分并改写后，为整组 issue 排序：先放 tracer bullet（用于证明端到端路径有效的 issue），然后是核心行为、边界情况，最后是集成。

10. 将所有变更作为单个批次提出

在向跟踪器或磁盘写入任何内容之前，先在对话中完整展示所有变更：

• 所有改写后的 issue 正文
• docs/design/<feature>.md 的设计计划内容

设计计划记录模块、边界、测试策略、不变量，以及一行式 issue 索引，并链接到每个改写后的 issue。它不重复 issue 正文——以 issue 跟踪器中的内容为准。

设计计划文件（docs/design/<feature>.md）按以下顺序包含：标题、状态/日期/epic 标头；Context（一段，仅包含领域词汇）；Domain Vocabulary Used（本计划依赖的 CONTEXT.md 中的术语）；Module Map（模块 → 职责 → 接口操作 → 边界）；Seams（跨越每个边界的内容，以及测试环境与生产环境中的适配器）；Invariants and Contracts（无论如何实现都必须成立的规则）；Testing Strategy（模块 → 测试入口点 → 测试级别 → 替身策略）；Issue Index（issue → 模块 → 一行式说明）；Open Questions（实现前或实现期间尚未解决的问题）。

等待明确批准。按用户要求进行行内修改。然后通过跟踪器（gh issue edit）和文件系统一次性写入所有内容。

未经一次性批次审批，此技能绝不修改外部状态。

过时的设计计划

设计计划是短期使用的实现脚手架。用户发现内容与实际情况不符时，会直接在文档中处理：在受影响的章节添加提示，然后通过 /grill-with-docs 提取可长期适用的经验。

最后一个问题发布后，将设计计划标记为 status: shipped。

---

每次设计会话的检查清单

[ ] Self-check passed (PRD, CONTEXT.md, issues, multi-module signal)
[ ] Domain vocabulary read from CONTEXT.md before naming anything
[ ] Frontend-flavored issues stamped (step 2) regardless of backlog size
[ ] /codebase-design invoked for module/seam framework (step 4)
[ ] /domain-modeling invoked before user confirmation; canonical terms incorporated (step 5)
[ ] Each module has exactly one reason to change
[ ] No issue mixes responsibilities from two modules
[ ] Issues ordered: tracer bullet → core behavior → edge cases → integration
[ ] New terms or trade-offs surfaced for /grill-with-docs extraction
[ ] /council invoked on confirmed design; Panel Dissent block appended and reviewed (or skip noted)
[ ] Full batch of rewrites previewed and approved before writing
[ ] Design Plan written and linked from affected issues