菜单
帮助用户按照codespec的sdd规范完成story设计，输出或完善proposal/delta-spec/delta-design/tasks。支持多次重入场景，能够接续执行步骤和问答进度。负责生成文档，不执行代码开发工作。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
远程访问工作流。首次访问远端、SSH、跳板机、上传下载或远程部署时，先发现并注册可复用节点，再执行和验证远端操作。
开展深度研究，支持多轮迭代搜索、交叉验证、结构化报告输出。适用于需要进行全面分析（需包含 10 个以上来源）、验证论断或比较不同方法的情况。触发条件包括“深度研究”、“全面分析”、“研究报告”、“比较 X 与 Y”或“分析趋势”。请勿用于简单的查找、调试或只需 1-2 次搜索即可解答的问题。
快速代码库探索专家，用于通过模式查找文件、搜索代码关键字，以及回答有关代码库结构的问题。适用于快速定位文件、理解代码组织或探索陌生代码库。触发条件：分析项目、意图识别、代码流程分析、调用栈分析、时序分析。
深度分析与规划专家。输出 RCA 报告、设计文档、执行计划（含伪代码级修改指引）。当需要分析问题根因、制定实施方案或生成结构化文档时使用。
根据经过批准的 pptx-craft 计划生成高质量 HTML 幻灯片、运行转换与布局 QA，并交付 pages.pptx。必须在 pptx-craft workflow 的 designer 阶段调用。
为 pptx-craft 生成严格可验收的内容大纲、页面描述、页面类型和布局意图。只能输出 UTF-8 的 ppt_plan.md；当由 pptx-craft 调用时作为 planner 阶段执行。
| name | sdd-design-story |
| description | 帮助用户按照codespec的sdd规范完成story设计，输出或完善proposal/delta-spec/delta-design/tasks。支持多次重入场景，能够接续执行步骤和问答进度。负责生成文档，不执行代码开发工作。 |
SDD 是 specification driven design，本 skill 能够在用户需要做 story 设计的时候，用引导和协作的方式，引导用户完成 proposal/delta-spec/delta-design 的设计，并完成 tasks 分解。为后续直接编码提供设计输出。 本 skill 的内容不包含编码。
需求澄清 → 增量规格 → 增量设计 → 任务规划 → 一致性验证
(proposal) (delta-spec) (delta-design) (tasks) (validation)
每个步骤的标准流程：
步骤 1-4：第一阶段：准备/收集 → 第二阶段：交互式澄清（必须执行）→ 第三阶段：生成文档 → 第四阶段：用户确认（必须执行）→ 第五阶段：校验（可选）
步骤 5：第一阶段：读取文档 → 第二阶段：AI 自主分析（必须执行）→ 第三阶段：生成验证报告 → 第四阶段：提供修订建议
核心特性：
SDD 方法论背景：详见 references/sdd-methodology.md
本 skill 使用状态机来追踪工作流进度和文档状态，确保工作流的可追溯性和可恢复性，同时支持多次重入场景。
当前状态结构：详见 templates/state.json
状态说明：
current_step：当前所处的步骤iteration：当前迭代次数（用于追踪修订，每次修订 +1）files：各文档的状态信息
status：文档状态
pending：待生成in_progress：生成中completed：已完成modified：已修订version：文档版本号last_action：最后一次执行的操作next_action：建议的下一步操作history：操作历史记录存储位置：{项目根目录}/codespec/changes/{工作目录}/state.json
持久化时机：
时间戳更新规则：
last_modified 字段2026-02-13T14:30:00+08:00Get-Date -Format "yyyy-MM-ddTHH:mm:ssK"date +"%Y-%m-%dT%H:%M:%S%:z"history 数组时，每条记录的 timestamp 字段也必须使用当前实际时间恢复机制：
适用场景：每个步骤完成文档生成后，必须按照以下规范更新 state.json
更新步骤：
获取当前时间戳
Get-Date -Format "yyyy-MM-ddTHH:mm:ssK"
# 输出示例：2026-02-13T14:30:00+08:00
date +"%Y-%m-%dT%H:%M:%S%:z"
# 输出示例：2026-02-13T14:30:00+08:00
更新 state.json 字段
current_step = 当前步骤名称（如："proposal"、"delta-spec"、"delta-design"、"tasks"、"validation"）{文档名}.status = "completed"（或 "modified" 如果是修订）{文档名}.version = 当前版本号（首次生成时为 1，修订时为原版本号）{文档名}.last_modified = 当前实际时间（ISO8601 格式，北京时间）last_action = "生成 {文档名}"（或修订时的描述）next_action = 下一步操作描述history 数组中添加新记录展示更新结果
注意事项：
每次交互开始时，AI 应该展示当前状态：
📊 当前进度：
✅ 步骤 1：proposal.md（已完成，版本 1）
🔄 步骤 2：delta-spec.md（进行中）
⏳ 步骤 3：delta-design.md（待开始）
⏳ 步骤 4：tasks.md（待开始）
⏳ 步骤 5：validation.md（待开始）
📁 已生成文件：
- proposal.md（最后修改：{{实际修改时间}}）
🎯 下一步：
交互澄清 delta-spec 的业务规则细节
💡 可用指令：
- "查看进度" 或 "show progress"：显示当前进度和状态
- "查看历史" 或 "show history"：显示操作历史
- "回退到步骤 X" 或 "back to step X"：回退到指定步骤
- "重新开始" 或 "restart"：清空状态，重新开始
| 当前状态 | 用户指令 | 新状态 | 说明 |
|---|---|---|---|
| proposal | "生成 delta-spec" | delta-spec | 进入步骤2，必须交互澄清 |
| delta-spec | "修订 proposal" | proposal | 回到步骤1，iteration+1，proposal.md status=modified |
| delta-spec | "生成 delta-design" | delta-design | 进入步骤3，必须交互澄清 |
| delta-design | "更新 delta-spec" | delta-spec | 回到步骤2，iteration+1，delta-spec.md status=modified |
| delta-design | "生成 tasks" | tasks | 进入步骤4，必须交互澄清 |
| tasks | "修订 delta-design" | delta-design | 回到步骤3，iteration+1，delta-design.md status=modified |
| tasks | "验证一致性" | validation | 进入步骤5 |
| validation | "调整 tasks" | tasks | 回到步骤4，iteration+1，tasks.md status=modified |
| validation | "完成" | completed | 工作流结束 |
| 任意 | "回退到步骤 X" | 步骤 X | 修改 current_step，记录跳转历史 |
| 任意 | "重新开始" | proposal | 清空所有状态，iteration=1 |
重要规则：
modified用户可以使用以下指令查询和管理工作流状态：
| 指令 | 说明 | 示例 |
|---|---|---|
| "查看进度" / "show progress" | 显示当前进度和状态 | 查看进度 |
| "查看历史" / "show history" | 显示操作历史 | 查看历史 |
| "回退到步骤 X" / "back to step X" | 回退到指定步骤（1-5） | 回退到步骤 2 |
| "重新开始" / "restart" | 清空状态，重新开始 | 重新开始 |
| "保存状态" / "save state" | 手动保存当前状态 | 保存状态 |
| "当前状态" / "current state" | 显示完整的 state.json 内容 | 当前状态 |
在对话中维护以下关键信息：
状态跟踪变量：
current_step: 当前步骤（0-5）work_dir: 当前工作目录（如 US202601010015-增加逻辑多租）qa_progress: 各步骤问答进度记录generated_docs: 已生成的文档列表last_action: 上次执行的操作（问答/生成/跳转）当 skill 被重新激活时，执行以下检测：
./codespec/changes/ 目录，查找最近的工作目录重入检测流程：
如果对话历史中有状态信息：
→ 恢复 last_action 和 qa_progress
→ 提示用户："检测到未完成的工作，当前在步骤 X，是否继续？"
否则：
→ 扫描 changes/ 目录，找到最近的工作目录
→ 检查已生成的文档
→ 推测当前步骤（如已有 proposal.md 但无 delta-spec.md → 步骤 2）
→ 提示用户："发现工作目录 {work_dir}，已生成 {docs}，是否继续？"
详细的重入恢复逻辑：详见 references/common-guidance.md
核心原则：每个步骤的"交互式澄清"阶段是必须执行的，不能跳过。
执行规则：
禁止行为：
完成判断标准：
交互工具选择:
question工具，禁止直接列举问题ask_user工具，则必须使用ask_user工具，禁止直接列举问题文档生成必须在以下条件满足后才能执行：
核心原则：步骤 1-4 的文档生成后，必须等待用户确认才能进入下一步。
执行规则：
确认提示模板：
✅ {文档名} 已生成
📍 文档位置: {文档路径}
📋 请 review 文档内容，确认是否符合预期
💡 可用指令：
- "确认" 或 "继续" → 确认文档，进入下一步
- "修改: [具体修改意见]" → 根据您的反馈调整文档
- "重新生成" → 重新生成当前文档
- "查看文档" → 显示文档完整内容
⏸️ 等待您确认后再继续...
步骤 5（一致性验证）的特殊性：
步骤 5 的执行规则：
本 skill 支持多次重入场景，需要维护以下状态信息：
在对话中维护以下关键信息：
状态跟踪:
current_step: 当前步骤（0-5）work_dir: 当前工作目录（如 US202601010015-增加逻辑多租）qa_progress: 各步骤问答进度记录generated_docs: 已生成的文档列表last_action: 上次执行的操作（问答/生成/跳转）当 skill 被重新激活时，执行以下检测：
./codespec/changes/ 目录，查找最近的工作目录重入检测流程：
如果对话历史中有状态信息：
→ 恢复 last_action 和 qa_progress
→ 提示用户："检测到未完成的工作，当前在步骤 X，是否继续？"
否则：
→ 扫描 changes/ 目录，找到最近的工作目录
→ 检查已生成的文档
→ 推测当前步骤（如已有 proposal.md 但无 delta-spec.md → 步骤 2）
→ 提示用户："发现工作目录 {work_dir}，已生成 {docs}，是否继续？"
详细的重入恢复逻辑：详见 references/common-guidance.md
注意：步骤 0 不需要场景识别，因为所有场景都需要相同的工作目录识别流程。
目录结构确认与创建
{root}/codespec 目录是否存在codespec 目录及其子目录：
specs/ - 存放全量规格和设计文档changes/ - 存放工作目录（各个 story 的设计文档）archives/ - 存放已归档的工作目录工作目录识别
{root}/codespec/changes 目录（排除 archives 子目录）US编号-功能名）并自动创建工作目录创建规范
{root}/codespec/changes/ 目录下US编号-功能名{root}/codespec/changes/US202601010001-初始化服务项目框架{root}/US202601010001-初始化服务项目框架）全量规格确认
{root}/codespec/specs/spec.md 是否存在异常处理：详见 references/exception-handling.md
将模糊的需求转化为清晰的需求证据。
进度展示模板：
📊 当前进度：
✅ 步骤 1：proposal.md（已生成，待确认，版本 1）
🔄 步骤 2：delta-spec.md（待开始）
⏳ 步骤 3：delta-design.md（待开始）
⏳ 步骤 4：tasks.md（待开始）
⏳ 步骤 5：validation.md（待开始）
📁 文档状态：
- proposal.md（状态：⏸️ 已生成，待确认，版本 1，最后修改：[时间戳]）
🎯 当前任务：
等待用户确认 proposal.md
💡 可用指令：
- "确认" 或 "继续" → 确认文档，进入下一步：生成 delta-spec.md（需要交互澄清）
- "修改: [具体修改意见]" → 根据您的反馈调整文档
- "重新生成" → 重新生成当前文档
- "查看文档" → 显示文档完整内容
详细问答逻辑：详见 references/q-a-proposal.md
将需求证据转化为可验收的业务规则增量。
codespec/specs/spec.md 获取项目总体设计信息详细问答逻辑：详见 references/q-a-delta-spec.md
将业务规则转化为可实施的技术方案。
codespec/specs/design.md）详细问答逻辑：详见 references/q-a-delta-design.md
将技术方案拆分为 AI Agent 可执行的任务。
详细问答逻辑：详见 references/q-a-tasks.md
自主检查前面步骤的工作质量，识别问题并提供修复建议，确保文档链的一致性和完整性。
重要说明：
读取所有相关文档
AI 自主分析（必须执行）
生成 validation.md
提供修订建议和跳转选项（必须执行）
current_step 设置为 "completed"next_action 设置为 "SDD 设计流程已完成！可以开始执行 tasks.md 中的开发任务"用户可以随时跳转到任意步骤：
"修订 proposal" → 跳转到步骤 1
"更新 delta-spec" → 跳转到步骤 2
"修改 delta-design" → 跳转到步骤 3
"调整 tasks" → 跳转到步骤 4
"验证一致性" → 跳转到步骤 5
"跳到步骤 X" → 直接跳转到指定步骤
识别以下触发词模式：
在执行跳转前，检查以下条件：
前置条件检查
上下文恢复
正常流程（首次执行或无问题）：
验证发现问题后的修订循环： 详见 references/step-5-validation.md 中的"修订循环机制"章节
单次提问控制：
渐进式披露：
进度记录格式：
[步骤 1 问答进度]
- 第 1 轮：业务背景、目标用户 ✅
- 第 2 轮：功能范围、验收标准 ✅
- 第 3 轮：影响分析、DFX约束 ✅
重入时的问答恢复：
详细技巧详见 references/common-guidance.md
本 skill 定义了以下异常场景的处理流程：
详细的异常处理流程详见 references/exception-handling.md
详细的输出示例详见 references/output-examples.md