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>
161 lines
5.4 KiB
Markdown
161 lines
5.4 KiB
Markdown
# 如何在正式提交前进行技术验证与界面草图
|
||
|
||
**目标：** 在将某个阶段锁定到具体方案之前，通过聚焦的可行性实验（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
|
||
|
||
### 交互式引导（默认）
|
||
|
||
```bash
|
||
/gsd-spike
|
||
```
|
||
|
||
GSD 会询问技术问题，将其分解为 2–5 个独立实验，以 **Given / When / Then** 假设形式呈现，并在开始构建前请求确认。
|
||
|
||
### 直接提供想法
|
||
|
||
```bash
|
||
/gsd-spike "can we stream LLM tokens through SSE"
|
||
```
|
||
|
||
### 跳过引导，直接运行
|
||
|
||
```bash
|
||
/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` 中建立索引。
|
||
|
||
### 打包调查结果
|
||
|
||
当你获得有效信号后，将调查结果封装成项目本地技能，以便后续会话自动加载：
|
||
|
||
```bash
|
||
/gsd-spike --wrap-up
|
||
```
|
||
|
||
此命令会写入 `.claude/skills/spike-findings-[project]/`。该技能会被自动发现，并在后续的 `/gsd-sketch`、`/gsd-ui-phase` 和 `/gsd-plan-phase` 运行时加载——无需显式引用。
|
||
|
||
---
|
||
|
||
## 运行 sketch
|
||
|
||
### 风格引导（默认）
|
||
|
||
```bash
|
||
/gsd-sketch
|
||
```
|
||
|
||
GSD 会开启一段简短对话，在编写任何代码之前探索感觉、视觉参考和核心用户操作。它每次只问一个问题，只有在你说"开始"后才动手构建。
|
||
|
||
### 直接提供设计方向
|
||
|
||
```bash
|
||
/gsd-sketch "dashboard layout"
|
||
```
|
||
|
||
### 跳过风格引导，直接运行
|
||
|
||
```bash
|
||
/gsd-sketch --quick "sidebar navigation"
|
||
```
|
||
|
||
`--quick` 完全跳过引导对话，直接使用参数作为设计方向。
|
||
|
||
### 非 Claude 运行时（Codex、Gemini CLI 等）
|
||
|
||
```bash
|
||
/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` 中建立索引。
|
||
|
||
### 打包获胜的设计决策
|
||
|
||
选定变体后，将视觉决策捕获到项目本地技能中：
|
||
|
||
```bash
|
||
/gsd-sketch --wrap-up
|
||
```
|
||
|
||
此命令会写入 `.claude/skills/sketch-findings-[project]/`。该技能由 `/gsd-ui-phase` 自动获取——经过预验证的决策（布局、色彩方案、排版、间距）被视为已锁定，不会再次询问。
|
||
|
||
---
|
||
|
||
## 组合流程：spike → sketch → phase
|
||
|
||
当你对技术可行性和视觉方向都不确定时，推荐使用以下顺序：
|
||
|
||
```bash
|
||
/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 会在以下两个时间点自动读取它们：
|
||
|
||
1. **`/gsd-sketch`** — 在构建原型前加载 `.claude/skills/spike-findings-*/`，使变体反映已验证的约束（流式状态、真实字段名等）
|
||
2. **`/gsd-ui-phase N`** — 在生成 UI 设计契约前加载 `.claude/skills/sketch-findings-*/`；经过预验证的设计决策被视为已锁定
|
||
|
||
当存在 `spike-findings-*` 技能时，规划器也会读取 spike 调查结果，从而使已验证的技术选择（采用哪个库、哪种协议、哪种数据格式）直接流入任务计划，无需反复解释。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [设计 UI 阶段](design-a-ui-phase.md)
|
||
- [规划阶段](plan-a-phase.md)
|
||
- [命令参考](../COMMANDS.md)
|
||
- [文档索引](../README.md)
|