design-doc

Design Doc Writer

将产品和技术背景转化为一份尽可能精简的设计，让能力出色的实现 Agent 能够安全地执行。

撰写前，请完整阅读共享设计约定。 其中定义了就绪状态、证据、权限、故事语法，以及下游 feature-delivery 约定。

工作流

1. 梳理对话。 提取问题、目标、约束、非目标、决策及其理由、被否决的方向和未解决的决策。保留用户明确做出的选择。

2. 以事实为依据设计。 阅读仓库说明以及相关的愿景、架构、代码、测试、架构、模式和配置。先搜索，再做推测。核实重要路径、当前签名、所有权和集成点。

3. 仅澄清重要缺口。 只有当某个答案会实质性影响范围、架构、兼容性、安全性或故事边界，且无法通过查找或安全推断得出时，才提出简洁的分组问题。否则说明假设。

4. 综合设计。 说明选定的行为和约定，而不是探索过程的记录。除非设计中给出了偏离的理由，否则优先采用仓库中已有的模式。

5. 编写规范故事。 使用稳定的 ID，确保每个故事都能根据复制到其中的 issue 正文独立实现。在保证每个故事对应一个依赖顺序明确、连贯的结果的同时，尽量减少故事数量。

6. 验证。 从已安装的技能集或仓库技能集中解析 design-to-issues/scripts/story_contract.py，并运行：

   python3 <story-contract-script> <design-doc> \
     --repo-root <repository-root> --mode author
   

   完成前修复所有验证失败。

7. 保存为草稿。 除非用户或仓库指定了其他路径，否则写入 docs/design/<short-kebab-case-name>.md。新增和修订的内容均保留为 Draft；本技能不会将其提升为 Revised。

自适应文档结构

仅使用包含有用设计信息的章节。典型文档如下：

# Feature name

**Status:** Draft

## Problem and Goals
## Scope and Non-Goals
## Decisions and Rationale
## Architecture and Contracts
## Integration and Behavior
## Risks and Verification
## Open Questions
## User Stories
## Changelog

根据功能调整或合并标题。在有实际意义时，纳入安全、隐私、数据所有权、迁移、兼容性、性能、可观测性、发布和回滚等内容。在有助于解释重大决策时，纳入备选方案。省略无关章节，不要用模板内容填充。

仅在能消除实现歧义时，才提供精确示例、数据结构、序列或图表。将拟议接口标明为拟议内容；不要将其描述为仓库当前事实。

故事指南

遵循共享约定中的确切故事结构和依赖语法。此外：

• 在验收标准中写明行为结果，在实现上下文中提供实现指导。
• 让标准具备二元性且可观察。不要将文件放置位置、lint 是否通过，或“正常工作”之类的模糊表述用作行为验收标准。
• 在验证中列出适合该故事的测试、命令、浏览器／设备检查、迁移或运维证据。无需每个故事都要求所有验证方式。
• 仅当故事会改变文档或运维相关内容时，才纳入相应工作。
• 修订共享架构或约定文本时，更新所有受影响的故事。故事内容是 issue 同步所哈希并交付的内容。
• 修订时保留现有 ID。新增、删除、推迟或实质性调整故事范围，必须遵守共享约定中的权限规则。

修订行为

收到处理评审意见的请求时，应根据证据和原始意图评估每项阻塞性意见。用最小且连贯的改动满足必要的不变量；评审者的建议并非自动等同于解决方案。仅在收到请求或确有明显益处时，才采纳值得考虑的非阻塞性建议。

在评审文档或协调者交接记录中详细说明每项意见的处理方式。仅在设计文档中添加简短的变更记录，例如：

- 2026-07-28: Addressed review pass 2; clarified token ownership and updated AUTH-002.

将文档保留为 Draft，以便后续进行独立评审。

报告

返回设计文档路径、决策和故事顺序的简要摘要、验证结果，以及仍需用户作出的任何决定。不要开始同步问题或实施。