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/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 引入棕地仓库