3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
5.4 KiB
如何在正式提交前进行技术验证与界面草图
目标： 在将某个阶段锁定到具体方案之前，通过聚焦的可行性实验（spike）和一次性 HTML 原型（sketch）来降低实现风险。
前提条件： 无。/gsd-spike 和 /gsd-sketch 会自行创建所需的存储目录，不要求已初始化 GSD 项目。
决策：spike、sketch，还是两者都用
| 你想回答的问题… | 使用 |
|---|---|
| "这个技术方案真的可行吗？" | /gsd-spike |
| "这个布局 / 交互 / 视觉处理感觉对吗？" | /gsd-sketch |
| "正确的技术方案是什么，它应该长什么样？" | 两者都用，顺序是：先 spike，再 sketch |
Spike 通过可执行代码和 VALIDATED / INVALIDATED / PARTIAL 结论来回答二元可行性问题。Sketch 通过 2–3 个可在浏览器中对比的 HTML 变体来回答视觉问题。两者互为补充——spike 证明方案可构建，sketch 证明设计值得构建。
运行 spike
交互式引导（默认）
/gsd-spike
GSD 会询问技术问题，将其分解为 2–5 个独立实验，以 Given / When / Then 假设形式呈现，并在开始构建前请求确认。
直接提供想法
/gsd-spike "can we stream LLM tokens through SSE"
跳过引导，直接运行
/gsd-spike --quick "websocket vs SSE latency"
--quick 跳过分解对话，直接将参数作为单个 spike 问题处理。当问题已经足够具体、无需进一步细化时使用此选项。
每个实验产出内容
.planning/spikes/NNN-descriptive-name/ 中的每个 spike 包含：
- 可运行的代码（非伪代码）
- 在编写任何代码之前写好的 Given / When / Then 假设
- 记录边界情况、方向调整和意外发现的调查轨迹
- 附有证据的 VALIDATED、INVALIDATED 或 PARTIAL 结论
- 包含 frontmatter、运行说明和结果的
README.md
所有 spike 均在 .planning/spikes/MANIFEST.md 中建立索引。
打包调查结果
当你获得有效信号后，将调查结果封装成项目本地技能，以便后续会话自动加载：
/gsd-spike --wrap-up
此命令会写入 .claude/skills/spike-findings-[project]/。该技能会被自动发现，并在后续的 /gsd-sketch、/gsd-ui-phase 和 /gsd-plan-phase 运行时加载——无需显式引用。
运行 sketch
风格引导（默认）
/gsd-sketch
GSD 会开启一段简短对话，在编写任何代码之前探索感觉、视觉参考和核心用户操作。它每次只问一个问题，只有在你说"开始"后才动手构建。
直接提供设计方向
/gsd-sketch "dashboard layout"
跳过风格引导，直接运行
/gsd-sketch --quick "sidebar navigation"
--quick 完全跳过引导对话，直接使用参数作为设计方向。
非 Claude 运行时（Codex、Gemini CLI 等）
/gsd-sketch --text "onboarding flow"
--text 将交互式提示替换为纯文本编号列表。当你的运行时不支持 AskUserQuestion 时使用此选项。
每个草图产出内容
.planning/sketches/NNN-descriptive-name/ 中的每个 sketch 包含：
- 带有 2–3 个变体、可通过选项卡导航访问的
index.html——直接在浏览器中打开，无需构建步骤 - 功能性交互元素（悬停、点击、过渡动画）
- 使用来自先前 spike 调查结果的字段名和数据结构的近似真实内容
- 来自
.planning/sketches/themes/default.css的共享 CSS 变量 - 包含设计问题、变体说明和关注点的
README.md
所有 sketch 均在 .planning/sketches/MANIFEST.md 中建立索引。
打包获胜的设计决策
选定变体后，将视觉决策捕获到项目本地技能中：
/gsd-sketch --wrap-up
此命令会写入 .claude/skills/sketch-findings-[project]/。该技能由 /gsd-ui-phase 自动获取——经过预验证的决策（布局、色彩方案、排版、间距）被视为已锁定，不会再次询问。
组合流程：spike → sketch → phase
当你对技术可行性和视觉方向都不确定时，推荐使用以下顺序：
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
spike 调查结果会为 sketch 提供参考（真实数据结构、真实交互状态、实际约束）。两次 wrap-up 均会持久化决策，规划器和 UI 研究员会自动加载，因此在 /gsd-discuss-phase 或 /gsd-ui-phase 期间无需重新解释选择。
spike 或 sketch 如何流入某个阶段
Spike 和 sketch 的产物不需要手动引用。GSD 会在以下两个时间点自动读取它们：
/gsd-sketch— 在构建原型前加载.claude/skills/spike-findings-*/，使变体反映已验证的约束（流式状态、真实字段名等）/gsd-ui-phase N— 在生成 UI 设计契约前加载.claude/skills/sketch-findings-*/；经过预验证的设计决策被视为已锁定
当存在 spike-findings-* 技能时，规划器也会读取 spike 调查结果，从而使已验证的技术选择（采用哪个库、哪种协议、哪种数据格式）直接流入任务计划，无需反复解释。