docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

* 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>
2026-06-02 08:13:09 -04:00
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
--- a/docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
+++ b/docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
@@ -0,0 +1,226 @@
+# 将现有代码库纳入工作流
+
+在本教程中，您将把 GSD Core 引入一个已有代码的仓库。您将对代码库进行映射，创建一个描述您所*新增*内容的项目，并针对一个小型聚焦变更运行首次讨论与规划循环。完成后，GSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
+
+---
+
+## 您将构建的内容
+
+我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小，不会分散您对真正核心内容的注意力：GSD Core 在规划任何内容之前如何学习您的代码库。
+
+---
+
+## 前提条件
+
+- **Node.js 18 或更高版本** — `node --version` 应输出 `v18.x.x` 或更高版本。
+- **一个现有项目** — 任何已有代码的仓库。不必须是 Express；这些步骤适用于任何技术栈。
+- **Claude Code** — 在您的仓库根目录中打开。
+
+---
+
+## 第 1 步 — 安装 GSD Core
+
+在您的仓库根目录执行：
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+在提示时选择 **Claude Code** 和 **local**。您将看到：
+
+```text
+✓ Installed 86 skills to .claude/commands/
+✓ Installed agents to .claude/agents/
+✓ GSD Core ready — run /gsd-new-project to start
+```
+
+---
+
+## 第 2 步 — 使用权限启动 Claude Code
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+---
+
+## 第 3 步 — 映射代码库
+
+在创建项目之前，先让 GSD Core 了解已有的内容。这是使棕地规划准确的关键步骤。
+
+```text
+/gsd-map-codebase
+```
+
+GSD Core 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：
+
+| 代理 | 关注点 |
+|-------|-------|
+| 技术映射器 | 技术栈、框架、依赖项 |
+| 架构映射器 | 模式、层次、数据流 |
+| 质量映射器 | 规范、测试实践 |
+| 关注点映射器 | 技术债务、风险领域 |
+
+当所有四个代理返回后，您将看到：
+
+```text
+Codebase mapping complete.
+
+Created .planning/codebase/:
+- STACK.md        (47 lines) - Technologies and dependencies
+- ARCHITECTURE.md (62 lines) - System design and patterns
+- STRUCTURE.md    (38 lines) - Directory layout and organisation
+- CONVENTIONS.md  (55 lines) - Code style and patterns
+- TESTING.md      (41 lines) - Test structure and practices
+- INTEGRATIONS.md (29 lines) - External services and APIs
+- CONCERNS.md     (33 lines) - Technical debt and issues
+```
+
+打开 `.planning/codebase/STACK.md`。您将看到 GSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件，而非猜测。
+
+打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。GSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
+
+打开 `.planning/codebase/CONCERNS.md`。在进行任何新功能开发之前，这是最值得阅读的文件——它会展现可能影响您计划的技术债务和脆弱区域。
+
+---
+
+## 第 4 步 — 清除上下文并创建项目
+
+清除会话窗口：
+
+```text
+/clear
+```
+
+现在创建项目。由于 GSD Core 在上一步中发现了现有代码，它已经知道这是一个棕地项目。当您运行 `/gsd-new-project` 时，问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
+
+```text
+/gsd-new-project
+```
+
+GSD Core 会询问您想构建什么。请用您正在添加的功能来回答，而不是描述整个代码库：
+
+```text
+Add a GET /health endpoint to the Express app. It should return
+{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
+health checks.
+```
+
+GSD Core 会进一步提出少量澄清问题，然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`，它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
+
+对所有工作流设置选择推荐默认值。
+
+当路线图子代理返回后，您将看到一个建议的路线图。对于单个小型变更，它将只有一个阶段：
+
+```text
+Proposed Roadmap
+
+1 phase | 2 requirements mapped | All v1 requirements covered ✓
+
+| # | Phase          | Goal                                          | Requirements |
+|---|----------------|-----------------------------------------------|--------------|
+| 1 | Health endpoint| GET /health returning status and uptime JSON  | HLT-01, HLT-02 |
+```
+
+批准路线图。
+
+**在 `.planning/` 中创建的内容：**
+
+```text
+.planning/
+  PROJECT.md          ← project description; existing capabilities in "Validated"
+  REQUIREMENTS.md     ← HLT-01, HLT-02
+  ROADMAP.md          ← Phase 1, status: pending
+  STATE.md            ← session memory
+  config.json         ← workflow settings
+  codebase/           ← the seven map files from Step 3
+```
+
+注意 `.planning/codebase/` 已经从第 3 步存在。GSD Core 在编写 `PROJECT.md` 时读取了这些文件，这就是为什么它无需您描述即可填充已验证的需求。
+
+---
+
+## 第 5 步 — 清除上下文并讨论第 1 阶段
+
+```text
+/clear
+```
+
+```text
+/gsd-discuss-phase 1
+```
+
+由于 GSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`，其问题基于您的实际代码库——而非通用建议。您可能会看到：
+
+```text
+> Your routes are registered in src/routes/index.js. Should the health
+  endpoint live there, or in a dedicated src/routes/health.js?
+  A dedicated health.js — keep routes separated.
+
+> Your existing error middleware returns { error: "message" }. Should
+  /health use the same shape for error responses?
+  Yes, stay consistent.
+
+> Should uptime be calculated from process.uptime() or a stored start time?
+  process.uptime() is fine.
+```
+
+讨论结束后，GSD Core 将写入：
+
+```text
+.planning/phases/01-health-endpoint/CONTEXT.md
+```
+
+打开该文件。`## Implementation Decisions` 部分记录了您的回答。规划器将在编写任何任务之前读取此文件——因此您关于文件位置和响应格式的偏好将出现在计划中，而不仅仅停留在讨论里。
+
+---
+
+## 第 6 步 — 规划第 1 阶段
+
+```text
+/gsd-plan-phase 1
+```
+
+四个研究子代理并行运行（1–5 分钟）。当它们返回后，规划器读取 `CONTEXT.md`、研究结果和您的代码库映射，创建符合您规范的任务计划。
+
+**创建的内容：**
+
+```text
+.planning/phases/01-health-endpoint/
+  RESEARCH.md         ← findings on health endpoint patterns
+  01-01-PLAN.md       ← Task: create src/routes/health.js
+  01-02-PLAN.md       ← Task: register health route in src/routes/index.js
+```
+
+打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径，与 GSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
+
+---
+
+## 下一步
+
+您现在拥有一个带有代码库映射、讨论决策记录和经过验证的任务计划的项目——所有内容均基于您的实际代码。从这里开始，工作流与绿地项目完全相同：
+
+```text
+/gsd-execute-phase 1
+/gsd-verify-work 1
+/gsd-ship 1
+```
+
+对于每个未来的功能，当结构发生重大变化时，再次运行 `/gsd-map-codebase`，以保持代码库映射的时效性。
+
+---
+
+## 您学到了什么
+
+- `/gsd-map-codebase` 如何运行四个并行代理，在 `.planning/codebase/` 中生成 `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md` 和 `INTEGRATIONS.md`。
+- 在棕地仓库中运行 `/gsd-new-project` 如何将问题聚焦于您所*新增*的内容，并从现有代码中填充已验证的需求。
+- 代码库映射如何塑造 `/gsd-discuss-phase` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
+- 规划器如何读取 `CONTEXT.md` 和 `CONVENTIONS.md` 来生成符合您仓库风格的计划。
+
+---
+
+## 相关内容
+
+- [您的第一个项目](your-first-project.md) — 从安装到 PR 的完整绿地循环
+- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/gsd-map-codebase` 标志和子命令
+- [文档索引](../README.md)
--- a/docs/zh-CN/tutorials/your-first-project.md
+++ b/docs/zh-CN/tutorials/your-first-project.md
@@ -0,0 +1,291 @@
+# 你的第一个项目
+
+在本教程中，你将安装 GSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后，你将至少运行过核心阶段循环中的每一条命令一次，并看到每条命令所生成的规划产物。
+
+---
+
+## 你将构建什么
+
+一个 Node.js CLI 工具，支持添加、列出和完成存储在本地 JSON 文件中的待办事项。它足够小，可以在一次会话中完成，且仅使用 Node.js 标准库，无需安装任何额外依赖。
+
+---
+
+## 前提条件
+
+- **Node.js 18 或更高版本** — `node --version` 应打印 `v18.x.x` 或更高版本。
+- **Claude Code** — 在你想使用的项目目录中打开。
+- 初次安装需要网络连接。
+
+不需要其他工具。GSD Core 本身将在下一步安装。
+
+---
+
+## 第 1 步 — 安装 GSD Core
+
+在项目目录中打开终端并运行：
+
+```bash
+npx @opengsd/gsd-core@latest
+```
+
+安装程序会询问你使用的 AI 编程运行时，以及是全局安装还是安装到当前项目。现在选择 **Claude Code** 和**本地安装**（仅此项目）。
+
+你将看到类似如下的输出：
+
+```text
+✓ Installed 86 skills to .claude/commands/
+✓ Installed agents to .claude/agents/
+✓ GSD Core ready — run /gsd-new-project to start
+```
+
+注意项目中现在存在一个 `.claude/` 目录。这是 GSD Core 的命令和代理所在的位置。
+
+> 为什么选本地而不是全局？本地安装可将技能版本固定到该项目。如需全局安装，请参阅 [在你的运行时上安装](../how-to/install-on-your-runtime.md)。
+
+---
+
+## 第 2 步 — 以权限模式启动 Claude Code
+
+GSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code，这样它就不会在每次文件操作时暂停询问：
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+你将进入项目目录中的 Claude Code 提示符。
+
+---
+
+## 第 3 步 — 创建项目
+
+在 Claude Code 提示符处输入以下斜杠命令：
+
+```text
+/gsd-new-project
+```
+
+GSD Core 将开启一段对话。它首先提问：
+
+```text
+What do you want to build?
+```
+
+输入类似以下内容：
+
+```text
+A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
+`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
+No external dependencies — Node built-ins only.
+```
+
+GSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前，正在了解你的关注点。
+
+问题结束后，它会提议进行领域调研。对于如此小的项目，你可以跳过调研——在提示时选择**跳过调研**。
+
+GSD Core 随后会要求你选择工作流设置（模式、粒度、调研代理）。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
+
+最后，一个路线图子代理开始运行（你会看到"Spawning roadmapper…"的提示——这是正常的，大约需要一分钟）。返回后，GSD Core 会展示一份路线图提案。对于单阶段项目，它看起来类似：
+
+```text
+Proposed Roadmap
+
+1 phase | 4 requirements mapped | All v1 requirements covered ✓
+
+| # | Phase              | Goal                                    | Requirements      |
+|---|--------------------|-----------------------------------------|-------------------|
+| 1 | Core CLI           | add / list / done commands, todos.json  | CLI-01 … CLI-04   |
+```
+
+输入 **Approve** 以接受路线图。
+
+**`.planning/` 中创建的内容：**
+
+```text
+.planning/
+  PROJECT.md          ← 你的项目描述和需求
+  REQUIREMENTS.md     ← 每个 v1 功能的 REQ-ID
+  ROADMAP.md          ← 第 1 阶段，状态：待处理
+  STATE.md            ← 会话记忆，当前位置
+  config.json         ← 工作流设置
+```
+
+现在打开 `.planning/ROADMAP.md` 并阅读。注意第 1 阶段有目标、必须满足的需求列表和成功标准——这些是执行必须交付的可观测行为。
+
+---
+
+## 第 4 步 — 清除上下文并讨论第 1 阶段
+
+GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口：
+
+```text
+/clear
+```
+
+然后开始第 1 阶段的讨论：
+
+```text
+/gsd-discuss-phase 1
+```
+
+GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建，而不仅仅是*构建什么*。示例交流：
+
+```text
+> How should done items be stored — mark them in place or move them?
+  Mark them in place with a "done" flag.
+
+> Should `todo list` show completed items by default?
+  No, hide them unless --all is passed.
+
+> Error format when todos.json doesn't exist yet?
+  Create it silently on first add.
+```
+
+讨论结束后，GSD Core 会写入：
+
+```text
+.planning/phases/01-core-cli/CONTEXT.md
+```
+
+打开该文件。你会看到一个 `## Implementation Decisions` 章节，准确记录了你所说的内容。规划器读取该文件——因此你在此处做出的决定将贯穿到每个任务计划中。
+
+---
+
+## 第 5 步 — 规划第 1 阶段
+
+```text
+/gsd-plan-phase 1
+```
+
+四个调研子代理并行展开工作（你会看到"Spawning 4 researchers…"的提示）。这需要 1–5 分钟，请勿中断。
+
+返回后，规划器读取 CONTEXT.md 和调研结果，创建原子任务计划。然后，计划检查器在保存之前验证每个计划是否实现了阶段目标。
+
+**创建的内容：**
+
+```text
+.planning/phases/01-core-cli/
+  RESEARCH.md         ← 领域调研结果
+  01-01-PLAN.md       ← 任务：创建 todos.json 读写助手
+  01-02-PLAN.md       ← 任务：实现 add / list / done 命令
+```
+
+打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块，包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——GSD Core 的执行器将在写入代码后运行该命令。
+
+---
+
+## 第 6 步 — 执行第 1 阶段
+
+```text
+/gsd-execute-phase 1
+```
+
+GSD Core 将计划分组为波次（独立计划并行运行），为每个计划生成一个全新的 200k 上下文执行器，并原子性地提交每个任务。
+
+你将看到类似如下内容：
+
+```text
+Wave 1 (parallel):
+  [Executor A] → 01-01-PLAN.md (read/write helpers)   ✓ committed
+  [Executor B] → 01-02-PLAN.md (CLI commands)          ✓ committed
+
+[Verifier] Checking codebase against phase goals...
+  CLI-01 todo add   ✓
+  CLI-02 todo list  ✓
+  CLI-03 todo done  ✓
+  CLI-04 --all flag ✓
+  Status: PASS
+```
+
+**创建的内容：**
+
+```text
+.planning/phases/01-core-cli/
+  01-01-SUMMARY.md    ← 执行器 A 构建并提交的内容
+  01-02-SUMMARY.md    ← 执行器 B 构建并提交的内容
+  VERIFICATION.md     ← REQ 覆盖情况：PASS
+```
+
+现在运行你的 CLI：
+
+```bash
+node todo.js add "buy milk"
+node todo.js add "write tests"
+node todo.js list
+node todo.js done 1
+node todo.js list
+```
+
+你应该看到条目出现，并且在标记完成后，条目 1 从默认列表中消失。这是 GSD Core 交付的你的第一个可见结果。
+
+---
+
+## 第 7 步 — 验证工作
+
+```text
+/gsd-verify-work 1
+```
+
+GSD Core 提取阶段的成功标准并逐一引导你完成：
+
+```text
+[1/3] Can you run `node todo.js add "buy milk"` without errors?
+> yes
+
+[2/3] Does `node todo.js list` show only incomplete items by default?
+> yes
+
+[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
+> yes
+
+All 3 checks passed. Phase 1 verified.
+```
+
+如果任何检查失败，GSD Core 会诊断根本原因并创建修复计划。再次运行 `/gsd-execute-phase 1` 应用修复，然后重新运行 `/gsd-verify-work 1`。
+
+**创建的内容：**
+
+```text
+.planning/phases/01-core-cli/UAT.md   ← 所有检查及其结果
+```
+
+---
+
+## 第 8 步 — 发布
+
+```text
+/gsd-ship 1
+```
+
+GSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含：摘要、变更内容、已解决的需求、验证情况和关键决策。
+
+你将看到：
+
+```text
+Pull request created: https://github.com/your-org/your-repo/pull/1
+
+Title: feat(phase-1): core CLI — add / list / done commands
+```
+
+这就是完整的流程——从想法到合并 PR——一个阶段。
+
+---
+
+## 你学到了什么
+
+- 如何使用 `npx @opengsd/gsd-core@latest` 安装 GSD Core。
+- `/gsd-new-project` 如何将一段对话转化为由 `.planning/` 产物支撑的路线图。
+- `/gsd-discuss-phase` 如何在任何规划开始之前捕获实现决策。
+- `/gsd-plan-phase` 如何生成并行调研器并产出原子任务计划。
+- `/gsd-execute-phase` 如何以并行波次运行这些计划并提交每个任务。
+- `/gsd-verify-work` 如何引导完成成功标准并在需要时生成修复计划。
+- `/gsd-ship` 如何将已验证的阶段转化为拉取请求。
+
+对于多阶段项目，对每个阶段重复第 4–8 步，然后运行 `/gsd-progress --next`，让 GSD Core 自动检测下一步。
+
+---
+
+## 相关资源
+
+- [阶段循环](../explanation/the-phase-loop.md) — 循环为何如此设计
+- [操作指南](../README.md#how-to-guides) — 针对特定情况的任务型操作说明
+- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 GSD Core 引入棕地仓库