diegosouzapw 规格访谈技能
概述
通过深入的苏格拉底式访谈，将草稿规格说明转化为完整、可执行的技术文档。访谈完成后自动创建 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 后，用户可以：
审查与细化
- 检查生成的 proposal 和 specs
- 根据需要进行调整和补充
实施变更
- 使用
/openspec:apply或/openspec-apply命令 - 系统将根据 tasks.md 逐步实施
- 使用
归档变更
- 实施完成后使用
/openspec:archive或/openspec-archive - 将 spec deltas 合并到
openspec/specs/中
- 实施完成后使用
技术约束
- 路径表示: 使用双引号和正斜杠
/ - 搜索工具: 优先使用
rg而非grep - Git 策略: 除非明确要求，否则不执行 commit 或分支操作
- 代码理解: 遵循先读后写（Read-before-Write）原则
提问原则
- 深度优先: 避免显而易见的问题，挖掘隐藏假设与风险
- 结构化: 按工程原则 → 技术细节 → 风险权衡的顺序提问
- 引导式: 帮助用户思考"为什么"而非仅仅"是什么"
- 务实性: 关注可落地性，避免过度理论化
- 上下文感知: 根据项目类型调整访谈重点（API/CLI/库/应用）
使用示例
触发方式
- "帮我完善这个 plan"
- "对这个技术方案进行深度访谈"
- "创建规格提案"
- "spec-driven development"
典型对话流程
步骤 1: 启动访谈
用户: 帮我完善这个 plan
系统: 已读取
plan.md。该项目计划构建一个用户管理 API。在开始访谈前，请确认：这是一个面向公网的 API 还是内部服务？
步骤 2: 深度提问
用户: 内部服务
系统: 明白。关于认证机制，内部服务通常有几种选择：
- 服务间共享密钥（简单但安全性较低）
- mTLS（高安全性但配置复杂）
- 内部 OAuth 2.0（灵活但需要额外基础设施）
考虑到您的团队规模和运维能力，倾向于哪种方案？或者是否已有统一的内部认证标准？
步骤 3: 工程原则审查
系统: 关于用户角色管理，计划支持多少种角色？这是 MVP 必需的功能吗？
根据 YAGNI 原则，如果初期只需要管理员和普通用户两种角色，建议先实现简单的二元权限模型，后续再扩展为 RBAC。这样可以减少 30-40% 的开发时间。您的看法如何？
步骤 4: 创建 OpenSpec Proposal
系统: 访谈完成！现在为您创建 OpenSpec proposal...
[调用 /openspec:proposal 或等效命令]
✅ 已创建 proposal:
openspec/changes/user-management-api/后续步骤：
- 审查
proposal.md和tasks.md- 使用
/openspec:apply开始实施- 完成后使用
/openspec:archive归档
与 OpenSpec 的集成优势
- 需求锁定: 访谈结果固化为 proposal，避免需求在聊天历史中丢失
- 可追溯性: 所有决策和权衡都记录在 proposal 中
- 可审查性: 团队成员可以审查 proposal 而无需阅读代码
- 增量开发: 通过 spec deltas 清晰展示每次变更的影响范围
- 文档同步: 归档后自动更新 living specs，保持文档与代码一致
最佳实践
- 准备充分: 在访谈前准备好业务上下文和约束条件
- 诚实回答: 对不确定的问题，可以要求提供多个选项及其权衡分析
- 迭代细化: proposal 创建后可以继续访谈进行细化
- 团队协作: 将 proposal 分享给团队成员进行 review
- 持续归档: 完成的变更及时归档，保持 specs 目录的准确性