规格访谈技能

概述

通过深入的苏格拉底式访谈，将草稿规格说明转化为完整、可执行的技术文档。访谈完成后自动创建 OpenSpec proposal，实现规范驱动开发（Spec-Driven Development）。

核心功能

• 系统性需求访谈与细化
• 工程原则审查（KISS、YAGNI、DRY、SOLID）
• 技术方案设计与权衡分析
• 自动生成 OpenSpec proposal
• 风险识别与缓解策略制定

工作流程

1. 文档读取与分析

读取 plan.md 或用户指定的文档，分析：

• 核心业务目标和价值主张
• 现有技术方案的完整性
• 模糊或缺失的关键信息
• 潜在的技术债务和风险点

2. 系统性访谈

使用 AskUserQuestionTool 进行多维度深度访谈：

A. 工程原则审查（必须）

简单性检查（KISS & YAGNI）

• 该功能是否为 MVP 必需？是否可延后至后续迭代？
• 是否存在更简单的方案能达到 80% 的效果？
• 当前抽象层次是否合理？是否存在过度设计？

重复性识别（DRY）

• 识别相似逻辑模式，评估抽象为通用模块的可行性
• 配置模式是否会在项目中重复出现？
• 是否可以通过代码生成或模板减少重复？

架构健壮性（SOLID）

• 模块职责是否单一？是否承担过多责任？
• 接口设计是否支持未来扩展？
• 依赖关系是否合理？是否存在循环依赖风险？

B. 技术实现细节

• 技术栈选型依据与替代方案对比
• 数据结构与算法选择的性能影响
• 性能瓶颈预测与优化策略
• 第三方依赖的必要性、许可证与维护风险
• 测试策略（单元测试、集成测试、E2E、性能测试）

C. API 设计（如适用）

• API 标题与描述的清晰性
• 资源路径与操作的逻辑分组
• 请求/响应模型的完整性
• 认证与授权机制
• 错误处理与状态码设计
• 版本控制策略
• 分页、过滤、排序规范
• 幂等性与并发控制

D. UI/UX 设计（如适用）

• 用户交互流程的完整性与一致性
• 边界情况的 UI 反馈（加载、错误、空状态、网络异常）
• 响应式设计与跨设备兼容性
• 可访问性（WCAG 标准）
• 国际化与本地化需求

E. 风险与权衡

• 技术债务的可接受程度与偿还计划
• 安全性考量（认证、授权、数据加密、输入验证）
• 可维护性 vs 开发速度的平衡
• 成本估算（开发时间、基础设施、运维成本）
• 供应商锁定风险

F. 边缘情况与异常处理

• 网络异常、超时、重试机制
• 并发冲突与数据一致性保证
• 降级方案与容错设计
• 日志记录与监控策略
• 灾难恢复与业务连续性

G. 项目约定与规范

• Shell 脚本跨平台兼容性（Bash/PowerShell）
• 文档格式与元数据规范（Markdown frontmatter）
• 目标平台部署要求（Claude Code/Codex CLI）
• 代码风格与 Lint 规则
• Git 工作流与分支策略

3. 高风险操作检测

如规格涉及以下操作，将主动提醒：

⚠️ 高风险操作检测
操作类型：[文件删除 / Git 强制推送 / 环境变量修改 / 数据库结构变更 / 批量依赖更新]
影响范围：[具体描述]
建议措施：
  - 回滚方案：[具体步骤]
  - 备份策略：[备份内容与频率]
  - 测试要求：[测试环境与验证标准]
请确认是否继续执行。

4. 创建 OpenSpec Proposal

访谈完成后，系统将自动调用 OpenSpec 工作流创建 proposal：

调用方式

根据用户使用的 AI 工具，使用相应的命令：

Claude Code / Codex / Qoder / RooCode:

/openspec:proposal

Cursor / Continue / GitHub Copilot / Windsurf:

/openspec-proposal

其他工具（AGENTS.md 兼容）:

请创建一个 OpenSpec proposal

OpenSpec 输出结构

openspec/
├── changes/
│   └── <change-name>/
│       ├── proposal.md          # 变更提案
│       ├── tasks.md             # 任务清单
│       └── specs/               # 规格差异（delta）
│           └── <spec-name>/
│               └── spec.md      # 规格变更
└── specs/                       # 当前规格（归档后更新）
    └── <spec-name>/
        └── spec.md

生成的文件内容

1. Proposal (openspec/changes/<change-name>/proposal.md)

• 变更概述与业务价值
• 技术方案与架构决策
• 工程原则审查结果
• 风险评估与缓解措施
• 成功指标与验收标准

2. Tasks (openspec/changes/<change-name>/tasks.md)

• 实施任务清单（基于访谈结果）
• 优先级排序（高/中/低）
• 任务依赖关系
• 预估工作量

3. Spec Deltas (openspec/changes/<change-name>/specs/*/spec.md)

使用 delta 格式标记变更：

## 新增功能

+++ 新增的内容描述
+++ 包括接口定义、数据模型等

## 修改功能

--- 删除的旧内容
+++ 新增的替代内容

## 删除功能

--- 删除的内容描述

5. 后续工作流

创建 proposal 后，用户可以：

1. 审查与细化

   • 检查生成的 proposal 和 specs
   • 根据需要进行调整和补充

2. 实施变更

   • 使用 /openspec:apply 或 /openspec-apply 命令
   • 系统将根据 tasks.md 逐步实施

3. 归档变更

   • 实施完成后使用 /openspec:archive 或 /openspec-archive
   • 将 spec deltas 合并到 openspec/specs/ 中

技术约束

• 路径表示: 使用双引号和正斜杠 /
• 搜索工具: 优先使用 rg 而非 grep
• Git 策略: 除非明确要求，否则不执行 commit 或分支操作
• 代码理解: 遵循先读后写（Read-before-Write）原则

提问原则

1. 深度优先: 避免显而易见的问题，挖掘隐藏假设与风险
2. 结构化: 按工程原则 → 技术细节 → 风险权衡的顺序提问
3. 引导式: 帮助用户思考”为什么”而非仅仅”是什么”
4. 务实性: 关注可落地性，避免过度理论化
5. 上下文感知: 根据项目类型调整访谈重点（API/CLI/库/应用）

使用示例

触发方式

• “帮我完善这个 plan”
• “对这个技术方案进行深度访谈”
• “创建规格提案”
• “spec-driven development”

典型对话流程

步骤 1: 启动访谈

用户: 帮我完善这个 plan

系统: 已读取 plan.md。该项目计划构建一个用户管理 API。在开始访谈前，请确认：这是一个面向公网的 API 还是内部服务？

步骤 2: 深度提问

用户: 内部服务

系统: 明白。关于认证机制，内部服务通常有几种选择：

1. 服务间共享密钥（简单但安全性较低）
2. mTLS（高安全性但配置复杂）
3. 内部 OAuth 2.0（灵活但需要额外基础设施）

考虑到您的团队规模和运维能力，倾向于哪种方案？或者是否已有统一的内部认证标准？

步骤 3: 工程原则审查

系统: 关于用户角色管理，计划支持多少种角色？这是 MVP 必需的功能吗？

根据 YAGNI 原则，如果初期只需要管理员和普通用户两种角色，建议先实现简单的二元权限模型，后续再扩展为 RBAC。这样可以减少 30-40% 的开发时间。您的看法如何？

步骤 4: 创建 OpenSpec Proposal

系统: 访谈完成！现在为您创建 OpenSpec proposal…

[调用 /openspec:proposal 或等效命令]

✅ 已创建 proposal: openspec/changes/user-management-api/

后续步骤：

1. 审查 proposal.md 和 tasks.md
2. 使用 /openspec:apply 开始实施
3. 完成后使用 /openspec:archive 归档

与 OpenSpec 的集成优势

1. 需求锁定: 访谈结果固化为 proposal，避免需求在聊天历史中丢失
2. 可追溯性: 所有决策和权衡都记录在 proposal 中
3. 可审查性: 团队成员可以审查 proposal 而无需阅读代码
4. 增量开发: 通过 spec deltas 清晰展示每次变更的影响范围
5. 文档同步: 归档后自动更新 living specs，保持文档与代码一致

最佳实践

• 准备充分: 在访谈前准备好业务上下文和约束条件
• 诚实回答: 对不确定的问题，可以要求提供多个选项及其权衡分析
• 迭代细化: proposal 创建后可以继续访谈进行细化
• 团队协作: 将 proposal 分享给团队成员进行 review
• 持续归档: 完成的变更及时归档，保持 specs 目录的准确性

参考资源

• OpenSpec 官方文档
• OpenSpec 网站
• Spec-Driven Development 指南