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>
177 lines
5.3 KiB
Markdown
177 lines
5.3 KiB
Markdown
# 如何从追踪器议题驱动 GSD Core
|
||
|
||
**目标：** 将一个范围明确的 GitHub、Linear 或 Jira 议题，通过完整的 GSD 流水线从隔离工作区推进至合并 PR——仅使用 GSD Core 中已有的命令，无需任何自定义脚本或追踪器集成。
|
||
|
||
**前提条件：** GSD Core 已安装。议题范围有边界、验收标准可观测，且无上游阻塞依赖。
|
||
|
||
有关该模式背后的概念与设计理由，请参阅[议题驱动编排详解](../issue-driven-orchestration.md)。
|
||
|
||
---
|
||
|
||
## 第一步：将议题映射到阶段
|
||
|
||
打开追踪器议题，决定它如何对应 `ROADMAP.md` 中的阶段：
|
||
|
||
- **议题与现有阶段匹配** → 记下阶段编号，转至第二步。
|
||
- **议题是独立的新工作** → 添加一个阶段：
|
||
|
||
```bash
|
||
/gsd-phase "描述与议题标题一致的内容"
|
||
```
|
||
|
||
- **议题紧急，必须插入现有阶段之间** → 插入一个小数阶段：
|
||
|
||
```bash
|
||
/gsd-phase --insert 3 "Fix: 来自议题的描述"
|
||
```
|
||
|
||
复制追踪器议题的 URL。您将在第三步中将其粘贴到 `CONTEXT.md`，以便在上下文压缩后仍保留可追溯性。
|
||
|
||
---
|
||
|
||
## 第二步：创建隔离工作区
|
||
|
||
每个议题都有专属工作区——一个带有独立 `.planning/` 目录的 git worktree。未完成的工作、中止的计划和探索性提交均保留在 `main` 之外。
|
||
|
||
```bash
|
||
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
|
||
```
|
||
|
||
继续操作前，切换到工作区目录：
|
||
|
||
```bash
|
||
cd ~/gsd-workspaces/my-issue-slug
|
||
```
|
||
|
||
---
|
||
|
||
## 第三步：讨论阶段
|
||
|
||
运行 discuss-phase，在规划开始之前确定实现决策。会话打开后，将追踪器议题 URL 粘贴到讨论中，以便记录到 `CONTEXT.md`。
|
||
|
||
```bash
|
||
/gsd-discuss-phase N
|
||
```
|
||
|
||
GSD 会就议题范围中的模糊点进行提问——错误处理、边界情况、接口契约、技术选型。您的回答将影响后续生成的计划。
|
||
|
||
如果您已知晓所有答案并希望快速推进：
|
||
|
||
```bash
|
||
/gsd-discuss-phase N --auto
|
||
```
|
||
|
||
---
|
||
|
||
## 第四步：规划阶段
|
||
|
||
```bash
|
||
/gsd-plan-phase N
|
||
```
|
||
|
||
GSD 会派生研究代理，读取您的 `CONTEXT.md` 决策（包括议题 URL），并生成原子化的 `PLAN.md` 文件。计划检查器会在保存前验证每份计划。
|
||
|
||
如果您希望在执行前由外部 AI CLI 进行同行评审（对于重大变更推荐使用）：
|
||
|
||
```bash
|
||
/gsd-review --phase N
|
||
/gsd-plan-phase N --reviews
|
||
```
|
||
|
||
或运行完整的计划-评审-收敛循环，直到不再有 HIGH 级别的问题：
|
||
|
||
```bash
|
||
/gsd-plan-review-convergence N
|
||
```
|
||
|
||
---
|
||
|
||
## 第五步：执行阶段
|
||
|
||
交互式逐阶段执行：
|
||
|
||
```bash
|
||
/gsd-execute-phase N
|
||
```
|
||
|
||
无人值守地运行所有剩余阶段：
|
||
|
||
```bash
|
||
/gsd-autonomous
|
||
```
|
||
|
||
在可视化仪表盘中监控进度并跨阶段调度工作：
|
||
|
||
```bash
|
||
/gsd-manager
|
||
```
|
||
|
||
三种方式均会更新 `STATE.md`，原子化提交每项任务，并运行阶段后验证器。
|
||
|
||
---
|
||
|
||
## 第六步：验证工作
|
||
|
||
```bash
|
||
/gsd-verify-work N
|
||
```
|
||
|
||
GSD 会逐条引导您核对阶段目标中的验收标准（与追踪器议题对应）。如有失败，GSD 会诊断根本原因并创建修复计划。重复执行和重新验证，直到所有检查通过。
|
||
|
||
即使代码看起来正确，也应将 `verification_failed` 视为阻塞——失败通常会揭示原始议题中遗漏的验收标准。
|
||
|
||
---
|
||
|
||
## 第七步：评审与发布
|
||
|
||
在开启 PR 前先进行代码评审：
|
||
|
||
```bash
|
||
/gsd-code-review N
|
||
/gsd-code-review N --fix
|
||
```
|
||
|
||
然后创建 PR：
|
||
|
||
```bash
|
||
/gsd-ship N
|
||
```
|
||
|
||
GSD 会从您的规划产物中组装 PR 正文：阶段目标、变更摘要、已满足的需求、验证状态和关键决策。在 PR 正文中加入 `Closes #NNN` 或 `Fixes #NNN`（或通过 `/gsd-config` 设置），以便在 PR 合并时自动关闭追踪器议题。
|
||
|
||
---
|
||
|
||
## 第八步：记录后续工作
|
||
|
||
在处理议题的过程中，您常常会发现相关工作。在不丢失上下文的情况下进行记录：
|
||
|
||
```bash
|
||
/gsd-capture "Follow-up: 发现的工作描述" # 作为待办事项添加
|
||
/gsd-capture --seed "值得未来阶段考虑的想法" # 为下一个里程碑保留
|
||
/gsd-capture --backlog "不紧急但值得跟踪的内容" # 存入待办列表
|
||
```
|
||
|
||
GSD 不会自动向追踪器发布内容。从已记录的后续工作中创建追踪器议题是独立的手动步骤——这保留了人工审核的环节。
|
||
|
||
---
|
||
|
||
## 条件场景
|
||
|
||
| 情境 | 处理方式 |
|
||
|-----------|-----------|
|
||
| 议题非常小（拼写错误、配置变更） | 跳过工作区 + 讨论 + 规划；改用 `/gsd-quick` |
|
||
| 议题包含多个独立子任务 | 使用 `/gsd-manager` 跨计划并行执行 |
|
||
| 议题被其他议题阻塞 | 在上游阻塞解除前不要开始；GSD 没有自动依赖轮询 |
|
||
| 执行中途发现议题范围比预期大 | 停止，运行 `/gsd-phase --insert N` 添加子阶段，然后继续 |
|
||
| 想跳过交互式讨论 | 对 `/gsd-discuss-phase` 使用 `--auto` 标志，或为项目级自动化设置 `workflow.skip_discuss: true` |
|
||
| 多个议题构成一个连贯的发布版本 | 运行 `/gsd-new-milestone` 将其分组，并运行 `/gsd-autonomous` 按顺序执行 |
|
||
|
||
---
|
||
|
||
## 相关资源
|
||
|
||
- [议题驱动编排详解](../issue-driven-orchestration.md)
|
||
- [使用工作区隔离工作](isolate-work-with-workspaces.md)
|
||
- [验证与发布](verify-and-ship.md)
|
||
- [文档索引](../README.md)
|