项目生命周期命令（上）

这是「GSD 全景代码解析」专题的第 7 篇。在前面的章节中，我们从架构设计、安装体系到第一条实战命令，逐步建立了对 GSD 的全局认知。从本篇开始，我们将进入命令系统与用户层章节，系统梳理 GSD 85+ 条命令中最核心的项目生命周期命令。本篇聚焦上篇——项目创建与初始化阶段的四个关键命令。

---

一、项目生命周期命令概览

在 GSD 的命令体系中，项目生命周期命令是最基础、最常用的命令组。它们负责将一个模糊的想法逐步转化为结构化的、可执行的项目规划。这四个命令构成了 GSD 工作流的入口层：

flowchart LR
    A["/gsd-plant-seed
播种种子"] -->|想法成熟| B["/gsd-new-project
创建项目"]
    C["/gsd-new-workspace
创建工作空间"] -->|容纳| B
    B -->|拆分目标| D["/gsd-new-milestone
定义里程碑"]
    D -->|驱动| E["/gsd-plan-phase
阶段规划"]

命令	作用域	核心产出	使用频率
/gsd-plant-seed	个人想法池	seeds/*.md	高（随时记录）
/gsd-new-workspace	多项目目录	workspace.json	低（一次性）
/gsd-new-project	单个项目	.planning/ 目录	高（每个项目一次）
/gsd-new-milestone	项目路线图	ROADMAP.md 更新	中（每个版本一次）

设计哲学：GSD 将项目的生命周期管理显式化。不是让你在大脑中管理"这个项目进行到哪了"，而是通过命令将每个状态变更写入文件系统，成为可追踪、可恢复的持久状态。

---

二、/gsd-new-project：创建新项目的完整流程

/gsd-new-project 是 GSD 的核心入口命令。在上一篇（第 05 篇）中，我们已经从零开始体验过它的用法。本篇将从命令设计和实现角度进行更深度的解析。

2.1 命令文件结构

在 GSD 仓库中，/gsd-new-project 对应 commands/gsd/new-project.md：

---
name: new-project
description: Initialize a new project with deep context gathering and PROJECT.md.
allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Task
---

## Context

Load context via `gsd-sdk query init.new-project`...

## Steps

1. Ask user for project idea
2. Spawn gsd-project-researcher (4 parallel)
3. Spawn gsd-research-synthesizer
4. Generate .planning/ artifacts
5. Output next steps

allowed-tools 声明了该命令在执行期间可以调用的工具集。Read/Write/Edit 用于文件操作，Bash 用于执行 shell 命令（如 git init），Task 用于 Spawn Subagent。

2.2 Dream Extraction：从模糊到精确

Dream Extraction 是 /gsd-new-project 的灵魂。它不是简单的表单填写，而是一场结构化的意图澄清会话。

flowchart TD
    A[用户输入 /gsd-new-project] --> B{是否在 Git 仓库内?}
    B -->|是| C[读取现有代码上下文]
    B -->|否| D[执行 git init]
    C --> E[启动 Dream Extraction]
    D --> E
    E --> F[Vision：项目愿景]
    F --> G[Audience：目标用户]
    G --> H[Scope：功能范围]
    H --> I[Constraints：约束条件]
    I --> J[Tech Stack：技术偏好]
    J --> K[输出结构化规划]

五个提取维度：

维度	关键问题	输出映射
Vision	"你要构建什么？解决谁的什么问题？"	PROJECT.md 的 Vision 章节
Audience	"谁会使用这个？他们的技术水平如何？"	PROJECT.md 的 Key Metrics
Scope	"MVP 必须包含什么？明确排除什么？"	REQUIREMENTS.md 的 In-Scope / Out-of-Scope
Constraints	"时间、预算、合规、性能有何限制？"	PROJECT.md 的 Constraints 章节
Tech Stack	"语言、框架、部署方式有何偏好？"	PROJECT.md 的 Tech Stack 章节

关键设计：GSD 要求用户在项目启动时就明确 Out-of-Scope（明确不做的事）。这是防止项目范围无限蔓延的第一道防线。

2.3 项目结构初始化

Dream Extraction 完成后，GSD 执行一系列原子操作来初始化项目骨架：

sequenceDiagram
    participant U as 用户
    participant C as /gsd-new-project
    participant W as new-project Workflow
    participant A1 as gsd-project-researcher x4
    participant A2 as gsd-research-synthesizer
    participant FS as 文件系统

    U->>C: 触发命令
    C->>W: 加载上下文
    W->>A1: Spawn 4 个并行研究员
    A1-->>W: 返回研究报告
    W->>A2: 合成研究结果
    A2-->>W: 返回综合报告
    W->>FS: 创建 .planning/ 目录
    W->>FS: 写入 PROJECT.md
    W->>FS: 写入 REQUIREMENTS.md
    W->>FS: 写入 ROADMAP.md
    W->>FS: 写入 config.json
    W->>FS: 更新 .gitignore
    W-->>U: 输出下一步提示

2.4 .planning/ 目录生成详解

/gsd-new-project 创建的 .planning/ 目录是项目的战略层。以下是每个生成文件的详细解析：

PROJECT.md

项目的"宪法文件"，任何新加入的 Agent 首先阅读此文件：

# Project: [项目名称]

## Vision
[用 1-2 句话描述项目愿景]

## Status
- Created: YYYY-MM-DD
- Phase: planning
- Next: /gsd-plan-phase 1

## Tech Stack
- Language: [语言]
- Framework: [框架]
- Database: [数据库]
- Deployment: [部署方式]

## Constraints
- [约束 1]
- [约束 2]

## Key Metrics
- MVP Deadline: [日期]
- Target Users: [用户群体]

REQUIREMENTS.md

需求规格说明书，将模糊意图转化为可追踪的功能列表：

# Requirements

## In-Scope (v1)

### FR-001: [功能名称]
- Priority: P0
- Description: [描述]
- Acceptance: [验收标准]

## Out-of-Scope
- [明确排除的功能，防止范围蔓延]

## Non-Functional Requirements
- [性能、安全、可维护性等要求]

ROADMAP.md

基于需求优先级和依赖关系生成的里程碑计划：

# Roadmap

## Phase 1: Foundation
- [ ] 任务 1
- [ ] 任务 2
- **Deliverable**: [可交付成果]

## Phase 2: Core Features
- [ ] 任务 3 (依赖 FR-001)
- **Deliverable**: [可交付成果]

config.json

项目级配置文件，控制 GSD 行为：

{
  "project": {
    "name": "ProjectName",
    "version": "0.1.0",
    "language": "zh-CN"
  },
  "gsd": {
    "workspace": ".planning",
    "autoCommit": true,
    "sessionFormat": "structured"
  },
  "ai": {
    "model": "claude-sonnet-4-20250514",
    "responseStyle": "concise"
  }
}

注意：config.json 中的 workspace 字段定义了 .planning/ 的目录名。虽然默认是 .planning，但你可以修改为其他名称（如 .gsd），以适配团队的既有约定。

---

三、/gsd-new-milestone：里程碑管理

如果说 /gsd-new-project 定义了"我们要去哪里"，那么 /gsd-new-milestone 定义了"我们如何分段到达"。

3.1 里程碑的定义和作用

在 GSD 中，Milestone（里程碑） 是项目演进过程中的重要检查点。它与 Phase（阶段）不同：

概念	粒度	关注点	对应命令
Phase	细粒度（1-2 周）	可执行的任务集合	/gsd-plan-phase
Milestone	粗粒度（1-2 月）	可交付的业务价值	/gsd-new-milestone

一个 Milestone 通常包含多个 Phase。例如：

Milestone 1: MVP 发布（8 周）
├── Phase 1: 基础架构（2 周）
├── Phase 2: 核心功能（3 周）
├── Phase 3: 集成测试（2 周）
└── Phase 4: 部署上线（1 周）

3.2 与 ROADMAP.md 的关系

/gsd-new-milestone 的核心操作是在 ROADMAP.md 中注册一个新的里程碑节点：

flowchart TB
    subgraph Before["执行前"]
        R1["ROADMAP.md
Phase 1
Phase 2"]
    end

    subgraph Command["/gsd-new-milestone"]
        C1["输入：里程碑名称"]
        C2["输入：目标日期"]
        C3["输入：包含的 Phase 范围"]
        C4["输入：成功标准"]
    end

    subgraph After["执行后"]
        R2["ROADMAP.md
Phase 1
Phase 2
Milestone 1: MVP
├── 包含 Phase 1-4
└── Success Criteria"]
    end

    R1 --> Command
    Command --> R2

典型的 ROADMAP.md 里程碑区块：

# Roadmap

## Milestone 1: Foundation (目标日期: 2026-05-30)
- **Phase Range**: 1.0 - 1.4
- **Success Criteria**:
  - [ ] 用户认证系统可运行
  - [ ] 数据库 Schema 稳定
  - [ ] CI/CD 流水线通过
- **Status**: 🟡 In Progress

## Milestone 2: Public Beta (目标日期: 2026-07-15)
- **Phase Range**: 2.0 - 2.5
- **Success Criteria**:
  - [ ] 核心功能 100% 覆盖
  - [ ] 通过安全审计
  - [ ] 性能基准达标
- **Status**: ⚪ Not Started

3.3 里程碑的状态流转

里程碑在整个项目生命周期中会经历明确的状态流转：

stateDiagram-v2
    [*] --> Planning: /gsd-new-milestone
    Planning --> InProgress: /gsd-plan-phase 开始首个 Phase
    InProgress --> Blocked: 遇到阻塞项
    Blocked --> InProgress: /gsd-debug 或 /gsd-recovery 解决
    InProgress --> UnderReview: 所有 Phase 完成
    UnderReview --> Completed: /gsd-complete-milestone
    UnderReview --> InProgress: UAT 不通过，返回修复
    Completed --> [*]

状态	含义	触发条件
Planning	里程碑已创建，尚未开始执行	执行 /gsd-new-milestone 后
In Progress	至少一个 Phase 正在执行中	首个 Phase 开始
Blocked	里程碑因外部依赖或技术阻塞暂停	检测到阻塞项
Under Review	所有 Phase 执行完毕，等待验收	最后一个 Phase 完成
Completed	里程碑达成，所有验收标准通过	用户确认或自动验证通过

设计意图：里程碑的状态机设计让项目进度一目了然。当你打开 ROADMAP.md，看到的不是模糊的任务列表，而是清晰的状态标识和阻塞原因。

---

四、/gsd-new-workspace：工作空间管理

4.1 多项目工作空间的概念

在真实的开发环境中，你 rarely 只处理一个项目。你可能同时维护：

• 一个前端应用
• 一个后端 API
• 一个共享组件库
• 一个文档站点

/gsd-new-workspace 解决的就是多项目协同管理的问题。它创建一个工作空间（Workspace）——一个包含多个项目的父目录，并为整个工作空间提供统一的管理视图。

graph TB
    subgraph Workspace["~/gsd-workspace/"]
        W["workspace.json
工作空间配置"]

        subgraph P1["project-a/"]
            P1_PLAN[".planning/"]
        end

        subgraph P2["project-b/"]
            P2_PLAN[".planning/"]
        end

        subgraph P3["project-c/"]
            P3_PLAN[".planning/"]
        end

        subgraph Shared["shared/"]
            S1["templates/"]
            S2["references/"]
        end
    end

    W --> P1
    W --> P2
    W --> P3
    W --> Shared

4.2 工作空间配置

执行 /gsd-new-workspace 后，会在指定目录生成 workspace.json：

{
  "workspace": {
    "name": "my-team-workspace",
    "version": "1.0.0",
    "created": "2026-04-23"
  },
  "projects": [
    {
      "name": "frontend-app",
      "path": "./frontend-app",
      "type": "web",
      "status": "active"
    },
    {
      "name": "backend-api",
      "path": "./backend-api",
      "type": "api",
      "status": "active"
    },
    {
      "name": "shared-components",
      "path": "./shared-components",
      "type": "library",
      "status": "active"
    }
  ],
  "settings": {
    "defaultProject": "frontend-app",
    "sharedTemplates": "./shared/templates",
    "crossProjectReferences": true,
    "syncMilestones": true
  }
}

关键配置项：

配置项	类型	说明
projects	array	工作空间内所有项目的清单
defaultProject	string	默认操作的目标项目
sharedTemplates	string	跨项目共享的模板目录
crossProjectReferences	boolean	是否允许跨项目引用检测
syncMilestones	boolean	是否在项目间同步里程碑视图

4.3 工作空间命令的作用域

在工作空间模式下，GSD 命令的行为会发生微妙但重要的变化：

flowchart LR
    A["用户执行命令"] --> B{是否在 Workspace 目录?}
    B -->|否| C["单项目模式
直接操作当前目录的 .planning/"]
    B -->|是| D["工作空间模式"]
    D --> E{命令类型}
    E -->|/gsd-new-project| F["询问：添加到工作空间?"]
    E -->|/gsd-progress| G["汇总所有项目进度"]
    E -->|/gsd-status| H["显示工作空间级状态面板"]

例如，在工作空间根目录执行 /gsd-progress，你会看到：

📊 Workspace: my-team-workspace

frontend-app        ████████░░░░░░░░  50%  | Phase 2.1  | 🟡 In Progress
backend-api         ██████████░░░░░░  62%  | Phase 1.3  | 🟡 In Progress
shared-components   ████████████░░░░  75%  | Phase 1.4  | 🟡 In Progress

cross-project-deps:  frontend-app → shared-components ✅

---

五、/gsd-plant-seed：种子想法管理

5.1 seeds/ 目录的作用

/gsd-plant-seed 是 GSD 中最轻量、最灵活的命令。它的作用是在 .planning/seeds/ 目录中记录一个尚未成熟到需要创建项目的想法。

flowchart TD
    A[灵感闪现] -->|/gsd-plant-seed| B["创建 seed 文件
seeds/YYYY-MM-DD-idea-title.md"]
    B --> C[定期回顾 seeds/]
    C --> D{想法是否成熟?}
    D -->|否| E[继续孵化]
    D -->|是| F["升级为项目
/gsd-new-project"]
    E --> C

种子文件的结构：

# Seed: AI-Powered Code Review Bot

## Created
2026-04-23

## Status
🌱 Seed（种子期）

## One-Liner
一个能自动分析 PR 并生成代码审查意见的 GitHub Bot。

## Inspiration
每次代码审查都花费大量时间在格式和常规检查上，
希望有一个工具能先完成 80% 的机械性审查，
让人类审查者专注于架构和逻辑。

## Potential Features
- [ ] 自动检测代码风格违规
- [ ] 识别潜在的安全漏洞模式
- [ ] 生成审查摘要和优先级排序
- [ ] 与现有 CI/CD 集成

## Open Questions
- 使用 GitHub Actions 还是独立服务？
- 支持哪些编程语言？
- 如何防止误报过多？

## Related Seeds
- seeds/2026-04-20-devops-automation.md

5.2 从想法到项目的演进路径

GSD 为想法提供了一个渐进式成熟的管道：

flowchart LR
    S1["🌱 Seed
种子期
/gsd-plant-seed"] -->|补充调研| S2["🌿 Sprout
萌芽期
手动更新"]
    S2 -->|添加可行性分析| S3["🌳 Sapling
幼苗期
创建调研文档"]
    S3 -->|确定技术方案| S4["🏗️ Project
项目期
/gsd-new-project"]

    style S1 fill:#e8f5e9
    style S2 fill:#c8e6c9
    style S3 fill:#a5d6a7
    style S4 fill:#81c784

阶段	标识	特征	操作
Seed	🌱	一句话想法，未经调研	/gsd-plant-seed
Sprout	🌿	补充了初步特征列表	手动编辑 seed 文件
Sapling	🌳	完成可行性调研，有明确技术路径	添加 research/ 文档
Project	🏗️	正式立项，进入开发	/gsd-new-project

5.3 种子管理的最佳实践

1. 定期回顾：每周执行一次 /gsd-review-seeds（或手动浏览 seeds/ 目录），避免想法被遗忘
2. 链接关联种子：在 Related Seeds 中建立想法间的关联，有时两个不成熟的种子合并后就是一个优秀的项目
3. 设置孵化期限：为每个 seed 设置 Review Date，到期后决定升级或放弃
4. 保持轻量：seed 文件不需要完美，关键是捕获灵感的那一刻上下文

---

六、四个命令的对比和使用场景

6.1 功能对比矩阵

维度	/gsd-plant-seed	/gsd-new-workspace	/gsd-new-project	/gsd-new-milestone
触发时机	灵感闪现时	开始管理多项目时	确定要开发时	项目需要大版本时
执行频率	随时	一次性	每个项目一次	每个大版本一次
核心产出	seeds/*.md	workspace.json	.planning/ 目录	ROADMAP.md 更新
AI 参与度	低（模板填充）	中（配置生成）	高（Dream Extraction）	中（目标拆解）
可逆性	高（直接删除文件）	中（可重建）	低（涉及 git 历史）	高（编辑 ROADMAP）

6.2 典型工作流组合

场景 A：独立开发者启动新项目

sequenceDiagram
    participant U as 独立开发者
    participant S as /gsd-plant-seed
    participant P as /gsd-new-project
    participant M as /gsd-new-milestone

    U->>S: 记录一个产品想法
    Note over S: seeds/2026-04-23-my-idea.md
    U->>S: 一周后补充调研
    U->>P: 确定开发，创建项目
    Note over P: .planning/ 目录生成
    U->>M: 定义 MVP 里程碑
    Note over M: ROADMAP.md 更新

场景 B：团队初始化微服务架构

sequenceDiagram
    participant TL as 技术负责人
    participant W as /gsd-new-workspace
    participant P1 as /gsd-new-project
    participant P2 as /gsd-new-project
    participant P3 as /gsd-new-project

    TL->>W: 创建团队工作空间
    Note over W: workspace.json
    TL->>P1: 创建网关服务
    TL->>P2: 创建用户服务
    TL->>P3: 创建订单服务
    Note over P1,P2,P3: 每个项目独立 .planning/

6.3 常见误区

误区	问题	正确做法
跳过 seed 直接 new-project	项目边界模糊，范围蔓延	先用 /gsd-plant-seed 孵化想法
一个 workspace 塞太多项目	状态面板过于冗长	按团队或业务线拆分 workspace
里程碑粒度太细	与 Phase 概念混淆	里程碑对应业务价值，Phase 对应技术任务
忽视 Out-of-Scope	需求无限膨胀	在 REQUIREMENTS.md 中显式声明不做的事

---

七、小结

本篇我们深入解析了 GSD 项目生命周期上半场的四个核心命令：

1. /gsd-new-project：通过 Dream Extraction 将模糊意图转化为结构化的 .planning/ 战略层，是 GSD 工作流的正式入口。
2. /gsd-new-milestone：在 ROADMAP.md 中定义粗粒度的业务检查点，提供清晰的项目进度状态机。
3. /gsd-new-workspace：为微服务或多项目场景提供统一的管理平面，让跨项目进度一目了然。
4. /gsd-plant-seed：以最低成本捕获灵感，为想法提供从 🌱 种子到 🏗️ 项目的渐进式成熟管道。

这四个命令的共同设计哲学是：将项目管理中隐性的、存在于开发者大脑中的状态，显式化为文件系统中的持久化记录。这不是简单的文档化，而是 GSD 解决 Context Rot 的基础——如果状态不在文件中，AI Agent 就无法在 Fresh Context 中恢复它。

下一篇预告： 第 08 篇《项目生命周期命令（下）》

我们将深入解析项目运行期的生命周期命令：/gsd-plan-phase、/gsd-execute-phase、/gsd-complete-milestone、/gsd-archive-project。 敬请期待。