企业官网建设流程全解析

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用

导读

本篇技术指南系统讲解 GSD-2 开源仓库中内置的Research Spike 工作流模板（spike.md）。它回答的是软件开发中最常见的悬而未决问题——技术选型、架构决策、“我们应该用 X 吗”。读完本文，你将掌握如何通过/gsd start spike启动一次规范的研究冲刺：先界定问题与成功标准，再从多个角度展开调研，最后产出带对比矩阵与备选方案的推荐结论，并学会如何把可复用的调研结论沉淀为项目级 skill 或记入决策台账。

一、什么是 Research Spike：产出知识的“零生产代码”工作流

Spike（技术冲刺）是极限编程与敏捷实践中常见的降低不确定性手段。GSD-2 将其形式化为一条不产出生产代码的工作流：它的交付物是知识而非实现。

在 spike.md 的<purpose>段落中，模板对适用场景给出了明确定义：

Investigate a question, evaluate options, prototype if needed, and produce a clear recommendation. No production code is shipped — the output is knowledge.

适用场景包括：

• 技术评估（technology evaluation）：评估某库、某框架是否值得引入；
• 架构决策（architecture decisions）：在多种架构方案之间做取舍；
• “Should we X?” 类问题：是否自研、是否迁移、是否升级。

其核心价值在于：把一次“可能失控的调研”压缩进一套有门禁（Gate）、有产物（Artifact）、有结论（Recommendation）的结构化流程中，避免调研发散、结论模糊。

模板元数据

模板头部的<template_meta>定义了该工作流在 GSD-2 注册表中的关键属性：

<template_meta> name: spike version: 1 mode: markdown-phase requires_project: false artifact_dir: .gsd/workflows/spikes/ </template_meta>

这段元数据并非摆设——它正是 registry.json 中spike条目（第 48-58 行）的组成部分，由 workflow-templates.ts 中的TemplateEntry类型统一解析加载。

触发词与自动识别

在 registry.json 中，spike 模板还登记了一组触发词：

"triggers": [ "research", "investigate", "explore", "spike", "compare", "evaluate", "should we", "what if", "how does" ]

这组触发词在两种场景下被使用：

1. 显式指定：/gsd start spike <描述>，首词spike会被 resolveByName() 精确命中；同时research、investigate也是该函数内置的别名；
2. 自动识别：若用户输入的首词不是模板名，autoDetect() 会对输入文本做分词匹配——多词触发词（如should we）命中得分翻倍，按high/medium/low置信度排序；只有唯一或高置信度命中时才会自动选型，否则会列出候选让用户选择。

这意味着你可以直接对 Agent 说“帮我 evaluate 一下这几个日志库”，而不必记得模板名。

二、如何启动一次 Spike：/gsd start的完整命令面

spike 模板由 GSD-2 的/gsd start命令调度执行，其实现位于 commands-workflow-templates.ts 的handleStart()。

基本用法

/gsd start spike evaluate auth libraries

执行后，系统会依次完成：

1. 解析模板：spike命中注册表中的精确匹配；
2. 创建产物目录：以“日期-序号-别名”格式生成目录，如.gsd/workflows/spikes/260106-1-evaluate-auth-libraries（日期前缀YYMMDD+ 自增序号，见 getNextWorkflowNum() 与 slugify()）；
3. 创建隔离分支：默认创建gsd/spike/<slug>分支（若 git 隔离模式为worktree或branch；若为none则留在当前分支）；
4. 写入状态文件：在产物目录写STATE.json，记录模板名、阶段列表、当前阶段、分支与时间戳，为后续/gsd start resume提供断点续跑能力；
5. 派发工作流提示：将 spike.md 的完整内容注入workflow-start提示词，交由 Agent 执行。

辅助命令与标志

与自动模式的冲突约束

值得注意的安全约束：handleStart()在派发前会检查自动模式（auto-mode）是否处于激活状态。由于工作流模板会自行派发消息并切换 git 分支，与自动模式的派发循环存在冲突，因此自动模式运行期间无法启动工作流模板，需先/gsd pause（见 commands-workflow-templates.ts）。

三、Phase 1：Scope —— 界定问题与成功标准

spike 的第一阶段目标非常明确：定义我们在调研什么，以及“一个好答案”长什么样。

1. 框定问题（Frame the question）

写下需要回答的具体问题。注意把大问题拆成可回答的子问题——例如“是否引入 ORM”可拆为“性能影响如何”“开发体验如何”“迁移成本如何”。

2. 定义成功标准（Define success criteria）

模板明确要求回答“有用的答案应包含什么”，并给出了三类维度的框架：

• 对比标准（Comparison criteria）：性能、开发体验（DX）、维护成本、生态成熟度等；
• 约束条件（Constraints）：如“必须与 X 集成”“必须支持 Y”；
• 决策格式（Decision format）：go/no-go、多选一、取舍矩阵（tradeoff matrix）。

成功标准是后续验证调研是否“做完”的标尺——没有它，调研会无限发散。

3. 识别研究角度（Identify research angles）

选定 2～3 个相互独立的切入角度。模板给出两组示例：

• “评估库 A”“评估库 B”“评估自研”；
• “性能影响”“开发体验影响”“迁移路径”。

多角度的意义在于避免单一视角下的幸存者偏差。

4. 产出 SCOPE.md 并设门禁

• 产出：在产物目录写入SCOPE.md；
• 门禁（Gate）：将范围与研究角度提交给用户确认，通过后才进入调研阶段。这是整个流程唯一强制的人工确认点，防止在错误的问题上投入调研成本。

四、Phase 2：Research —— 多角度纵深调研

第二阶段要求对每个角度做彻底调查，模板给出的标准动作包括：

1. 检索相关文档、基准测试（benchmarks）、对比资料；
2. 阅读项目内的相关源码（对选型至关重要——外部基准与项目真实上下文往往差异巨大）；
3. 必要时构建小型原型或概念验证（POC）；
4. 记录每个角度的优缺点、风险与未知项（pros, cons, risks, unknowns）。

每个角度的调研结果独立成文，存放于产物目录的research/子目录：

research/ANGLE-1.md research/ANGLE-2.md

每篇文档的固定结构：发现（findings）、证据（evidence）、优缺点（pros/cons）、置信度（confidence level）。其中“置信度”字段尤为关键——它让结论可以被分级采信，而不是把所有判断混为一谈。

五、Phase 3：Synthesize —— 汇总结论与推荐

第三阶段把分散的调研整合为一个清晰的决策输出。

1. 跨角度对比

构建对比矩阵或汇总表，将各角度在统一维度上对齐。

2. 给出推荐

模板要求推荐部分包含三层内容，这正是它与“一份调研报告”的本质区别：

• 主推荐（Primary recommendation）：基于证据应怎么做，并给出理由；
• 备选方案（Alternative）：主推荐行不通时的退路；
• 风险因子（What would change the recommendation）：什么条件出现会推翻当前结论。

3. 产出 RECOMMENDATION.md

最终文档必须包含四部分：

• 执行摘要（1～2 段）；
• 对比矩阵；
• 带理由的推荐；
• 推荐被采纳后的下一步行动（Next steps）。

4. 面向用户呈现

将结论展示给用户讨论——spike 的终点是“人类与 Agent 达成一致”，而非 Agent 单方面给出答案。

六、收尾：把调研转化为长期资产

spike 最容易被浪费的价值在于：结论用一次就被遗忘。spike.md 的 Phase 3 明确给出了两种沉淀路径。

路径 A：可复用结论 → spike-wrap-up 技能

如果结论包含可复用的指导（如“如何评估 X”“某库的坑有哪些”“应遵循的某种模式”），则运行spike-wrap-upskill，将产物打包为项目级 skill 写入.claude/skills/<name>/SKILL.md。该 skill 会在未来相似任务到来时由 skill-discovery.ts 自动加载——一次性调研就此变成长期能力。

spike-wrap-up/SKILL.md 定义了打包的完整流程：定位最新 spike → 判断是否值得打包 → 设计技能（含触发词描述、目标、步骤、反模式、成功标准）→ 写入.claude/skills/<name>/SKILL.md→ 在技能中引用来源 spike → 在.gsd/DECISIONS.md追加一行记录 → 确认下次会话可被发现。其<core_principle>尤其强调三个铁律：

• 不是每个 spike 都值得打包：若结论是一次性决策（如“选了库 Y，到此为止”），应走路径 B；
• 必须写入项目本地（.claude/skills/），不得写入用户全局目录（~/.claude/skills/）；
• description 是发现性信号：它是 Agent 判断是否加载技能的启发式依据，应写成未来可能遇到的关键词而非摘要。

路径 B：一次性决策 → 记入 DECISIONS.md

若结论只是决策而无复用价值，则将一句话结论追加到.gsd/DECISIONS.md。该文件是 GSD 方法论的只追加决策台账（见 GSD-WORKFLOW.md 的DECISIONS.md章节）——行只增不改，若要推翻决策则新增一行并引用旧编号，同时记录Revisable?与触发条件。

七、源码视角：模板如何被加载与校验

理解 spike 模板的“幕后”，能帮你更好地定制它。

注册表与解析

所有模板统一登记在 registry.json。workflow-templates.ts 的loadRegistry()会惰性加载并缓存注册表；resolveByName()按“精确 key → 模板名 → 前缀模糊 → 内置别名”四级顺序解析，spike 对应别名research、investigate。模板解析结果携带置信度（exact/high/medium/low），供自动选型排序使用。

阶段式执行与恢复

spike 属于markdown-phase模式（isLegacyWorkflowMode判定为非auto-milestone），执行时会在产物目录写入STATE.json，记录phases数组与每个阶段的pending/active/completed状态。/gsd start resume通过 findInProgressWorkflows() 扫描所有工作流分类目录（bugfixes、features、spikes 等），筛选未写completedAt的状态文件并恢复。

模板覆盖机制

项目或全局的插件可以同名覆盖内置模板——handleStart()优先加载插件覆盖版本（resolvePlugin），仅在插件缺失时才回落到内置文件loadWorkflowTemplate()。这意味着团队可以基于 spike 模板做定制，而无需改动仓库内置文件。

八、实践清单与常见误区

一次高质量 spike 的检查清单

• SCOPE.md已定义成功标准（对比维度、约束、决策格式），并经用户确认；
• 至少 2 个独立研究角度，每角度有独立research/ANGLE-N.md；
• 每篇研究文档包含发现、证据、优缺点与置信度；
• RECOMMENDATION.md含执行摘要、对比矩阵、主推荐 + 备选 + 风险因子、下一步行动；
• 结论已向用户呈现并讨论；
• 可复用结论已打包为项目级 skill；一次性决策已追加至.gsd/DECISIONS.md。

常见误区

1. 跳过门禁直接开跑：未与用户确认范围就调研，是对研究成本的最大浪费；
2. 只调研不对比：单角度的调研无法支撑决策，对比矩阵是 RECOMMENDATION 的骨架；
3. 把一次性决策包装成 skill：spike-wrap-up 的<core_principle>明确反对“每个 spike 都打包”——它应在.gsd/DECISIONS.md里终结；
4. 结论没有置信度与风险因子：没有“什么会推翻这个结论”的推荐，无法在条件变化时及时调整；
5. 在自动模式运行时启动模板：会被handleStart()的冲突守卫拦截，需先/gsd pause。

结语

Research Spike 工作流把“调研”从不可控的对话过程，压缩为Scope（带门禁）→ Research（多角度、带置信度）→ Synthesize（带对比矩阵与备选方案）三阶段、三份产物的确定性流程，并以.gsd/workflows/spikes/作为统一产物目录、/gsd start resume提供断点续跑。它的终点不只是“知道了答案”，而是结论可追溯、可复用、可推翻——这正是 GSD-2 面向长周期自主 Agent 设计理念在“决策类任务”上的具体落地。对于团队而言，你既可以直接复用内置模板，也可以参照 registry.json 的结构登记自己的定制版本。

• 人工智能
• AI Agent
• 代码智能体
• Agent 编排
• CLI
• AI 应用