msd-core/docs/zh-CN/tutorials/your-first-project.md

你的第一个项目

在本教程中，你将安装 GSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后，你将至少运行过核心阶段循环中的每一条命令一次，并看到每条命令所生成的规划产物。

---

你将构建什么

一个 Node.js CLI 工具，支持添加、列出和完成存储在本地 JSON 文件中的待办事项。它足够小，可以在一次会话中完成，且仅使用 Node.js 标准库，无需安装任何额外依赖。

---

前提条件

• Node.js 18 或更高版本 — node --version 应打印 v18.x.x 或更高版本。
• Claude Code — 在你想使用的项目目录中打开。
• 初次安装需要网络连接。

不需要其他工具。GSD Core 本身将在下一步安装。

---

第 1 步 — 安装 GSD Core

在项目目录中打开终端并运行：

npx @opengsd/gsd-core@latest

安装程序会询问你使用的 AI 编程运行时，以及是全局安装还是安装到当前项目。现在选择 Claude Code 和本地安装（仅此项目）。

你将看到类似如下的输出：

✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start

注意项目中现在存在一个 .claude/ 目录。这是 GSD Core 的命令和代理所在的位置。

为什么选本地而不是全局？本地安装可将技能版本固定到该项目。如需全局安装，请参阅 在你的运行时上安装。

---

第 2 步 — 以权限模式启动 Claude Code

GSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code，这样它就不会在每次文件操作时暂停询问：

claude --dangerously-skip-permissions

你将进入项目目录中的 Claude Code 提示符。

---

第 3 步 — 创建项目

在 Claude Code 提示符处输入以下斜杠命令：

/gsd-new-project

GSD Core 将开启一段对话。它首先提问：

What do you want to build?

输入类似以下内容：

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 会展示一份路线图提案。对于单阶段项目，它看起来类似：

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/ 中创建的内容：

.planning/
  PROJECT.md          ← 你的项目描述和需求
  REQUIREMENTS.md     ← 每个 v1 功能的 REQ-ID
  ROADMAP.md          ← 第 1 阶段，状态：待处理
  STATE.md            ← 会话记忆，当前位置
  config.json         ← 工作流设置

现在打开 .planning/ROADMAP.md 并阅读。注意第 1 阶段有目标、必须满足的需求列表和成功标准——这些是执行必须交付的可观测行为。

---

第 4 步 — 清除上下文并讨论第 1 阶段

GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口：

/clear

然后开始第 1 阶段的讨论：

/gsd-discuss-phase 1

GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响如何构建，而不仅仅是构建什么。示例交流：

> 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 会写入：

.planning/phases/01-core-cli/CONTEXT.md

打开该文件。你会看到一个 ## Implementation Decisions 章节，准确记录了你所说的内容。规划器读取该文件——因此你在此处做出的决定将贯穿到每个任务计划中。

---

第 5 步 — 规划第 1 阶段

/gsd-plan-phase 1

四个调研子代理并行展开工作（你会看到"Spawning 4 researchers…"的提示）。这需要 1–5 分钟，请勿中断。

返回后，规划器读取 CONTEXT.md 和调研结果，创建原子任务计划。然后，计划检查器在保存之前验证每个计划是否实现了阶段目标。

创建的内容：

.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 阶段

/gsd-execute-phase 1

GSD Core 将计划分组为波次（独立计划并行运行），为每个计划生成一个全新的 200k 上下文执行器，并原子性地提交每个任务。

你将看到类似如下内容：

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

创建的内容：

.planning/phases/01-core-cli/
  01-01-SUMMARY.md    ← 执行器 A 构建并提交的内容
  01-02-SUMMARY.md    ← 执行器 B 构建并提交的内容
  VERIFICATION.md     ← REQ 覆盖情况：PASS

现在运行你的 CLI：

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 步 — 验证工作

/gsd-verify-work 1

GSD Core 提取阶段的成功标准并逐一引导你完成：

[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。

创建的内容：

.planning/phases/01-core-cli/UAT.md   ← 所有检查及其结果

---

第 8 步 — 发布

/gsd-ship 1

GSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含：摘要、变更内容、已解决的需求、验证情况和关键决策。

你将看到：

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 自动检测下一步。

---

相关资源

• 阶段循环 — 循环为何如此设计
• 操作指南 — 针对特定情况的任务型操作说明
• 接入现有代码库 — 将 GSD Core 引入棕地仓库