claude-skills 的 discovery:synthesize 命令将多源研究资料收敛为可执行工单的合成机制【免费下载链接】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:synthesize是 claude-skills 工作流系统 Discovery研究/发现阶段的第二个核心命令它接收人类研究阶段产出的多份 Confluence 文档发现文档、访谈纪要、技术 spike 报告、竞品分析等通过跨源分析、假设验证、推荐生成产出一份包含机器可读 JSON 拟议工单的综合合成文档。读完本文你将掌握该命令的参数约定、五阶段执行流程、合成文档九个章节的组织规范以及它如何与discovery:approve无缝衔接把研究结论转成 Jira 中可追溯、可验收的实现工单。一、命令定位发现阶段的中枢收敛器在 claude-skills 的四阶段工作流Discovery → Planning → Execution → Retrospectives中Discovery 阶段由三个命令构成完整闭环完整链路见 docs/workflow/discovery-phase.md顺序命令职责1discovery:create基于 Jira Epic 创建结构化发现文档假设地图、研究问题矩阵、研究计划2discovery:synthesize把研究产物收敛为发现、建议与拟议工单本命令3discovery:approve解决阻塞性决策在 Jira 中创建实现工单命令的主文档 docs/workflow/discovery-synthesize.md 给出了它的核心定义Agent 获取所有提供的源文档执行跨源分析以识别主题与矛盾生成映射到目标 Epic 的功能建议并产出一份综合合成文档该文档包含供审批命令消费的机器可读拟议工单段JSON。从命令注册配置 commands/project/discovery/synthesize.yaml 可以看到它的元数据command: discovery:synthesize phase: discovery path: commands/project/discovery/synthesize-discovery.md description: docs/workflow/discovery-synthesize.md requires: - ticketing - documentation status: existing argument-hint: source-url [source-url...] [--targetepic-key] repeat: false两个关键点requires声明它依赖 Jiraticketing与 Confluencedocumentation两大外部系统因此前置条件是在 docs/ATLASSIAN_MCP_SETUP.md 中完成 Atlassian MCP 配置repeat: false表示该命令一次流程中只执行一次。完整工作流链条命令实现文档 commands/project/discovery/synthesize-discovery.md 用一张流程图清晰标出了本命令在整条链路中的位置/create-epic-discovery epic-key → Discovery Document ↓ [Manual research, interviews, experiments] ↓ /synthesize-discovery doc-urls... → Synthesis Document本命令在此 ↓ /approve-synthesis synthesis-url → Creates Jira Tickets ↓ /create-implementation-plan overview-doc → Implementation planning continues注意两个关键设计研究阶段是人工环节——文档明确指出Between steps 1 and 2, humans conduct the actual research: user interviews, technical spikes, competitive analysis, design sprints产出可追溯——每一步的产物 URL 都会被显式传递给下一步骤形成文档级的审计链。二、输入与输出契约输入参数名称类型必填说明source-urlslist[url]是一个或多个待合成的 Confluence 文档 URLtargetstring否目标实现 Epic 键如--targetCC-62省略时从来源自动探测输出产物名称类型路径说明synthesis-documenturl/epics/Discovery/{discovery-epic-key}/Synthesis/包含合并后发现、已验证/已否定假设、按 Epic 分类的建议、阻塞性决策与拟议工单 JSON 的 Confluence 页面前置条件已通过discovery:create创建发现文档详见 docs/workflow/discovery-create.md人工研究已完成产物可通过 URL 访问Jira 与 Confluence 访问已配置参数解析示例实现文档定义了四种典型的参数形态均通过/synthesize-discovery调用/synthesize-discovery https://confluence/doc1→ 单一来源自动探测目标 Epic/synthesize-discovery https://confluence/doc1 https://confluence/doc2→ 多来源/synthesize-discovery https://confluence/doc1 --targetCC-62→ 单一来源 指定 Epic/synthesize-discovery doc1-url doc2-url doc3-url --targetCC-62→ 多来源 指定 Epic支持的源文档类型实现文档明确列出六类可消费的来源发现文档来自/create-epic-discovery研究发现文档research findings访谈纪要interview summaries技术 spike 报告technical spike reports竞品分析文档competitive analysis documents任何包含结构化发现的 Confluence 页面三、Phase 0来源检索与双重强制检查点合成流程共五个阶段第一阶段负责拿到并核实输入。提取与目标 Epic 识别Agent 需要从每个来源中提取文档类型、关键发现与洞见、已验证/已否定的假设、已回答的研究问题、剩余未知项、建议。目标实现 Epic 的确定顺序为若指定了--target直接使用否则从来源文档的 Target Implementation Epics 章节提取若都未找到向用户询问。失败条件信息缺失即停止若来源无法获取或未识别出目标 EpicAgent 必须 STOP 并提示I was unable to retrieve required information. Sources Retrieved: [count]/[total] Failed Sources: [list URLs that failed] Target Epics Found: [list or None] Please provide: 1. Confirm source URLs are accessible 2. Target implementation epic(s): [e.g., CC-62, CC-60]在确认之前DO NOT PROCEED——这是贯穿整个工作流系统的硬性铁律见 docs/WORKFLOW_COMMANDS.md 的 Checkpoint System 章节任何命令在未经用户明确批准前不得修改 Jira 或 Confluence。强制检查点来源确认进入正式分析前Agent 必须展示待合成的来源清单并征得用户确认Please confirm before I proceed: Sources to Synthesize: 1. [URL] - [Document Title] ([type]) 2. [URL] - [Document Title] ([type]) ... Target Implementation Epic(s): [list] Is this correct? (Yes / No / Correct)四、Phase 1跨源分析——从碎片发现到结构化清单这一阶段解决多个文档说了什么、彼此是否矛盾、还有什么不知道三个问题。发现合并与矛盾识别跨源合并四类信息合并假设验证结果、合并研究问题答案、识别一致主题、标注矛盾或冲突。值得注意的是矛盾并不被隐藏而是显式记录——这正是后面阻塞性决策与待解决分歧的输入。发现清单Findings Inventory所有发现汇入一张带唯一 ID 的清单表ID 是整个合成文档中被引用、被追溯的锚点Finding IDSource(s)CategoryFindingConfidenceActionableF1Doc1, Doc2User NeedUsers want XHighYesF2Doc1TechnicalAPI supports YMedYesF3Doc3BusinessROI is ZLowNeeds validation模式识别与未知项目录模式跨来源反复出现的主题、趋同的结论、需要解决的分歧意见未知项目录仍未回答的问题、新浮现的问题、需要进一步研究的领域。五、Phase 2建议生成——发现到工单的映射对每条可行动发现ActionableTrueAgent 判断五个问题是否应成为工单工作类型是什么Feature/Enhancement/Spike/Research归属哪个实现 Epic基于发现确定优先级与其他建议是否有依赖建议矩阵Recommendation MatrixRec IDBased OnTitleTypeTarget EpicPriorityDependenciesR1F1, F2Implement X featureStoryCC-62HighNoneR2F3Validate ROI assumptionSpikeCC-60MedR1R3F1Design user flow for XTaskCC-62HighNone范围决策识别同时标记需要利益相关方介入的三类范围问题可能走向多个方向的功能、需要权衡取舍的 trade-off、MVP 与后续阶段future phase的取舍。六、Phase 3合成文档创建——九个章节的结构化知识产物这是本命令最核心的产出。合成文档发布在/epics/Discovery/{discovery-epic-key}/Synthesis/标题规范为{Discovery_Epic_Key} Synthesis - [Date]。完整章节如下。1. Synthesis Overview合成概览记录 Discovery Epic 链接、所有已分析来源及链接、合成日期、目标实现 Epic 链接为文档提供上下文锚点。2. Executive Summary执行摘要一段话的核心洞见Key Insight、基于发现的高层方向建议Recommendation、整体置信度Confidence Level、需要决策的阻塞项清单Major Decisions Needed。3. Consolidated Findings合并发现分三张表组织已验证假设Validated HypothesesIDOriginal HypothesisValidation StatusEvidenceImplicationsH1[statement]Validated[sources][what this means]H2[statement]Partially Validated[sources][caveats]H3[statement]Invalidated[sources][pivot needed]注意三分法Validated / Partially Validated / Invalidated后者会驱动pivot needed的结论直接作用于后续建议。已回答研究问题Research Questions AnsweredIDQuestionAnswerConfidenceSource(s)Q1[question][answer]High/Med/Low[docs]关键洞见Key Insights按用户/客户洞见、技术洞见、业务洞见三类主题组织的叙事性总结每条洞见都需附证据支撑。4. Remaining Unknowns剩余未知项IDUnknownImpactRecommendationPriorityU1[what we dont know][why it matters][next step]High/Med/Low5. Recommendations by Epic按 Epic 分类的建议对每个目标实现 Epic 输出三个部分推荐工单表含 #、标题、类型、优先级、故事点、依赖、依据发现、范围建议MVP 应包含什么、应推迟到什么、基于发现不应构建什么、风险调整新识别风险、更新后的风险等级、学到的缓解策略。推荐工单表示例#TitleTypePriorityStory PointsDependenciesBased On1[title]StoryHigh5NoneF1, F22[title]TaskMed3#1F36. Decision Log 与 6a. Blocking Decisions决策日志记录所有需要决策的事项DecisionOptionsRecommendationRationaleOwnerDeadline阻塞性决策单独成节状态标记为Pending Resolution / All ResolvedIDDecisionOptionsStatusResolutionResolved ByDateD1[decision question]A, B, CPending---并显式标注影响面Impact: Tickets [T1, T3, T5] are blocked until all decisions are resolved.——这些决策是工单创建前的硬性闸门只能由/approve-synthesis解决详见 docs/workflow/discovery-approve.md。7. Source Cross-Reference来源交叉引用SourceKey ContributionsFindings Referenced[Doc1 URL][what this doc contributed]F1, F2, F5[Doc2 URL][what this doc contributed]F3, F48. Appendix: Full Findings Inventory完整发现清单附录保留全部细节供审批与实现阶段深查。9. Proposed Tickets Data机器可读拟议工单这是整个命令的机器接口用!-- PROPOSED_TICKETS_START --与!-- PROPOSED_TICKETS_END --注释包裹的 JSON 块供discovery:approve解析。完整结构如下{ 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 }这个 JSON 的 schema 设计与审批命令discovery:approve的解析逻辑一一对应blocking_decisions数组驱动决策解决阶段、proposed_tickets驱动工单审阅与创建、approval_status字段防止重复审批。审批完成后命令会回写approval_status: approved与created_tickets映射如{T1: CC-123}详见 commands/project/discovery/approve-synthesis.md。七、Phase 4合成审阅——发布前的强制检查点合成文档发布前Agent 必须展示完整预览并附统计摘要## Synthesis Document Preview [Full synthesis document content] --- Summary: - Sources Analyzed: [count] - Findings Extracted: [count] - Hypotheses Validated: [count] / Invalidated: [count] - Proposed Tickets: [count] - Blocking Decisions: [count] pending - Target Epics: [list] Ready to publish synthesis document? (Yes / No / Modify)三种响应Yes→ 发布到 ConfluenceNo→ 询问所需修改Modify→ 用户给出反馈后重新生成。未获明确批准前DO NOT PROCEED。八、Phase 5发布与输出发布动作将合成文档发布到 Confluence/epics/Discovery/{Discovery_Epic_Key}/Synthesis/标题为{Discovery_Epic_Key} Synthesis - [Date]更新发现文档加入合成文档链接更新目标 Epic加入合成文档链接与拟议工单摘要注意此时工单尚未创建。完成输出模板命令结束时 Agent必须按固定模板输出完整汇报包括合成文档 URL、已分析来源、统计摘要总发现数/已验证/已否定假设/剩余未知项、拟议工单摘要按 Epic 分组的工单数与故事点合计、阻塞性决策清单与下一步动作## Discovery Synthesis Complete! **Synthesis Document:** {Synthesis_Document_URL} ### Sources Analyzed 1. Doc1 Title 2. Doc2 Title ... ### Summary - Total Findings: [count] - Validated Hypotheses: [count] - Invalidated Hypotheses: [count] - Remaining Unknowns: [count] ### Proposed Tickets Summary **Total Proposed:** [count] tickets, [sum] story points **Blocking Decisions:** [count] pending #### By Epic: - {Epic_Key_1}: [count] tickets ([sum] points) - {Epic_Key_2}: [count] tickets ([sum] points) ### Blocking Decisions 1. [D1: Decision needing resolution] 2. [D2: Decision needing resolution] ### Next Steps 1. Review the synthesis document 2. Resolve blocking decisions 3. Run ticket approval: /approve-synthesis {Synthesis_Document_URL}这种文档 URL 必须显式输出的设计与该仓库 docs/WORKFLOW_COMMANDS.md 的 Best Practices 一致下游命令完全依赖上游输出的 URL 工作——discovery:create输出{Discovery_Document}供 synthesize 使用discovery:synthesize输出{Synthesis_Document}供 approve 使用形成无断点的文档链。九、失败条件与降级策略实现文档定义了四类标准失败场景及对应处置条件动作来源 URL 不可访问列出失败 URL请求替代方案未指定或未找到目标 Epic请求用户指定目标 Epic跨来源发现冲突记录冲突请求用户裁决Confluence 发布失败提供文档内容供人工发布这四类失败条件的设计逻辑是可恢复优先所有失败都保留对话继续的路径而非中断流程。与之呼应审批命令discovery:approve的失败条件表还覆盖了 JSON 解析失败、工单创建失败等更多场景并提供 Retry/Skip/Stop 三选一。十、Agent 委派策略并行分析命令实现文档还规定了 Agent 委派模式合成前Before synthesis文档分析使用 Explore agents并行分析每个来源文档模式识别识别跨来源的主题与模式交叉引用将发现映射回其来源。文档创建期间During document creation验证确认目标 Epic 存在且可访问决策识别标记将阻塞工单创建的决策。这种读阶段并行、写阶段串行的策略与 docs/WORKFLOW_COMMANDS.md 中 planning 阶段并行 agents 探索代码库的模式一脉相承是仓库处理多来源信息的标准范式。十一、与上下游的衔接从合成到落地进入审批合成文档发布后的标准下一步是 docs/workflow/discovery-approve.md 描述的discovery:approveAgent 抓取合成文档、提取PROPOSED_TICKETS_START/END之间的 JSON、交互式解决所有未决阻塞性决策然后以 Add/Remove/Modify 三种方式让用户编辑拟议工单最终在目标 Epic 下创建 Jira 工单——每个工单都会携带完整描述、验收标准以及发现溯源链接Source/Context/Summary/Acceptance Criteria/Notes from Discovery/Decisions Made 的固定模板并打上from-discovery与发现 Epic 键的标签保证每张工单都能回溯到具体的发现与决策。进入规划工单创建后流程继续进入 Planning Phaseplanning:epic-plan为目标实现 Epic 创建利益相关方可读的概览文档见 docs/workflow/planning-phase.md随后planning:impl-plan将工单细化为自包含的实现计划。整条链路中合成文档始终是为什么做、依据什么做的权威证据源。发现优先流Discovery-First Flow若 Epic 存在重大未知推荐使用发现优先的完整流程discovery:create - [research] - discovery:synthesize - discovery:approve - planning:epic-plan - planning:impl-plan - [execution:execute-ticket execution:complete-ticket] x N - retrospectives:complete-epic十二、小结为什么合成是研究质量的守门人从源码实现commands/project/discovery/synthesize-discovery.md与工作流文档docs/workflow/discovery-synthesize.md、docs/WORKFLOW_COMMANDS.md可以归纳出discovery:synthesize的三个设计要义证据密度优先从发现清单F 编号、建议矩阵R 编号、假设验证表H 编号到机器可读 JSON每一个结论都可溯源到具体来源文档杜绝拍脑袋工单人工闸门贯穿来源确认、发布审阅两道强制检查点确保 Agent 不擅动 Confluence而阻塞性决策机制把关键范围问题显式推给利益相关方裁决机器可读接口PROPOSED_TICKETS_START/END包裹的 JSON 是合成文档与审批命令之间的协议边界使研究 → 工单的转化可编程、可验证、可审计。理解这一命令也就理解了 claude-skills 工作流系统用结构化研究驱动结构化交付的核心方法论。【免费下载链接】claude-skills67 Specialized Skills for Full-Stack Developers. Transform Claude Code into your expert pair programmer.项目地址: https://gitcode.com/GitHub_Trending/claud/claude-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考