claude-skills 的 Discovery Phase 详解：从 feature-forge 未知项到可执行 Jira 史诗的研究工作流-酒店常州论坛

claude-skills 的 Discovery Phase 详解：从 feature-forge 未知项到可执行 Jira 史诗的研究工作流

【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills

导读

Discovery Phase 是 claude-skills 工作流体系（Discovery → Planning → Execution → Retrospectives）中最前置、也是最容易被人忽视的一环：当 feature-forge 产出的规格中暴露出"现有知识无法回答"的未知项（需要用户访谈、竞品分析或技术 spike）时，Discovery Phase 为这些研究提供结构化框架，并把研究成果最终转化为落地的 Epic 与 Ticket。读完本文，你将掌握discovery:create/discovery:synthesize/discovery:approve三个命令的完整调用链、每一步生成的核心文档结构、以及贯穿全程的人工 Checkpoint 监督机制。

一、Discovery Phase 的定位：为什么不是每个功能都需要研究

Discovery Phase 在 docs/workflow/discovery-phase.md 中被明确定义为Optional research phase（可选研究阶段）。它不是默认必经之路——只有当 feature-forge 访谈环节暴露出无法从既有知识回答的问题时，这些未知项才会被路由到 Discovery。

触发 Discovery 的典型未知项包括：

用户访谈需求：无法确认"用户是否真的需要 X"这一类假设；
竞品分析需求：需要对比竞品才能确定的定位与取舍；
技术 Spike 待办：集成可行性、性能影响等无法靠推理得出结论的问题。

这种"按需触发"的设计避免了为每个功能都做一遍沉重的调研流程。与此对应，docs/workflow/planning-phase.md 也明确指出：对于需求清晰、无重大未知的 Epic，可以直接跳过 Discovery 进入规划阶段。整个生命周期在 docs/WORKFLOW_COMMANDS.md 中有完整的 mermaid 流程图与文档流转总表（Discovery Document → Synthesis Document → Jira Tickets → Overview → Implementation Plan → Code → Completion Report）。

触发源：feature-forge 与 Discovery Recommendation

Discovery 的输入侧依赖feature-forge技能。在 docs/workflow/discovery-phase.md 的 Prerequisites 中，第一条就是Feature-forge spec with Discovery Recommendation section (recommended)——即 feature-forge 产出的规格文档中应包含一个"建议是否进入 Discovery"的章节。feature-forge 本身的访谈与规格模板可参见 skills/feature-forge/SKILL.md 及其 references。

二、三个命令的总览与配置映射

Discovery Phase 的核心由三个按顺序执行的命令组成。命令的中枢定义位于 commands/workflow-manifest.yaml 同级的命令目录中，每个命令的元数据（输入、输出、所需集成、参数提示）分别声明在各自的 YAML 文件里：

顺序	命令	摘要	命令实现（Markdown）	元数据（YAML）
1	`discovery:create`	创建带有研究问题与假设的结构化发现工作区	create-epic-discovery.md	create.yaml
2	`discovery:synthesize`	将研究产物整合为发现、建议与拟议 ticket	synthesize-discovery.md	synthesize.yaml
3	`discovery:approve`	解决阻塞性决策并在工单系统中创建 ticket	approve-synthesis.md	approve.yaml

在 Claude Code 中使用时，命令以/project:discovery:create-epic-discovery <epic-key>这种全名形式触发（见 docs/WORKFLOW_COMMANDS.md 的 Command Reference 表）；三个命令对应的斜杠命令别名则是/create-epic-discovery、/synthesize-discovery、/approve-synthesis。

从 YAML 元数据可以确认三条关键信息：

三个命令的phase字段均为discovery，status均为existing（已实现，不同于 Intake 阶段命令的 "Planned" 状态）；
每个命令都声明了requires: [ticketing, documentation]，即都需要 Jira 与 Confluence 集成；
命令均设置repeat: false，属于单次执行命令。

阶段之间的人工研究窗口

值得强调的是：第 1 步与第 2 步之间是留给人类执行真实研究的。正如 docs/workflow/discovery-phase.md 所述：用户访谈、技术 Spike、竞品分析、设计冲刺（design sprints）都发生在这个窗口。Agent 负责搭建框架与整合结论，而研究本身需要人类参与——这是整个工作流"人机协作"设计的关键体现。

三、`discovery:create`：搭建研究脚手架

输入与输出

命令配置（create.yaml）明确定义了唯一必填参数：

输入：epic-key（string，必填），Jira Discovery Epic 的 key，例如CC-60；
输出：discovery-document（url），发布到 Confluence 的页面，路径为/epics/Discovery/{epic-key}/。

执行流程（对应 create-epic-discovery.md）

Phase 0 — Context Retrieval：先从 Jira 拉取 Epic 及其关联 ticket，提取 Epic 标题、Jira 项目 URL、关联 ticket 列表，并确定 Confluence 发布位置（默认/Epics/Discovery/{Epic_Key}/）。该阶段有两个硬性停止条件：

Failure Condition：Epic 找不到或没有关联 ticket 时，必须 STOP 并向用户提示[epic not found / no linked tickets / access denied]，要求确认 Epic key、Jira 项目 URL 与发布位置；
Mandatory Checkpoint：发布前必须向用户展示 Epic Key、Epic Title、Linked Tickets 数量与 Publish Location，获得明确确认（Yes / No / Correct）才能继续。

Phase 1 — Question Extraction：使用 JQL 查询"Epic Link" = {Epic_Key}读取全部子 ticket，提取显式问题与隐式问题（来自模糊需求）、需要验证的假设、未知项清单，并将问题按主题归类：

Customer/User Discovery（谁在用、什么问题、什么工作流）
Technical Feasibility（能否构建、复杂度如何）
Business Viability（值不值得做、ROI 如何）
Integration Points（外部系统、API、数据源）
Scope Boundaries（做什么、不做什么）

随后为每个问题匹配合适的研究方法：用户访谈、数据分析、技术 Spike/POC、竞品研究、专家咨询、原型设计。

Phase 2 — Discovery Document Creation：生成包含九个章节的发现文档，这是整个发现阶段的核心交付物：

Discovery Overview— Epic 链接、发现目标、成功标准、时间线与干系人；
Hypothesis Map— 假设表（Hypothesis ID / Statement / Confidence / Validation Method / Status），例如H1: "Users need X because Y"、H2: "We can integrate with Z"；
Research Questions Matrix— 按客户/技术/商业/范围四个维度组织的优先级问题矩阵（ID / Question / Priority / Method / Owner / Status）；
Dependencies & Blockers— 外部依赖、内部依赖、信息阻塞项、时间线依赖；
Research Plan— 每个高优先级问题配一份研究活动模板（Activity / Questions Addressed / Method / Participants / Expected Duration / Output）；
Decision Framework— 决策点、选项、评估标准与负责人，例如 "Build vs Buy"、"目标用户细分"；
Risk Register— 风险、可能性、影响、缓解措施与负责人；
Target Implementation Epics— 研究成果可能流入的落地 Epic 列表；
Linked Tickets— 关联 ticket 及其对应的发现焦点。

Phase 3/4 — Review & Publish：再次经过 Mandatory Checkpoint（展示研究问题数、假设数、高优先级问题数、目标 Epic 列表），用户批准后才发布到 Confluence，页面标题格式为{Epic_Key} Discovery - {Epic_Title}。发布完成后必须输出发现文档 URL——这个 URL 是后续 synthesize 步骤的必需输入，文档中对此标注为 CRITICAL。

命令的失败条件矩阵还覆盖了 Epic key 不存在、无关联 ticket（可询问是否生成最小文档）、Confluence 位置无效、Jira/Confluence 凭据缺失等场景。

四、`discovery:synthesize`：跨源整合研究结论

输入与输出

根据 synthesize.yaml：

输入：source-urls（list[url]，必填）——一个或多个 Confluence 文档 URL；target（string，可选）——目标实现 Epic key，例如--target=CC-62，缺省时从来源文档自动探测；
输出：synthesis-document（url），发布路径为/epics/Discovery/{discovery-epic-key}/Synthesis/。

参数用法（见 synthesize-discovery.md）支持多种组合：

/synthesize-discovery https://confluence/doc1 /synthesize-discovery https://confluence/doc1 https://confluence/doc2 /synthesize-discovery https://confluence/doc1 --target=CC-62

支持的来源类型包括：Discovery 文档、研究发现文档、访谈纪要、技术 Spike 报告、竞品分析文档，以及任何包含结构化发现的 Confluence 页面。

执行流程

Phase 0 — Source Retrieval：拉取全部来源文档，从每份文档提取文档类型、关键发现、已验证/证伪的假设、已回答的研究问题、剩余未知项与建议；确定目标实现 Epic（--target优先，其次从 "Target Implementation Epics" 章节提取，都没有则询问用户）。同样存在 Failure Condition（来源不可达或未找到目标 Epic 时 STOP）与 Mandatory Checkpoint（列出来源清单与目标 Epic 请用户确认）。

Phase 1 — Cross-Source Analysis：合并假设验证结果、综合研究问题答案、识别一致主题与矛盾冲突，建立 Findings Inventory（Finding ID / Source / Category / Finding / Confidence / Actionable），并记录跨来源反复出现的模式、收敛性结论以及仍待解决的未知项。

Phase 2 — Recommendation Generation：对每个可行动的发现判断：是否应成为 ticket、工作类型（Feature / Enhancement / Spike / Research）、归属哪个实现 Epic、优先级、依赖关系。输出 Recommendation Matrix（Rec ID / Based On / Title / Type / Target Epic / Priority / Dependencies），并识别需要干系人输入的 Scope 决策。

Phase 3 — Synthesis Document Creation：生成综合文档，关键章节包括：

Executive Summary— 关键洞察、总体方向建议、置信度、需要的主要决策；
Consolidated Findings— 已验证/部分验证/证伪的假设表、已回答研究问题表、按主题（用户/技术/商业）组织的关键洞察叙述；
Remaining Unknowns— 未知项、影响、建议与优先级；
Recommendations by Epic— 每个目标 Epic 的推荐 ticket 表（含 Story Points、依赖与 Based On）、MVP 范围建议、风险调整；
Decision Log 与 Blocking Decisions— 决策表 + 必须解决的阻塞决策表（D1/D2...）；
Source Cross-Reference— 发现到来源的可追溯映射；
Proposed Tickets Data— 机器可读的 JSON 区块（见下节），供 approve 命令消费。

机器可读的 Proposed Tickets JSON

这是 synthesize 输出中最重要的结构化部分，被与标记包裹，结构示意如下：

{ "version": "1.0", "synthesis_url": "[this document URL]", "discovery_epic": "[Discovery Epic Key]", "blocking_decisions": [ { "id": "D1", "question": "[decision question]", "options": ["A", "B", "C"], "status": "pending", "resolution": null, "blocks_tickets": ["T1", "T3"] } ], "proposed_tickets": [ { "id": "T1", "title": "[Ticket title]", "type": "Story", "target_epic": "CC-62", "priority": "High", "story_points": 5, "dependencies": [], "blocked_by_decisions": ["D1"], "based_on_findings": ["F1", "F2"], "description": "[Full ticket description]", "acceptance_criteria": ["Criterion 1", "Criterion 2"], "notes_from_discovery": "[Relevant insights]" } ], "approval_status": "pending", "approved_by": null, "approved_date": null }

其中blocking_decisions与proposed_tickets是discovery:approve的解析入口，approval_status会在批准后被改写为approved。synthesize 阶段的 Checkpoint 同样强制：发布前展示来源数、发现数、验证/证伪假设数、拟议 ticket 数与待决阻塞决策数，获用户批准后才发布到/epics/Discovery/{Discovery_Epic_Key}/Synthesis/，并同步在发现文档与目标 Epic 中补上综合文档链接与拟议 ticket 摘要。

五、`discovery:approve`：解决决策并落地 Jira 工单

输入与输出

根据 approve.yaml：

输入：synthesis-url（url，必填）；decisions（list[string]，可选），用于预置决策解析，例如--decision=D1:B --decision=D2:Y；
输出：created-tickets（tickets）——创建在目标实现 Epic 下的 Jira ticket，链接到 Discovery Epic，包含完整描述与验收标准。

执行流程（对应 approve-synthesis.md）

Phase 0 — Context Retrieval：拉取综合文档，提取 Discovery Epic 链接、目标 Epic、Proposed Tickets JSON（注意它是从与标记之间解析的）以及阻塞决策与批准状态。两个 Failure Condition：

综合文档缺失（找不到 / 缺 Proposed Tickets 章节 / JSON 无效）→ STOP 要求验证；
综合文档已批准（approval_status: "approved"）→ STOP 并给出选项（查看已建工单 / 追加创建 / 取消）。

Phase 1 — Decision Resolution：解析blocking_decisions数组；先应用--decision=ID:Value预置解析（校验决策 ID 存在、值合法），再以交互方式逐个呈现仍待决的决策（含选项 A/B/C、综合文档给出的推荐与理由、被阻塞的工单 T1/T3/T5），所有决策未解决前不得创建 ticket。每次解析都会记录选项、解析人（用户）与时间戳，并在决策改变范围时更新受影响的 ticket。

Phase 2 — Ticket Review & Editing：展示拟议 ticket 列表（按 Epic 分组，含 ID、标题、类型、点数、优先级、依赖），用户可选择Approve / Edit / Cancel。Edit 模式支持 Add（如 "Add Story 'Implement caching' to CC-62"）、Remove（如 "Remove T3"）、Modify（如 "Modify T1 points to 8"）的循环编辑，直到输入 "Done" 回到最终批准 Checkpoint——没有显式的 "Yes" 绝不创建 ticket。

Phase 3 — Ticket Creation：在目标 Epic 下逐张创建 ticket，设置字段：Summary、Type（Story/Task/Bug/Spike）、Epic Link、Story Points、Priority，并打上from-discovery与{Discovery_Epic_Key}标签。描述使用统一模板，包含 Source（Discovery Epic / Synthesis 文档 / Based on Findings）、Context、Summary、Acceptance Criteria、Notes from Discovery、Decisions Made。随后用 Jira issue link 建立工单依赖（inward_issue_key= blocker、outward_issue_key= blocked，链接语义可参见 atlassian-mcp 的 jira-queries 参考），并维护{ T1: "CC-123", T2: "CC-124", ... }的映射。单张创建失败时提供 Retry / Skip / Stop 三个选项。

Phase 4 — Update & Output：在综合文档中追加 "Section 10: Approved Tickets"（含批准日期、批准人、已创建工单表、决策解析表、与原提案的差异清单），将 Section 9 的 JSON 中approval_status更新为approved并补上approved_by、approved_date、created_tickets映射，同时在 Discovery Epic 中补记综合文档链接与工单摘要。

六、贯穿全程的 Checkpoint 机制：人类监督是硬性约束

三个命令尽管职责不同，共享同一种"质量门禁"设计哲学（详见 docs/WORKFLOW_COMMANDS.md 的 Checkpoint System 章节）：命令在任何情况下都不得未经用户明确批准就修改 Jira 或 Confluence。

Discovery 阶段涉及的 Checkpoint 类型与命令对应关系如下：

命令	必经 Checkpoint
`discovery:create`	Epic 确认、发布前文档审查
`discovery:synthesize`	来源确认、发布前综合文档审查
`discovery:approve`	决策解析、工单修改、工单创建批准

Checkpoint 的响应约定为：Yes继续；No停止并询问需要什么变更；Modify用户反馈后重新生成再确认；Correct用户纠正后更新再确认。这套机制一方面防止 Agent 对工单系统的意外写入，另一方面为关键决策保留完整审计轨迹。

七、输出物、前置条件与后续衔接

三阶段输出物汇总

Discovery Document（发现文档）——研究问题、假设、研究计划，发布于/epics/Discovery/{epic-key}/；
Synthesis Document（综合文档）——整合后的发现、建议、带阻塞决策的拟议 ticket，发布于/epics/Discovery/{discovery-epic-key}/Synthesis/；
Tickets（工单）——在工单系统中创建、以研究为依据的 Epic 与 Ticket。

前置条件

Feature-forge 规格文档（建议包含 Discovery Recommendation 章节）；
Jira 工单系统访问权限（与 Confluence 的配置方法见 docs/ATLASSIAN_MCP_SETUP.md，该技能能力总览见 skills/atlassian-mcp/SKILL.md）；
Confluence 文档系统访问权限。

与 Planning 阶段的衔接

Discovery 完成后即进入规划阶段（docs/workflow/planning-phase.md）：先由planning:epic-plan分析代码库与工单、产出干系人可读的 Overview 文档（含 7 维风险评分），再由planning:impl-plan将其转化为带拓扑排序执行顺序、并行执行波次与 agent 推荐的实现计划，并把每个 Jira ticket 充实为自包含的实现细节（文件路径、代码片段、测试代码与验收标准）。若采用完整的 Discovery-First 流程，整个链路的形态为：

discovery:create → [人工研究] → discovery:synthesize → discovery:approve → planning:epic-plan → planning:impl-plan → [execution:execute-ticket + execution:complete-ticket] × N → retrospectives:complete-epic

而需求清晰、无需研究的 Epic 则可以直接走标准实现流程planning:epic-plan → planning:impl-plan → ...，这也再次印证了 Discovery 的"可选、按需"定位。

八、关键实现与文档索引

若要在仓库中深入研读本阶段，建议按以下路径展开：

阶段总览：docs/workflow/discovery-phase.md
三个命令的规格文档：docs/workflow/discovery-create.md、docs/workflow/discovery-synthesize.md、docs/workflow/discovery-approve.md
命令元数据与参数声明：commands/project/discovery/create.yaml、commands/project/discovery/synthesize.yaml、commands/project/discovery/approve.yaml
命令的完整执行提示词（分阶段流程、失败条件、Checkpoint、输出模板）：commands/project/discovery/create-epic-discovery.md、commands/project/discovery/synthesize-discovery.md、commands/project/discovery/approve-synthesis.md
全生命周期、集成点与 Checkpoint 总表：docs/WORKFLOW_COMMANDS.md
触发源技能：skills/feature-forge/SKILL.md 及 specification-template
Jira/Confluence 配置与链接语义：docs/ATLASSIAN_MCP_SETUP.md、skills/atlassian-mcp/references/jira-queries.md

需要说明的是，当前仓库提供的是命令提示词与元数据定义，实际执行依赖 Jira + Confluence 的外部集成（配置见 ATLASSIAN_MCP_SETUP）。因此，在生产环境中运行本阶段命令前，应确认 Epic 已存在于 Jira 且关联了 ticket、Jira 与 Confluence 访问已就绪，并准备好 feature-forge 产出的规格文档作为触发依据。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析