golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: hard-fork GSD -> MSD (Make Software Done)

Browse Source 
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/zh-CN/tutorials/onboarding-an-existing-codebase.md
View File

@@ -1,12 +1,12 @@
# 将现有代码库纳入工作流
在本教程中，您将把 GSD Core 引入一个已有代码的仓库。您将对代码库进行映射，创建一个描述您所*新增*内容的项目，并针对一个小型聚焦变更运行首次讨论与规划循环。完成后，GSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
在本教程中，您将把 MSD Core 引入一个已有代码的仓库。您将对代码库进行映射，创建一个描述您所*新增*内容的项目，并针对一个小型聚焦变更运行首次讨论与规划循环。完成后，MSD Core 的规划流水线将了解您的技术栈、规范和关注点——并在每次规划时运用这些知识。
---
## 您将构建的内容
我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小，不会分散您对真正核心内容的注意力：GSD Core 在规划任何内容之前如何学习您的代码库。
我们将向一个现有的 Express 应用程序添加一个 `GET /health` 端点。该变更足够小，不会分散您对真正核心内容的注意力：MSD Core 在规划任何内容之前如何学习您的代码库。
---
@@ -18,12 +18,12 @@
---
## 第 1 步 — 安装 GSD Core
## 第 1 步 — 安装 MSD Core
在您的仓库根目录执行：
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
在提示时选择 **Claude Code** 和 **local**。您将看到：
@@ -31,7 +31,7 @@ npx @opengsd/gsd-core@latest
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
✓ MSD Core ready — run /msd-new-project to start
```
---
@@ -44,7 +44,7 @@ claude --dangerously-skip-permissions
> [!CAUTION]
> **The permissions flag is optional.** It skips per-file confirmation while
> GSD's sub-agents read and write files. Use it only in low-stakes or
> MSD's sub-agents read and write files. Use it only in low-stakes or
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
> For real work, read the [security model](../explanation/security-model.md) first.
@@ -53,13 +53,13 @@ claude --dangerously-skip-permissions
## 第 3 步 — 开始 brownfield onboarding
在创建项目之前，让 GSD Core 检查仓库状态并告诉您安全的下一个顶层命令。这一步可避免跳过代码库上下文或覆盖现有 planning 文件。
在创建项目之前，让 MSD Core 检查仓库状态并告诉您安全的下一个顶层命令。这一步可避免跳过代码库上下文或覆盖现有 planning 文件。
```text
/gsd-onboard
/msd-onboard
```
如果 onboarding 报告缺少代码库映射，请选择推荐选项并运行打印出的 `/gsd-map-codebase` 交接命令，然后重新运行 `/gsd-onboard`。`/gsd-onboard --fast` 只适合轻量首次通过；在 `/gsd-new-project` 前仍需要完整映射。`/gsd-map-codebase` 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：
如果 onboarding 报告缺少代码库映射，请选择推荐选项并运行打印出的 `/msd-map-codebase` 交接命令，然后重新运行 `/msd-onboard`。`/msd-onboard --fast` 只适合轻量首次通过；在 `/msd-new-project` 前仍需要完整映射。`/msd-map-codebase` 会派生四个并行映射子代理（您将看到"Spawning 4 parallel codebase mapper agents…"——这需要 1–5 分钟；请勿中断）。每个代理专注于不同的关注点：
| 代理 | 关注点 |
|-------|-------|
@@ -83,9 +83,9 @@ Created .planning/codebase/:
- CONCERNS.md (33 lines) - Technical debt and issues
```
打开 `.planning/codebase/STACK.md`。您将看到 GSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件，而非猜测。
打开 `.planning/codebase/STACK.md`。您将看到 MSD Core 检测到的语言、运行时、框架版本和关键依赖项——这些内容基于实际读取的文件，而非猜测。
打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。GSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
打开 `.planning/codebase/CONVENTIONS.md`。您将看到它从您的源代码中观察到的命名规范、错误处理模式和代码风格规则。MSD Core 为该仓库生成的每个计划都将自动遵循这些规范。
打开 `.planning/codebase/CONCERNS.md`。在进行任何新功能开发之前，这是最值得阅读的文件——它会展现可能影响您计划的技术债务和脆弱区域。
@@ -99,15 +99,15 @@ Created .planning/codebase/:
/clear
```
现在再次运行 `/gsd-onboard`。如果 GSD Core 检测到 ADR、PRD、spec、RFC 或根级需求文档，请先接受推荐的 `/gsd-ingest-docs` 交接，然后再运行 `/gsd-onboard`。上下文准备好后，onboarding 会打印项目初始化交接命令：
现在再次运行 `/msd-onboard`。如果 MSD Core 检测到 ADR、PRD、spec、RFC 或根级需求文档，请先接受推荐的 `/msd-ingest-docs` 交接，然后再运行 `/msd-onboard`。上下文准备好后，onboarding 会打印项目初始化交接命令：
```text
/gsd-new-project
/msd-new-project
```
由于 GSD Core 在上一步中发现了现有代码，`/gsd-new-project` 知道这是一个棕地项目。问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
由于 MSD Core 在上一步中发现了现有代码，`/msd-new-project` 知道这是一个棕地项目。问题将聚焦于您所*新增*的内容，而非重新描述已有的内容：
GSD Core 会询问您想构建什么。请用您正在添加的功能来回答，而不是描述整个代码库：
MSD Core 会询问您想构建什么。请用您正在添加的功能来回答，而不是描述整个代码库：
```text
Add a GET /health endpoint to the Express app. It should return
@@ -115,7 +115,7 @@ Add a GET /health endpoint to the Express app. It should return
health checks.
```
GSD Core 会进一步提出少量澄清问题，然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`，它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
MSD Core 会进一步提出少量澄清问题，然后继续创建需求和路线图。由于它已读取 `ARCHITECTURE.md` 和 `STACK.md`，它会自动将现有能力映射到 `PROJECT.md` 的 **Validated** 部分——您无需描述现有的 API 接口。
对所有工作流设置选择推荐默认值。
@@ -133,7 +133,7 @@ Proposed Roadmap
批准路线图。
项目设置完成后，再运行一次 `/gsd-onboard`。现在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 都已存在，onboarding 会创建或确认 `.planning/onboarding/SUMMARY.md`。
项目设置完成后，再运行一次 `/msd-onboard`。现在 `PROJECT.md`、`REQUIREMENTS.md`、`ROADMAP.md` 和 `STATE.md` 都已存在，onboarding 会创建或确认 `.planning/onboarding/SUMMARY.md`。
**在 `.planning/` 中创建的内容：**
@@ -148,7 +148,7 @@ Proposed Roadmap
codebase/ ← 第 3 步生成的七个映射文件
```
注意 `.planning/codebase/` 已经从第 3 步存在。GSD Core 在编写 `PROJECT.md` 时读取了这些文件，这就是为什么它无需您描述即可填充已验证的需求。
注意 `.planning/codebase/` 已经从第 3 步存在。MSD Core 在编写 `PROJECT.md` 时读取了这些文件，这就是为什么它无需您描述即可填充已验证的需求。
---
@@ -159,10 +159,10 @@ Proposed Roadmap
```
```text
/gsd-discuss-phase 1
/msd-discuss-phase 1
```
由于 GSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`，其问题基于您的实际代码库——而非通用建议。您可能会看到：
由于 MSD Core 已读取您的 `CONVENTIONS.md` 和 `ARCHITECTURE.md`，其问题基于您的实际代码库——而非通用建议。您可能会看到：
```text
> Your routes are registered in src/routes/index.js. Should the health
@@ -177,7 +177,7 @@ Proposed Roadmap
process.uptime() is fine.
```
讨论结束后，GSD Core 将写入：
讨论结束后，MSD Core 将写入：
```text
.planning/phases/01-health-endpoint/CONTEXT.md
@@ -190,7 +190,7 @@ Proposed Roadmap
## 第 6 步 — 规划第 1 阶段
```text
/gsd-plan-phase 1
/msd-plan-phase 1
```
四个研究子代理并行运行（1–5 分钟）。当它们返回后，规划器读取 `CONTEXT.md`、研究结果和您的代码库映射，创建符合您规范的任务计划。
@@ -204,7 +204,7 @@ Proposed Roadmap
01-02-PLAN.md ← Task: register health route in src/routes/index.js
```
打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径，与 GSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
打开 `01-01-PLAN.md`。注意 `<files>` 标签引用了 `src/routes/health.js`——正是您在讨论中指定的路径，与 MSD Core 在代码库映射中观察到的路由模式一致。这正是代码库映射发挥作用的体现。
---
@@ -213,21 +213,21 @@ Proposed Roadmap
您现在拥有一个带有代码库映射、讨论决策记录和经过验证的任务计划的项目——所有内容均基于您的实际代码。从这里开始，工作流与绿地项目完全相同：
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
/msd-execute-phase 1
/msd-verify-work 1
/msd-ship 1
```
对于每个未来的功能，当结构发生重大变化时，再次运行 `/gsd-map-codebase`，以保持代码库映射的时效性。
对于每个未来的功能，当结构发生重大变化时，再次运行 `/msd-map-codebase`，以保持代码库映射的时效性。
---
## 您学到了什么
- `/gsd-onboard` 如何安全编排 brownfield 设置，不嵌套交互式命令，也不覆盖现有 planning 文件。
- `/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` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
- `/msd-onboard` 如何安全编排 brownfield 设置，不嵌套交互式命令，也不覆盖现有 planning 文件。
- `/msd-map-codebase` 如何运行四个并行代理，在 `.planning/codebase/` 中生成 `STACK.md`、`ARCHITECTURE.md`、`CONVENTIONS.md`、`CONCERNS.md`、`STRUCTURE.md`、`TESTING.md` 和 `INTEGRATIONS.md`。
- 在棕地仓库中运行 `/msd-new-project` 如何将问题聚焦于您所*新增*的内容，并从现有代码中填充已验证的需求。
- 代码库映射如何塑造 `/msd-discuss-phase` 中的每个问题——文件路径、模式和规范均来自您的实际代码。
- 规划器如何读取 `CONTEXT.md` 和 `CONVENTIONS.md` 来生成符合您仓库风格的计划。
---
@@ -235,5 +235,5 @@ Proposed Roadmap
## 相关内容
- [您的第一个项目](your-first-project.md) — 从安装到 PR 的完整绿地循环
- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/gsd-map-codebase` 标志和子命令
- [通过命令使用映射代码库](../COMMANDS.md) — 所有 `/msd-map-codebase` 标志和子命令
- [文档索引](../README.md)

70
docs/zh-CN/tutorials/your-first-project.md
View File

@@ -1,6 +1,6 @@
# 你的第一个项目
在本教程中，你将安装 GSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后，你将至少运行过核心阶段循环中的每一条命令一次，并看到每条命令所生成的规划产物。
在本教程中，你将安装 MSD Core 并从头构建一个小型命令行待办事项应用——一个阶段、一个 PR、完整的流程循环。完成后，你将至少运行过核心阶段循环中的每一条命令一次，并看到每条命令所生成的规划产物。
---
@@ -16,16 +16,16 @@
- **Claude Code** — 在你想使用的项目目录中打开。
- 初次安装需要网络连接。
不需要其他工具。GSD Core 本身将在下一步安装。
不需要其他工具。MSD Core 本身将在下一步安装。
---
## 第 1 步 — 安装 GSD Core
## 第 1 步 — 安装 MSD Core
在项目目录中打开终端并运行：
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
安装程序会询问你使用的 AI 编程运行时，以及是全局安装还是安装到当前项目。现在选择 **Claude Code** 和**本地安装**（仅此项目）。
@@ -35,10 +35,10 @@ npx @opengsd/gsd-core@latest
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
✓ MSD Core ready — run /msd-new-project to start
```
注意项目中现在存在一个 `.claude/` 目录。这是 GSD Core 的命令和代理所在的位置。
注意项目中现在存在一个 `.claude/` 目录。这是 MSD Core 的命令和代理所在的位置。
> 为什么选本地而不是全局？本地安装可将技能版本固定到该项目。如需全局安装，请参阅 [在你的运行时上安装](../how-to/install-on-your-runtime.md)。
@@ -46,7 +46,7 @@ npx @opengsd/gsd-core@latest
## 第 2 步 — 以权限模式启动 Claude Code
GSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code，这样它就不会在每次文件操作时暂停询问：
MSD Core 会生成读写文件的子代理。以权限标志启动 Claude Code，这样它就不会在每次文件操作时暂停询问：
```bash
claude --dangerously-skip-permissions
@@ -61,10 +61,10 @@ claude --dangerously-skip-permissions
在 Claude Code 提示符处输入以下斜杠命令：
```text
/gsd-new-project
/msd-new-project
```
GSD Core 将开启一段对话。它首先提问：
MSD Core 将开启一段对话。它首先提问：
```text
What do you want to build?
@@ -78,13 +78,13 @@ A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
No external dependencies — Node built-ins only.
```
GSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前，正在了解你的关注点。
MSD Core 会继续提出几个澄清性问题。自然地回答即可。它在撰写任何计划之前，正在了解你的关注点。
问题结束后，它会提议进行领域调研。对于如此小的项目，你可以跳过调研——在提示时选择**跳过调研**。
GSD Core 随后会要求你选择工作流设置（模式、粒度、调研代理）。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
MSD Core 随后会要求你选择工作流设置（模式、粒度、调研代理）。每项均选择推荐的默认值。这些设置将写入 `.planning/config.json`。
最后，一个路线图子代理开始运行（你会看到"Spawning roadmapper…"的提示——这是正常的，大约需要一分钟）。返回后，GSD Core 会展示一份路线图提案。对于单阶段项目，它看起来类似：
最后，一个路线图子代理开始运行（你会看到"Spawning roadmapper…"的提示——这是正常的，大约需要一分钟）。返回后，MSD Core 会展示一份路线图提案。对于单阶段项目，它看起来类似：
```text
Proposed Roadmap
@@ -115,7 +115,7 @@ Proposed Roadmap
## 第 4 步 — 清除上下文并讨论第 1 阶段
GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口：
MSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会话窗口：
```text
/clear
@@ -124,10 +124,10 @@ GSD Core 的设计围绕全新的上下文。在每个阶段之前清除主会
然后开始第 1 阶段的讨论：
```text
/gsd-discuss-phase 1
/msd-discuss-phase 1
```
GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建，而不仅仅是*构建什么*。示例交流：
MSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*如何*构建，而不仅仅是*构建什么*。示例交流：
```text
> How should done items be stored — mark them in place or move them?
@@ -140,7 +140,7 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
Create it silently on first add.
```
讨论结束后，GSD Core 会写入：
讨论结束后，MSD Core 会写入：
```text
.planning/phases/01-core-cli/CONTEXT.md
@@ -153,7 +153,7 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
## 第 5 步 — 规划第 1 阶段
```text
/gsd-plan-phase 1
/msd-plan-phase 1
```
四个调研子代理并行展开工作（你会看到"Spawning 4 researchers…"的提示）。这需要 1–5 分钟，请勿中断。
@@ -169,17 +169,17 @@ GSD Core 读取阶段目标并询问你的实现偏好。这些决定将影响*
01-02-PLAN.md ← 任务：实现 add / list / done 命令
```
打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块，包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——GSD Core 的执行器将在写入代码后运行该命令。
打开 `01-01-PLAN.md`。你会看到一个 `<task>` 块，包含名称、涉及的文件、操作步骤、验证命令和完成条件。注意 `<verify>` 标签——MSD Core 的执行器将在写入代码后运行该命令。
---
## 第 6 步 — 执行第 1 阶段
```text
/gsd-execute-phase 1
/msd-execute-phase 1
```
GSD Core 将计划分组为波次（独立计划并行运行），为每个计划生成一个全新的 200k 上下文执行器，并原子性地提交每个任务。
MSD Core 将计划分组为波次（独立计划并行运行），为每个计划生成一个全新的 200k 上下文执行器，并原子性地提交每个任务。
你将看到类似如下内容：
@@ -215,17 +215,17 @@ node todo.js done 1
node todo.js list
```
你应该看到条目出现，并且在标记完成后，条目 1 从默认列表中消失。这是 GSD Core 交付的你的第一个可见结果。
你应该看到条目出现，并且在标记完成后，条目 1 从默认列表中消失。这是 MSD Core 交付的你的第一个可见结果。
---
## 第 7 步 — 验证工作
```text
/gsd-verify-work 1
/msd-verify-work 1
```
GSD Core 提取阶段的成功标准并逐一引导你完成：
MSD Core 提取阶段的成功标准并逐一引导你完成：
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
@@ -240,7 +240,7 @@ GSD Core 提取阶段的成功标准并逐一引导你完成：
All 3 checks passed. Phase 1 verified.
```
如果任何检查失败，GSD Core 会诊断根本原因并创建修复计划。再次运行 `/gsd-execute-phase 1` 应用修复，然后重新运行 `/gsd-verify-work 1`。
如果任何检查失败，MSD Core 会诊断根本原因并创建修复计划。再次运行 `/msd-execute-phase 1` 应用修复，然后重新运行 `/msd-verify-work 1`。
**创建的内容：**
@@ -253,10 +253,10 @@ All 3 checks passed. Phase 1 verified.
## 第 8 步 — 发布
```text
/gsd-ship 1
/msd-ship 1
```
GSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含：摘要、变更内容、已解决的需求、验证情况和关键决策。
MSD Core 使用自动生成的正文创建拉取请求。PR 正文始终包含：摘要、变更内容、已解决的需求、验证情况和关键决策。
你将看到：
@@ -272,15 +272,15 @@ Title: feat(phase-1): core CLI — add / list / done commands
## 你学到了什么
- 如何使用 `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` 如何将已验证的阶段转化为拉取请求。
- 如何使用 `npx @golem15/msd-core@latest` 安装 MSD Core。
- `/msd-new-project` 如何将一段对话转化为由 `.planning/` 产物支撑的路线图。
- `/msd-discuss-phase` 如何在任何规划开始之前捕获实现决策。
- `/msd-plan-phase` 如何生成并行调研器并产出原子任务计划。
- `/msd-execute-phase` 如何以并行波次运行这些计划并提交每个任务。
- `/msd-verify-work` 如何引导完成成功标准并在需要时生成修复计划。
- `/msd-ship` 如何将已验证的阶段转化为拉取请求。
对于多阶段项目，对每个阶段重复第 4–8 步，然后运行 `/gsd-progress --next`，让 GSD Core 自动检测下一步。
对于多阶段项目，对每个阶段重复第 4–8 步，然后运行 `/msd-progress --next`，让 MSD Core 自动检测下一步。
---
@@ -288,4 +288,4 @@ Title: feat(phase-1): core CLI — add / list / done commands
- [阶段循环](../explanation/the-phase-loop.md) — 循环为何如此设计
- [操作指南](../README.md#how-to-guides) — 针对特定情况的任务型操作说明
- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 GSD Core 引入棕地仓库
- [接入现有代码库](onboarding-an-existing-codebase.md) — 将 MSD Core 引入棕地仓库