这是「GSD 全景代码解析」专题的第 16 篇。在前面的文章中，我们从命令系统（第 06-12 篇）逐步深入到工作流的核心编排机制。命令是触发器，工作流才是剧本——而
new-project正是 GSD 所有剧本的第一幕。它承担着将一个模糊的想法转化为结构化、可执行项目的使命，是整个 GSD 生命周期中杠杆率最高的时刻。
new-project 工作流位于 get-shit-done/workflows/new-project.md，文件大小约 44KB，是 GSD 仓库中最大的单体工作流文件之一。它的目标非常明确：通过深度对话提取需求、（可选）并行研究、结构化定义、分阶段 Roadmap，将一个「我想做点什么」的念头转化为 .planning/ 目录下完整的一套项目蓝图。
正如工作流文件开篇所言：
"This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes."
本文将逐段拆解这个 44KB 的「庞然大物」，带你看懂 GSD 是如何用纯文本 Prompt 完成项目初始化的全部魔法。
一、new-project 概览：从想法到可执行蓝图
1.1 工作流定位
new-project 不是简单的「创建几个文件」，它是一个端到端的上下文工程流水线。它的输入是一个模糊的想法（或一份 PRD 文档），输出是 .planning/ 目录下的完整项目蓝图，包括：
| 输出文件 | 职责 |
|---|---|
.planning/PROJECT.md | 项目上下文、核心价值、关键决策 |
.planning/REQUIREMENTS.md | 结构化需求（v1/v2/Out of Scope） |
.planning/ROADMAP.md | 分阶段执行路线图 |
.planning/STATE.md | 项目状态与进度追踪 |
.planning/config.json | 工作流偏好配置 |
.planning/research/ | 领域研究（可选） |
CLAUDE.md / AGENTS.md | 项目级 AI 指令文件 |
对应的命令入口是 /gsd:new-project，定义在 commands/gsd/new-project.md。命令文件非常薄——它只是声明了参数（[--auto]）、可用工具和 execution_context，然后将所有工作委托给上述工作流文件。这是 GSD 「命令即触发器」 设计哲学的典型体现。
1.2 完整流程总览
整个 new-project 工作流包含 9 个主要步骤：
flowchart TB
Start([用户输入: /gsd:new-project]) --> S1[① Setup
初始化检测与配置]
S1 --> S2[② Brownfield Offer
现有代码检测]
S2 --> S3[③ Deep Questioning
Dream Extraction]
S3 --> S4[④ Write PROJECT.md
项目上下文固化]
S4 --> S5[⑤ Workflow Preferences
工作流偏好配置]
S5 --> S6[⑥ Research Decision
是否并行研究]
S6 --> S7[⑦ Define Requirements
需求结构化定义]
S7 --> S8[⑧ Create Roadmap
分阶段路线图]
S8 --> S9[⑨ Done
初始化完成与下一步引导]
S9 --> End([/gsd:discuss-phase 1])
S6 -.->|选择研究| R1[Spawn 4× researchers
Stack/Features/Architecture/Pitfalls]
R1 --> R2[Spawn synthesizer
生成 SUMMARY.md]
R2 --> S7
S8 -.->|Roadmap 阻塞| S8r[用户反馈调整]
S8r --> S8这个流程的设计遵循了 GSD 的核心原则：渐进式信息披露（Progressive Disclosure）。用户不需要一次性提供所有信息，而是通过多轮对话逐步澄清；AI 也不需要一次性生成所有产物，而是按阶段提交、按阶段确认。
二、Dream Extraction：深度对话提取
2.1 什么是 Dream Extraction？
Dream Extraction 是 GSD 对需求澄清阶段的命名。它的核心理念是：用户最初的想法往往像梦一样模糊——有情绪、有画面、但缺少结构。工作流的目标不是记录这个梦，而是通过系统性的提问，把梦里的关键元素提取、结构化、可执行化。
在 new-project 工作流中，Dream Extraction 对应 Step 3（Deep Questioning） 阶段。它有两个分支：
- 交互模式（默认）：多轮对话，逐层深入
- 自动模式（
--auto）：从提供的文档中提取上下文，跳过对话
2.2 多轮对话的设计哲学
Deep Questioning 不是一份固定的问题清单，而是一个动态跟随线程的对话引擎。工作流文件明确要求：
"Keep following threads. Each answer opens new threads to explore."
具体来说，每轮对话遵循以下策略：
| 策略 | 含义 | 示例 |
|---|---|---|
| Challenge vagueness | 挑战模糊表述 | 用户说"做一个社交平台" → 追问"用户之间如何互动？" |
| Make abstract concrete | 将抽象具体化 | 用户说"要智能" → 追问"具体解决什么场景的什么问题？" |
| Surface assumptions | 暴露隐含假设 | 追问"你为什么认为需要实时同步而非异步？" |
| Find edges | 寻找边界情况 | 追问"如果用户没有安装客户端，体验应该退化成什么样？" |
| Reveal motivation | 揭示动机 | 追问"是什么问题促使你想做这个项目？" |
2.3 五个核心维度的提取
虽然对话是动态的，但工作流背后维护着一个心理检查清单，确保五个核心维度被覆盖：
flowchart TD
subgraph DE["Dream Extraction — 五维提取"]
D1["What excited them?
兴奋点 — 核心驱动力"]
D2["What problem sparked this?
问题源 — 痛点验证"]
D3["What do they mean by vague terms?
术语澄清 — 消除歧义"]
D4["What would it actually look like?
具象描述 — 功能/界面/流程"]
D5["What's already decided?
已决事项 — 技术栈/约束/边界"]
end工作流文件引用了一份外部参考文档 questioning.md，其中包含了更详细的提问技巧。这种**「工作流引用参考文档」**的模式是 GSD 工作流设计的常见手法——将易变的技巧性内容抽离为独立文档，工作流只保留流程骨架。
2.4 决策门控：Ready? Gate
当 AI 认为自己已经足够理解用户的意图时，不会直接继续，而是主动停下来请求确认：
header: "Ready?"
question: "I think I understand what you're after. Ready to create PROJECT.md?"
options:
- "Create PROJECT.md" — Let's move forward
- "Keep exploring" — I want to share more / ask me more这是 GSD 门控（Gate）模式的典型应用。如果用户选择 "Keep exploring"，对话会继续深入，直到用户满意为止。这个循环保证了 PROJECT.md 的生成不是草率的，而是充分共识后的产物。
三、需求分析与结构化：从自然语言到 REQUIREMENTS.md
3.1 需求的三态模型
在 Deep Questioning 完成后，工作流进入 Step 7（Define Requirements）。GSD 采用一种独特的需求三态模型：
| 状态 | 含义 | 在 REQUIREMENTS.md 中的标记 |
|---|---|---|
| Validated | 已验证的需求（已交付并通过测试） | ✓ [REQ-ID] — validated in Phase N |
| Active | 当前迭代要实现的需求 | - [ ] [REQ-ID] |
| Out of Scope | 明确排除的需求（附理由） | - [Exclusion] — [why] |
对于 Greenfield 项目（全新项目），初始状态是：
## Requirements
### Validated
(None yet — ship to validate)
### Active
- [ ] [Requirement 1]
- [ ] [Requirement 2]
- [ ] [Requirement 3]
### Out of Scope
- [Exclusion 1] — [why]对于 Brownfield 项目（已有代码库），则从 codebase map 中推断已验证的能力：
## Requirements
### Validated
- ✓ [Existing capability 1] — existing
- ✓ [Existing capability 2] — existing
### Active
- [ ] [New requirement 1]
- [ ] [New requirement 2]3.2 REQ-ID 格式与可追溯性
每个需求都有唯一的 REQ-ID：
[CATEGORY]-[NUMBER]例如：AUTH-01、CONTENT-02、PAYMENT-03。这种格式不仅便于引用，还为后续的 Roadmap 映射 和 Traceability（可追溯性） 提供了基础。
3.3 需求质量检查清单
工作流对需求质量有严格的内建标准：
| 标准 | 反例 | 正例 |
|---|---|---|
| Specific and testable | "Handle password reset" | "User can reset password via email link" |
| User-centric | "System does Y" | "User can X" |
| Atomic | "User can login and manage profile" | "User can login" + "User can manage profile"（拆分为两个） |
| Independent | 强依赖其他需求 | 最小化依赖，可独立实现验证 |
如果需求不够具体，工作流会主动推回（push back）：
"Reject vague requirements. Push for specificity."
3.4 研究的输入（可选）
如果用户在 Step 6 选择了研究，则 REQUIREMENTS.md 的生成会参考 .planning/research/FEATURES.md 中的研究发现。研究将功能分为三类：
- Table stakes：行业标准功能，不做用户会流失
- Differentiators：差异化功能，竞争优势
- Anti-features：明确不做的功能（比「做什么」更重要的是「不做什么」）
在 Auto Mode 下，工作流会自动包含所有 table stakes 和文档中明确提到的功能，自动 defer 未被提及的 differentiators。
四、项目结构初始化：技术栈检测与目录生成
4.1 Setup 阶段的前置检测
在 Deep Questioning 之前，Step 1（Setup） 执行了一系列关键的初始化检测：
INIT=$(gsd-sdk query init.new-project)
AGENT_SKILLS_RESEARCHER=$(gsd-sdk query agent-skills gsd-project-researcher)
AGENT_SKILLS_SYNTHESIZER=$(gsd-sdk query agent-skills gsd-synthesizer)
AGENT_SKILLS_ROADMAPPER=$(gsd-sdk query agent-skills gsd-roadmapper)这些查询返回的 JSON 包含了大量状态信息：
| 字段 | 含义 |
|---|---|
project_exists | 项目是否已初始化（防止重复运行） |
has_codebase_map | 是否已有代码库地图 |
has_existing_code | 目录中是否已有代码 |
has_package_file | 是否检测到 package.json 等包管理文件 |
is_brownfield | 是否判定为 brownfield（现有代码）项目 |
needs_codebase_map | 是否需要先运行 codebase map |
has_git | 是否已有 git 仓库 |
agents_installed | GSD 子 Agent 是否已安装 |
4.2 Brownfield 检测与处理
如果检测到现有代码但无 codebase map，工作流会主动提出：
I detected existing code in this directory. Would you like to map the codebase first?
- "Map codebase first" — Run /gsd:map-codebase
- "Skip mapping" — Proceed with project initialization这是 GSD 「检测-建议-确认」 模式的典型体现。它不会默默假设用户想做什么，而是显式沟通、让用户选择。
4.3 Git 初始化
如果检测到没有 git 仓库，工作流会自动执行：
git init这是 new-project 中**唯一会修改项目文件系统（非 .planning/）**的操作。它保证了后续所有规划文档都可以通过 gsd-sdk query commit 被版本控制。
五、.planning/ 目录的完整生成
5.1 目录结构全景
.planning/ 是 GSD 项目的「大脑」，所有规划产物都集中于此：
.planning/
├── PROJECT.md # 项目上下文与核心决策
├── REQUIREMENTS.md # 结构化需求
├── ROADMAP.md # 分阶段路线图
├── STATE.md # 项目状态与进度
├── config.json # 工作流偏好配置
├── research/ # 领域研究（可选）
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ ├── PITFALLS.md
│ └── SUMMARY.md
└── codebase/ # 代码库地图（brownfield 时）
├── ARCHITECTURE.md
└── STACK.md5.2 PROJECT.md：项目上下文
PROJECT.md 使用模板 templates/project.md，在 Dream Extraction 完成后生成。对于 Greenfield 项目，它包含：
- What This Is：一句话描述项目
- Core Value：核心价值——如果只能实现一个功能，是什么？
- Context：目标用户、使用场景、关键约束
- Requirements：三态需求（Validated / Active / Out of Scope）
- Key Decisions：初始化阶段的关键决策与理由
- Evolution：文档的更新规则（在 Phase 过渡和 Milestone 完成时如何演进）
PROJECT.md 底部有一个强制性的时间戳：
---
*Last updated: [date] after initialization*5.3 config.json：工作流偏好
config.json 是用户的「工作流偏好配置文件」，在 Step 5 生成。它包含两类配置：
核心工作流设置：
| 字段 | 选项 | 默认推荐 |
|---|---|---|
mode | YOLO / Interactive | YOLO |
granularity | Coarse / Standard / Fine | Coarse |
parallelization | true / false | true |
commit_docs | true / false | true |
Agent 设置：
| 字段 | 含义 |
|---|---|
workflow.research | 每个 Phase 前是否研究 |
workflow.plan_check | Plan 生成后是否验证 |
workflow.verifier | Phase 执行后是否验证 |
model_profile | AI 模型偏好（Quality/Balanced/Budget/Inherit） |
config.json 支持全局默认值（~/.gsd/defaults.json），用户可以在初始化时选择「使用默认值」、「修改部分」或「全新配置」。
5.4 ROADMAP.md：分阶段路线图
ROADMAP.md 不是由 new-project 工作流直接编写的，而是委托给 gsd-roadmapper Agent 生成。这是 GSD 「工作流委托 Agent」 模式的典型案例。
Roadmapper 的输入上下文包括：
- .planning/PROJECT.md (项目上下文)
- .planning/REQUIREMENTS.md (v1 需求)
- .planning/research/SUMMARY.md (研究发现，如存在)
- .planning/config.json (粒度与模式设置)Roadmapper 的输出必须满足：
- 从需求推导阶段，不强行套用模板结构
- 每个 v1 需求映射到且仅映射到一个阶段
- 每个阶段有 2-5 个 Success Criteria（可观察的用户行为）
- 100% 覆盖率验证
Roadmap 生成后，new-project 工作流会展示一个漂亮的摘要表格：
| # | Phase | Goal | Requirements | Success Criteria |
|---|-------|------|--------------|------------------|
| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
| 2 | [Name] | [Goal] | [REQ-IDs] | [count] |5.5 STATE.md：项目状态
STATE.md 是 GSD 的状态机持久化文件。它在初始化时创建，随着项目进展不断更新：
# Project State
## Current Phase
Phase 1: [Name]
## Completed
(None yet)
## In Progress
- [ ] [Requirement 1]
## Blocked
(None)STATE.md 的设计确保了即使 AI 会话的上下文丢失，项目状态仍然可以从文件系统中恢复。
5.6 项目指令文件（AGENTS.md / CLAUDE.md）
在初始化完成前，工作流会执行：
gsd-sdk query generate-claude-md --output "$INSTRUCTION_FILE"其中 $INSTRUCTION_FILE 根据运行时决定：
| 运行时 | 指令文件名 |
|---|---|
| Codex | AGENTS.md |
| Claude / OpenCode / Gemini | CLAUDE.md |
这个文件将 GSD 的工作流规则（如必须先 plan 再 execute、每个 Phase 结束必须 verify 等）注入到项目的 AI 指令中，确保后续所有 AI 交互都遵循 GSD 规范。
六、与 gsd-planner 和 gsd-project-researcher 的协作
6.1 子 Agent 协作模型
new-project 工作流本身不直接生成所有产物，而是通过委托子 Agent 完成专业任务：
flowchart LR
subgraph NP["new-project 工作流"]
NP1["主控流程"]
end
subgraph Agents["专业 Agent 层"]
R1["gsd-project-researcher ×4"]
R2["gsd-research-synthesizer ×1"]
R3["gsd-roadmapper ×1"]
end
NP1 -->|"Step 6: 并行研究"| R1
R1 -->|"4 份研究报告"| R2
R2 -->|"SUMMARY.md"| NP1
NP1 -->|"Step 8: Roadmap"| R3
R3 -->|"ROADMAP.md + STATE.md"| NP16.2 gsd-project-researcher 的四维并行研究
当用户选择「Research first」时，new-project 会同时 spawn 4 个 researcher Agent，每个负责一个维度：
| 维度 | 输出文件 | 核心问题 |
|---|---|---|
| Stack | research/STACK.md | 2025 年该领域的标准技术栈是什么？ |
| Features | research/FEATURES.md | Table stakes vs Differentiators vs Anti-features |
| Architecture | research/ARCHITECTURE.md | 系统通常如何结构化？组件边界与数据流？ |
| Pitfalls | research/PITFALLS.md | 这个领域常见的错误是什么？如何预防？ |
每个 researcher 都有统一的输出模板（位于 templates/research-project/），确保输出格式一致、下游消费者（synthesizer 和 roadmapper）可以可靠解析。
6.3 gsd-research-synthesizer 的整合
4 个 researcher 完成后，会 spawn 一个 synthesizer Agent，将四份报告整合为 research/SUMMARY.md。这个设计遵循了 GSD 的 Map-Reduce 模式：先并行处理（Map），再串行整合（Reduce）。
6.4 gsd-roadmapper 的规划
Roadmapper 是整个初始化流程中最关键的 Agent。它的任务不是简单地列出阶段，而是：
- 从需求推导结构：需求之间的依赖关系决定了阶段的先后顺序
- 平衡粒度：根据
config.json中的granularity设置决定阶段的粗细 - 定义成功标准：每个阶段必须有可观测的 Success Criteria
Roadmapper 的输出可能有两种状态：
## ROADMAP CREATED：成功，进入审批流程## ROADMAP BLOCKED：阻塞，需要用户介入解决
这种显式状态返回是 GSD Agent 通信协议的重要约定。
七、初始化失败的处理与恢复
7.1 前置验证失败
new-project 工作流在 Setup 阶段有多层前置验证：
| 验证项 | 失败行为 |
|---|---|
project_exists == true | 报错：「Project already initialized. Use /gsd:progress.」 |
agents_installed == false | 警告：子 Agent spawn 会失败，跳过研究阶段，直接生成 Roadmap |
| Auto mode 无文档 | 报错：「Error: --auto requires an idea document.」 |
7.2 Roadmap 阻塞处理
如果 Roadmapper 返回 ROADMAP BLOCKED，new-project 不会强行继续，而是：
- 向用户展示阻塞信息
- 与用户协作解决阻塞
- 解决后重新 spawn Roadmapper
7.3 原子提交与断点恢复
整个 new-project 流程遵循 「原子提交」 原则：
"Each phase commits its artifacts immediately. If context is lost, artifacts persist."
每完成一个阶段，产物都会通过 gsd-sdk query commit 提交到 git。这意味着：
- 如果 AI 会话意外中断，已生成的
PROJECT.md、config.json等不会丢失 - 用户可以重新运行
/gsd:new-project，工作流会检测到project_exists并给出正确提示 - 每个文件都是独立的恢复点
7.4 自动模式的失败降级
Auto mode 虽然跳过了交互，但并非无条件的「全自动驾驶」。它在关键决策点仍然遵循门控逻辑：
- 如果提供的文档信息不足，仍然会生成**假设（hypotheses）**而非断言
- 如果研究阶段网络失败，会静默跳过研究，基于已有信息继续
- 所有「自动批准」的决策都会记录在
config.json中，可追溯
八、小结
new-project 工作流是 GSD 框架的门面工程。它用 44KB 的纯文本 Prompt，实现了一套媲美专业项目管理工具的初始化流程：
| 特性 | 实现方式 |
|---|---|
| 深度需求提取 | Dream Extraction + 五维检查清单 + 动态线程跟随 |
| 结构化需求管理 | 三态模型（Validated/Active/Out of Scope）+ REQ-ID |
| 并行领域研究 | 4× researcher + 1× synthesizer 的 Map-Reduce |
| 智能分阶段规划 | gsd-roadmapper 从需求推导结构 |
| 状态持久化 | .planning/ 目录 + 原子提交 + STATE.md |
| 失败恢复 | 前置验证 + Roadmap 阻塞处理 + 断点恢复 |
它的设计哲学可以用一句话概括：在项目的起点投入足够多的思考，后续的每一步都会更轻松。
正如工作流文件反复强调的：
"One workflow takes you from idea to ready-for-planning."
当你下一次输入 /gsd:new-project 时，你会知道背后那 44KB 的 Prompt 正在执行怎样精密的上下文工程——从检测你的代码库状态，到追问你模糊想法背后的真实动机，再到协调多个专业 Agent 并行研究，最终为你生成一套完整的项目蓝图。
📌 下一篇预告：第 17 篇《discuss-phase 与交互工作流》将深入解析 GSD 中最具特色的交互式工作流——
/gsd:discuss-phase。我们将看到 GSD 如何在每个 Phase 开始前通过深度对话澄清实现细节、处理不确定性、协调人类判断与 AI 执行之间的张力。如果说new-project是「运筹帷幄」的起点，那么discuss-phase就是「决胜千里」前的最后一次校准——它是 GSD 工作流中人与 AI 协作最密集、最精妙的环节，敬请期待！