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

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* 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>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

148
docs/zh-CN/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# CONTEXT.md 结构参考
每个阶段的 `CONTEXT.md` 是 GSD Core 用于保存 `/gsd:discuss-phase` 阶段所收集的实现决策的载体。它是研究代理和规划代理的主要上游输入。本页面记录其结构。参见[文档索引](../README.md)。
---
## 概述
每个经过讨论工作流处理的阶段，均会在以下路径生成一份 `CONTEXT.md`：
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
示例：`.planning/phases/03-post-feed/03-CONTEXT.md`。
该文件由 `get-shit-done/workflows/discuss-phase.md` 中的 `write_context` 步骤生成（或通过 PRD/ADR 摄入快速路径生成）。在正常操作中，该文件不会被手动编辑——讨论阶段工作流负责写入，下游代理将其作为封闭的可信来源读取。
---
## 前言（Frontmatter）
`CONTEXT.md` 不包含 YAML 前言。元数据以内联形式写在正文顶部：
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
`Status` 字段在文件首次写入时始终为 `Ready for planning`，创建后不再更新。
---
## 块结构
正文由若干具名 XML 风格的块组成，以固定顺序出现。下游代理通过块名而非行号来读取各块内容。
| 块名 | 用途 | 由谁填充 | 由谁消费 |
|---|---|---|---|
| `<domain>` | 声明阶段边界——本阶段交付内容及明确排除在范围之外的内容。在规划和执行过程中为范围护栏提供锚点。 | `discuss-phase`（来自 ROADMAP.md 阶段目标） | `gsd-planner`、`gsd-plan-checker`（范围合规性） |
| `<spec_lock>` | 仅在 `check_spec` 步骤发现 `*-SPEC.md` 时才存在。列出锁定的需求数量和范围边界；代理被指示直接读取 `SPEC.md` 以获取完整需求。 | `discuss-phase`（条件性） | `gsd-planner`（直接读取 SPEC.md，而非在此重读需求） |
| `<decisions>` | 从讨论中收集的实现决策，使用 `D-NN` 标识符标注。分类由实际讨论内容产生，而非固定分类体系。包含 `Claude's Discretion` 子节，用于用户委托代理自行决定的领域。 | `discuss-phase`（交互式讨论） | `gsd-planner`（锁定的决策必须实现）、`gsd-plan-checker`（维度 7 合规性） |
| `<canonical_refs>` | 与本阶段相关的所有规格文档、ADR、功能文档或设计文档的完整相对路径。必填——每份 CONTEXT.md 必须包含此节。代理在规划或实现之前必须读取列出的文件。 | `discuss-phase`（从 ROADMAP.md 引用 + 讨论中的用户引用 + 代码库侦查积累） | `gsd-phase-researcher`、`gsd-planner` |
| `<code_context>` | 在 `scout_codebase` 步骤中发现的可复用资产、已建立的模式和集成点。引导代理使用现有代码，而非重新实现。 | `discuss-phase`（代码库侦查） | `gsd-planner`、`gsd-phase-researcher` |
| `<specifics>` | 讨论期间逐字记录的具体"我希望它像 X 一样"的参考、产品对比或特定示例。 | `discuss-phase`（自由形式用户输入） | `gsd-planner` |
| `<deferred>` | 讨论中出现但属于其他阶段的想法，予以保留以免遗失。当待办事项经过审查但未纳入范围时，包含 `Reviewed Todos` 子节。 | `discuss-phase`（范围蔓延重定向） | 不被自动化代理消费；仅供人工参考 |
---
## 决策标识符格式
`<decisions>` 中的每条决策均带有顺序编号的 `D-NN` 标识符：
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
标识符的作用域限定在阶段内。第 3 阶段中的 `D-01` 与第 7 阶段中的 `D-01` 无关。计划检查器（维度 7）会验证每个 `D-NN` 是否在生成计划中至少有一个任务动作加以覆盖。
---
## 规范引用
`<canonical_refs>` 块为**必填项**。如果代理发现其缺失，会将该 CONTEXT.md 视为不完整并发出警告。条目按主题分组，包含完整相对路径以及对文件所决定或定义内容的简要说明：
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
当项目没有外部规格文档时，该节应明确说明：
```
No external specs — requirements fully captured in decisions above
```
在 `<decisions>` 中散落的内联提及（如"参见 ADR-019"）是不够的；代理需要在专用节中获取完整路径。
---
## 决策覆盖关卡关系
计划检查器的**维度 7：上下文合规性**在规划完成后执行覆盖关卡检查：
1. `<decisions>` 中的每个 `D-NN` 标识符必须出现在至少一个计划任务的 `<action>` 或说明中。
2. 任何任务均不得实现 `<deferred>` 中列出的内容（即范围蔓延）。
3. `Claude's Discretion` 领域免于此检查——规划者可自由选择。
决策被成功纳入计划的 CONTEXT.md 被视为合规。决策被悄然丢弃或部分交付的 CONTEXT.md 会触发**维度 7b：范围缩减检测**，这始终是一个**阻断项**。
---
## SPEC.md 集成
当 `/gsd:spec-phase` 在讨论阶段之前运行时，`check_spec` 步骤会找到 `*-SPEC.md` 文件并激活 `<spec_lock>`：
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
当 `<spec_lock>` 存在时，`<decisions>` 中仅包含来自讨论的实现决策——即"如何做"，而非"做什么"。需求不会在两个文件之间重复。
---
## 页脚
每份 CONTEXT.md 以身份页脚结尾：
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## 相关内容
- [PLAN.md 结构](plan-md.md)
- [规划产物](planning-artifacts.md)
- [讨论模式](../workflow-discuss-mode.md)
- [文档索引](../README.md)

249
docs/zh-CN/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# PLAN.md 模式参考
每个计划的 `PLAN.md` 是 GSD Core 的可执行工作单元——一份结构化文档，精确告知执行器代理需要构建什么以及如何验证构建是否正确完成。本页记录其结构。参见[文档索引](../README.md)。
---
## 概述
计划存放在以下位置的阶段目录中：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
例如：`.planning/phases/03-post-feed/03-02-PLAN.md`（第 3 阶段，第 2 计划）。
计划由 `gsd-planner` 代理生成（由 `/gsd:plan-phase` 触发），并由 `execute-phase` 消费。一个阶段通常包含一到四个计划；同一阶段内的计划被分配到执行波次，以便独立工作并行运行。
---
## YAML 前置元数据
每个 PLAN.md 以位于 `---` 分隔符之间的 YAML 前置元数据块开头。
### 注释示例
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### 前置元数据字段参考
| 字段 | 是否必填 | 类型 | 用途 |
|---|---|---|---|
| `phase` | 是 | string | 阶段标识符，例如 `03-post-feed`。 |
| `plan` | 是 | string | 阶段内的计划编号，例如 `02`。 |
| `type` | 是 | `execute` 或 `tdd` | 标准计划使用 `execute`；测试驱动计划使用 `tdd`，测试在实现之前编写。 |
| `wave` | 是 | integer | 执行波次。波次 1 中的计划并行运行（无依赖关系）。波次 2 及以上的计划等待上一波次的所有计划完成后才开始。由 `gsd-planner` 在规划时预先计算。 |
| `depends_on` | 是 | array of plan IDs | 该计划必须等待的前置计划。空数组表示波次 1。示例：`["03-01"]` 表示该计划在第 3 阶段计划 01 完成后运行。 |
| `files_modified` | 是 | array of paths | 该计划创建或修改的所有文件。被计划检查器用于检测同波次文件冲突，也被 execute-phase 用于合并跟踪。 |
| `autonomous` | 是 | boolean | 当所有任务类型均为 `auto` 时为 `true`。当计划包含任何需要人工交互的 `checkpoint:*` 任务时为 `false`。 |
| `requirements` | 是 | array of IDs | 该计划所对应的 ROADMAP.md 中的需求 ID。每个阶段需求 ID 必须出现在至少一个计划的 `requirements` 字段中。空数组是阻断项（BLOCKER）。 |
| `user_setup` | 否 | array of objects | Claude 无法自动化的外部服务设置步骤（账户创建、密钥获取、控制台配置）。存在时，execute-phase 会为开发者生成 `USER-SETUP.md` 检查清单。 |
| `must_haves` | 是 | object | 以目标为导向的验证标准。详见下文。 |
---
## `must_haves` 字段
`must_haves` 描述了阶段目标达成后必须可观测到的真实状态。该字段在规划阶段派生，并在执行后由 `gsd-verifier` 代理验证。
### 子字段
| 子字段 | 类型 | 用途 |
|---|---|---|
| `truths` | array of strings | 从用户视角可观测到的行为。每项必须可验证。示例：`"User can send a message"`，而非 `"WebSocket library installed"`。 |
| `artifacts` | array of objects | 必须存在且具有实质性实现（非桩代码）的文件。 |
| `artifacts[].path` | string | 相对于项目根目录的文件路径。 |
| `artifacts[].provides` | string | 该文件所提供的能力。 |
| `artifacts[].min_lines` | integer（可选） | 被视为非桩代码的最小行数。 |
| `artifacts[].exports` | array of strings（可选） | 需要验证的预期命名导出项。 |
| `artifacts[].contains` | string（可选） | 必须出现在文件中的正则表达式或字面量模式。 |
| `key_links` | array of objects | 制品之间的关键连接——使系统端到端运行的接线。 |
| `key_links[].from` | string | 源文件或组件。 |
| `key_links[].to` | string | 目标文件、端点或模块。 |
| `key_links[].via` | string | 连接方式描述（例如 `fetch in useEffect`、`Prisma query`、`import`）。 |
| `key_links[].pattern` | string（可选） | 用于验证源代码中连接是否存在的正则表达式。 |
---
## 正文结构
前置元数据之后，计划正文使用执行器代理读取的具名 XML 风格块。
### `<objective>`
说明计划所交付的内容及其对项目的重要性：
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
列出执行器在开始前读取的工作流文件。始终包含 execute-plan 工作流；当计划包含检查点任务时，额外添加检查点参考：
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
引用执行器需要读取的源文件。包括项目级规划文档以及计划必须复用其模式或类型的源文件。仅当后续计划对其类型或决策存在真实依赖时，才引用前序计划的 `SUMMARY.md` 文件——而非无条件引用：
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
包含一个或多个 `<task>` 元素。对于 `type="auto"` 的任务，每个任务元素必须包含 `<name>`、`<files>`、`<read_first>`、`<action>`、`<verify>`、`<acceptance_criteria>` 和 `<done>`。
---
## 任务类型
| 类型 | 使用场景 | 自主程度 |
|---|---|---|
| `auto` | 执行器可独立完成的所有内容。 | 完全自主。 |
| `checkpoint:human-verify` | 需要人工查看运行中的界面或服务进行视觉或功能验证。 | 暂停执行；呈现给开发者；批准后恢复。 |
| `checkpoint:decision` | 执行过程中出现的需要开发者输入的实现选择。 | 暂停执行；呈现选项；选择后恢复。 |
| `checkpoint:human-action` | 真正不可避免的手动步骤（账户创建、硬件交互）。谨慎使用。 | 暂停执行；确认后恢复。 |
包含任何检查点任务的计划必须在前置元数据中设置 `autonomous: false`。
---
## `auto` 任务结构
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### `auto` 任务必填字段
| 字段 | 规则 |
|---|---|
| `<files>` | 任务创建或修改的所有文件。执行器只写入这些文件。 |
| `<read_first>` | 执行器在修改任何内容之前必须读取的文件——包括待修改文件、任何真实来源的模式文件以及必须复用其类型或约定的文件。 |
| `<action>` | 包含精确标识符、文件路径、函数签名和预期值的具体指令。不能在未指定目标状态的情况下说"将 X 与 Y 对齐"。不包含代码围栏块或完整实现。 |
| `<verify>` | 可运行的命令或检查，用于证明任务已成功完成。必须能区分通过与失败——`echo "done"` 无效。 |
| `<acceptance_criteria>` | 可验证的条件：可通过 grep 验证的字符串、命令退出码、可观测行为。不含主观性语言（"看起来正确"、"配置正确"）。 |
| `<done>` | 已完成结果的简短可量化陈述。 |
---
## 计划质量维度
`gsd-plan-checker` 代理在执行开始前对每个 PLAN.md 进行 12 个维度的审查。任何未通过 BLOCKER 级别检查的计划将被退回给 `gsd-planner` 修订（最多 3 次迭代）：
| 维度 | 检查内容 |
|---|---|
| **1 — 需求覆盖率** | ROADMAP.md 中每个阶段需求 ID 出现在至少一个计划的 `requirements` 前置元数据字段中，并有相应的覆盖任务。 |
| **2 — 任务完整性** | 每个 `auto` 任务携带所有必填字段（`<files>`、`<action>`、`<verify>`、`<acceptance_criteria>`、`<done>`）。无模糊或空字段。 |
| **3 — 依赖正确性** | `depends_on` 引用有效、无循环，并与波次编号一致。第 N 波次计划仅依赖波次 < N 的计划。 |
| **4 — 关键链接规划** | `must_haves.key_links` 中的制品有对应的实现接线任务——而非仅创建制品。 |
| **5 — 范围合理性** | 计划保持在上下文预算内：每个计划 2–3 个任务（4 个 = 警告，5 个及以上 = BLOCKER），每个计划 ≤ 8–10 个文件（15 个及以上 = BLOCKER）。 |
| **6 — 验证推导** | `must_haves.truths` 是用户可观测行为，而非实现细节。制品映射到真实状态。关键链接覆盖关键接线。 |
| **7 — 上下文合规性** | CONTEXT.md 中每个 `D-NN` 决策至少由一个任务处理。没有任务实现 `<deferred>` 中的内容。 |
| **7b — 范围缩减检测** | 任务操作不会在未交付完整决策范围的情况下，悄悄将已锁定决策降级为"v1"、"桩代码"或"未来增强"。发现时始终为 BLOCKER。 |
| **7c — 架构层级合规性** | 任务按照 RESEARCH.md 架构责任映射（如存在）将能力分配到正确层级。安全敏感能力分配到错误层级时为 BLOCKER。 |
| **8 — 奈奎斯特合规性** | 当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 存在时，每个任务有 `<automated>` 验证命令，连续 3 个任务的窗口内不缺少覆盖，且 VALIDATION.md 存在。 |
| **9 — 跨计划数据契约** | 当计划共享数据管道时，其转换相互兼容——没有计划删除另一个计划需要原始形式的数据。 |
| **10 — CLAUDE.md 合规性** | 计划遵守 `./CLAUDE.md` 中的项目特定约定、禁止模式、必需工具和安全要求。 |
| **11 — 研究解决** | 当 RESEARCH.md 存在时，其 `## Open Questions` 部分在规划继续之前标记为 `(RESOLVED)`。 |
| **12 — 模式合规性** | 当 PATTERNS.md 存在时，任务为每个新建或修改的文件引用正确的类比模式。 |
---
## 波次执行模型
波次编号在规划阶段预先计算。Execute-phase 按波次编号对计划进行分组，并行运行每个波次的计划：
```
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
Wave 2: Plan 04 (waits for Wave 1 to complete)
Wave 3: Plan 05 (waits for Wave 2 to complete)
```
同一波次中修改重叠文件的计划不得处于同一波次——计划检查器的维度 3 会将此标记为 BLOCKER。
---
## 计划输出
计划成功执行后，执行器在以下路径写入 SUMMARY.md：
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
SUMMARY.md 是所构建内容的权威记录。同一阶段内的后续计划，仅当对其类型或决策存在真实依赖时，才可引用该文件。
---
## 相关内容
- [CONTEXT.md 模式](context-md.md)
- [规划制品](planning-artifacts.md)
- [功能特性](../FEATURES.md)
- [文档索引](../README.md)

225
docs/zh-CN/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# 规划产物参考
`.planning/` 目录是 GSD Core 项目的共享记忆。所有工作流都会读取和写入该目录，并留下可审计的决策记录。本页列出每个文件、其用途，以及哪些命令负责生成或消费它。参见[文档索引](../README.md)。
---
## 目录结构
```
.planning/
├── PROJECT.md # 项目标识与核心价值
├── ROADMAP.md # 里程碑 + 阶段列表及目标
├── REQUIREMENTS.md # 编号化验收标准
├── STATE.md # 实时进度跟踪器
├── config.json # 工作流与模型配置
├── MILESTONES.md # 里程碑归档（可选）
├── BACKLOG.md # 延期与未来工作（可选）
├── LEARNINGS.md # 跨阶段积累的经验（可选）
├── DECISIONS-INDEX.md # 历史决策滚动摘要（可选）
├── METHODOLOGY.md # 可复用的解释框架（可选）
├── HANDOFF.json # 机器可读的暂停状态（临时文件）
├── codebase/ # 代码库映射（可选）
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # 可查询的符号索引（可选，intel.enabled）
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # 每个阶段一个目录
├── <NN>-CONTEXT.md # 实现决策（discuss-phase）
├── <NN>-DISCUSSION-LOG.md # 人类可读的讨论审计（discuss-phase）
├── <NN>-RESEARCH.md # 技术研究结果（plan-phase）
├── <NN>-VALIDATION.md # Nyquist 测试覆盖策略（plan-phase）
├── <NN>-PATTERNS.md # 代码库类比映射（plan-phase，可选）
├── <NN>-<PP>-PLAN.md # 可执行计划（plan-phase，每个计划一个）
├── <NN>-<PP>-SUMMARY.md # 执行记录（execute-phase，每个计划一个）
├── <NN>-VERIFICATION.md # 阶段目标验证报告（verify-phase）
├── <NN>-UAT.md # 持久化 UAT 会话状态（execute-phase）
└── .continue-here.md # 暂停后的恢复说明（pause-work）
```
---
## 根级产物
### `PROJECT.md`
| | |
|---|---|
| **用途** | 规范的项目标识：项目内容、目标用户、核心价值、需求、约束和关键决策。随项目演进持续更新。 |
| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-complete-milestone` 在决策验证后更新。 |
| **消费者** | 所有规划工作流；`gsd-phase-researcher`、`gsd-planner`（上下文）；`discuss-phase`（历史决策）；`gsd-plan-checker`（项目约束）。 |
### `ROADMAP.md`
| | |
|---|---|
| **用途** | 里程碑与阶段列表，含目标、需求 ID、成功标准以及每个阶段的规范参考。是项目构建内容和顺序的唯一可信来源。 |
| **生成者** | `/gsd-new-project`（初始创建）；由 `/gsd-phase --insert` 和 `/gsd-complete-milestone` 更新。 |
| **消费者** | `/gsd-discuss-phase`、`/gsd-plan-phase`、`/gsd-execute-phase`；所有需要阶段信息的编排命令；`gsd-planner`、`gsd-plan-checker`、`gsd-phase-researcher`。 |
### `REQUIREMENTS.md`
| | |
|---|---|
| **用途** | 编号化、可勾选的项目验收标准。每条需求带有 ID（如 `AUTH-01`），映射到路线图阶段。随着阶段执行，逐步标记需求为已完成。 |
| **生成者** | `/gsd-new-project`（初始创建）；需求由 `execute-phase` 标记为已完成。 |
| **消费者** | `gsd-planner`（计划必须覆盖所有阶段需求 ID）；`gsd-plan-checker` 维度 1（需求覆盖）；`discuss-phase`（历史需求）。 |
### `STATE.md`
| | |
|---|---|
| **用途** | 实时进度跟踪器——当前阶段与计划、进度指标、积累的决策、会话连续性说明。每次工作流运行时首先读取，每次重要操作后更新。 |
| **生成者** | `/gsd-new-project`（初始创建）；由所有阶段工作流、`/gsd-pause-work`、`/gsd-resume-work` 持续更新。 |
| **消费者** | 所有编排工作流；`/gsd-progress`；通过 `/gsd-quick` 执行的临时任务；`gsd-planner` 和 `gsd-phase-researcher`（项目决策）。 |
完整字段参考请参见 [STATE.md 模式](state-md.md)。
### `config.json`
| | |
|---|---|
| **用途** | 工作流配置：模型配置文件、研究与计划检查器开关、Git 分支策略、Nyquist 验证、并行化设置，以及每个代理的模型覆盖。 |
| **生成者** | `/gsd-new-project`（初始创建）；`/gsd-settings`（交互式编辑）。 |
| **消费者** | 每个工作流和子代理——在初始化时通过 `gsd-tools query config-get` 读取。 |
完整模式请参见 [CONFIGURATION](../CONFIGURATION.md)。
### `MILESTONES.md`（可选）
| | |
|---|---|
| **用途** | 已完成里程碑的历史记录。每个里程碑关闭时填充；提供已交付内容及时间的存档快照。 |
| **生成者** | `/gsd-complete-milestone`。 |
| **消费者** | `/gsd-audit-milestone`；人工审查。 |
### `DECISIONS-INDEX.md`（可选）
| | |
|---|---|
| **用途** | 先前阶段 CONTEXT.md 文件中捕获的决策的有界滚动摘要。存在时，`discuss-phase` 读取此单一文件，而不是逐一读取最多三个先前的 CONTEXT.md 文件，从而节省上下文预算。 |
| **生成者** | 当先前阶段数量超过滚动读取阈值时生成。 |
| **消费者** | `discuss-phase`（`load_prior_context` 步骤）。 |
### `HANDOFF.json`（临时文件）
| | |
|---|---|
| **用途** | 工作中断时写入的机器可读暂停状态。包含恢复点、进行中的上下文以及继续说明。恰好消费一次——在恢复时。 |
| **生成者** | `/gsd-pause-work`。 |
| **消费者** | `/gsd-resume-work`。 |
---
## 每阶段产物
所有每阶段文件均位于 `.planning/phases/<NN>-<slug>/` 下，其中 `NN` 是补零的阶段编号，`slug` 是用连字符连接的阶段名称。
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **用途** | 规划开始前捕获的实现决策。包含阶段边界（`<domain>`）、带有 `D-NN` 标识符的锁定决策（`<decisions>`）、规范文档参考（`<canonical_refs>`）、现有代码洞察（`<code_context>`）、具体灵感（`<specifics>`）以及推迟的想法（`<deferred>`）。 |
| **生成者** | `/gsd-discuss-phase`（交互式讨论或 PRD/ADR 快速路径）。 |
| **消费者** | `gsd-phase-researcher`（待调查内容）；`gsd-planner`（锁定决策）；`gsd-plan-checker` 维度 7（上下文合规性）。 |
完整字段参考请参见 [CONTEXT.md 模式](context-md.md)。
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **用途** | discuss-phase 会话的人类可读审计记录：讨论的领域、提出的选项、所做的选择、推迟的想法以及留给 Claude 自行决定的事项。不被自动化工作流消费。 |
| **生成者** | `/gsd-discuss-phase`（`git_commit` 步骤）。 |
| **消费者** | 人工审查；回顾总结。 |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **用途** | 规划前产生的技术研究结果。回答"为了很好地规划此阶段，我需要了解什么？"——涵盖领域分析、模式、风险、架构职责映射以及验证架构部分（由 Nyquist 门控使用）。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-phase-researcher` 代理。 |
| **消费者** | `gsd-planner`（规划输入）；`gsd-plan-checker` 维度 7c（层级合规性）、维度 8（Nyquist）、维度 11（研究解决）；`gsd-pattern-mapper`（文件列表来源）。 |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **用途** | 源自 RESEARCH.md 中 `## Validation Architecture` 部分的 Nyquist 启发式验证策略。指定计划必须遵守的自动化测试覆盖要求。 |
| **生成者** | `/gsd-plan-phase`（步骤 5.5，当 `workflow.nyquist_validation` 已启用且 RESEARCH.md 包含验证架构部分时）。 |
| **消费者** | `gsd-plan-checker` 维度 8（检查 8e 门控——Nyquist 检查进行前必须存在）；`gsd-verifier`。 |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **用途** | 由 `gsd-pattern-mapper` 生成的代码库类比映射。针对本阶段每个待创建或修改的文件，识别最近似的现有类比，对文件的角色和数据流进行分类，并提取具体代码摘录。引导规划者采用一致的模式。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-pattern-mapper` 代理（可选；如果 `workflow.pattern_mapper: false` 则跳过）。 |
| **消费者** | `gsd-planner`（模式指导）；`gsd-plan-checker` 维度 12（模式合规性）。 |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **用途** | 阶段内单个工作单元的可执行计划。包含 YAML 前置内容（wave、dependencies、files、requirements、`must_haves`）、目标、上下文参考、带有 `<read_first>`、`<action>`、`<verify>` 和 `<acceptance_criteria>` 字段的 XML 结构化任务，以及验证标准。 |
| **生成者** | `/gsd-plan-phase` 通过 `gsd-planner` 代理。每个计划一个文件——例如，`03-02-PLAN.md` 是第 3 阶段第 2 个计划。 |
| **消费者** | `/gsd-execute-phase`（执行器代理读取计划并运行任务）；`gsd-plan-checker`（执行前质量审查）；`gsd-verifier`（读取 `must_haves` 进行执行后验证）。 |
完整字段参考请参见 [PLAN.md 模式](plan-md.md)。
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **用途** | 计划完成后写入的执行记录。记录已构建内容、与计划的偏差、对验收标准的自查，以及阶段的依赖关系图。 |
| **生成者** | `execute-phase` 执行器代理（在每个计划执行结束时写入）。 |
| **消费者** | `/gsd-progress`（阶段状态）；`gsd-planner`（当后续计划对先前计划输出存在真实依赖时）；`milestone-summary`。 |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **用途** | 阶段目标验证报告。在执行完成后，对照实际代码库检查所有计划中的 `must_haves.truths`、`must_haves.artifacts` 和 `must_haves.key_links`。记录 `status: passed | gaps_found | human_needed`。 |
| **生成者** | `/gsd-verify-work`（或 `/gsd-execute-phase` 内的验证步骤）。 |
| **消费者** | `plan-phase` 已关闭阶段门控（`status: passed` 的 VERIFICATION.md 将阶段标记为 `Complete`，并在没有 `--force` 的情况下阻止重新规划）；`/gsd-progress`；人工审查。 |
### `<NN>-UAT.md`
| | |
|---|---|
| **用途** | 持久化的 UAT 会话跟踪。在实时 UAT 会话中记录每个测试用例、预期的可观察行为、结果以及开发者响应。带有 YAML 前置内容（`status`、`phase`、`source`、时间戳）。 |
| **生成者** | `/gsd-audit-uat`（交互式 UAT 会话）。 |
| **消费者** | `/gsd-audit-uat`（恢复先前的 UAT 会话）。 |
### `.continue-here.md`
| | |
|---|---|
| **用途** | 阶段工作暂停时写入的人类可读恢复说明。包含供恢复代理使用的上下文：关键反模式、阻塞问题、必读内容以及恢复的确切命令。 |
| **生成者** | `/gsd-pause-work`。 |
| **消费者** | 任何在阶段上启动的工作流——`discuss-phase` 和 `plan-phase` 在入口处均检查此文件，并要求代理在继续之前证明其理解了所有 `blocking` 反模式。 |
---
## 命名约定
| 片段 | 格式 | 示例 |
|---|---|---|
| 阶段目录 | `<NN>-<slug>` | `03-post-feed` |
| 阶段级文件 | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| 计划级文件 | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | 补零的阶段编号 | `03` 表示第 3 阶段 |
| `PP` | 阶段内补零的计划编号 | `02` 表示第 2 个计划 |
当 `config.json` 中设置了 `project_code` 时，阶段目录使用项目代码作为前缀：对于项目代码 `CK`、第 3 阶段，目录为 `CK-03-post-feed`。
---
## 相关内容
- [STATE.md 模式](state-md.md)
- [CONTEXT.md 模式](context-md.md)
- [PLAN.md 模式](plan-md.md)
- [文档索引](../README.md)

201
docs/zh-CN/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# STATE.md 架构参考
`STATE.md` 是 GSD Core 的动态项目记忆文件——一个记录项目当前状态、最近发生的事情以及下一步操作的单一 Markdown 文档。本页面记录其结构。参见[文档索引](../README.md)。
---
## 概述
由 GSD Core 管理的每个项目在 `.planning/STATE.md` 处保存一个 `STATE.md`。该文件在每次工作流开始时被读取，并在每次重要操作后被写入。该文件包含：
- **YAML 前置数据** — 机器可读字段，由状态行钩子（`parseStateMd`）和 `gsd-tools state` 命令使用。
- **Markdown 正文** — 人类可读的章节，涵盖当前位置、累积的上下文、会话连续性以及性能指标。
该文件有意保持较小（目标：不超过 100 行）。它是项目状态的摘要，而非存档。
---
## YAML 前置数据
前置数据出现在文件最开头的 `---` 分隔符之间。除 `gsd_state_version` 和 `status` 外，所有字段均为可选；当相关数据尚不可用时，字段可以缺失。
### 注释示例
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# Phase-lifecycle fields — all optional (added in v1.40.0, issue #2833)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# Additional fields written by syncStateFrontmatter
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### 字段参考
| 字段 | 类型 | 填充时机 | 用途 |
|---|---|---|---|
| `gsd_state_version` | 字符串（`'1.0'`） | 始终 | 架构版本；在第一次 `state.*` 调用时由 `syncStateFrontmatter` 写入。 |
| `milestone` | 字符串（如 `v2.0`） | 配置了里程碑时 | 当前里程碑版本，从项目配置中读取。 |
| `milestone_name` | 字符串 | 配置了里程碑时 | 里程碑的人类可读标签（如 `Code Quality`）。 |
| `status` | 字符串 | 始终 | 当前生命周期阶段。由 `normalizeStateStatus()` 规范化——参见[状态值](#状态值)。 |
| `active_phase` | 字符串（如 `"4.5"`） | 编排器命令正在处理该阶段时 | 当前正在处理的阶段编号。阶段之间时设为 `null`。 |
| `next_action` | 字符串 | 空闲且有推荐命令时 | 下一步要运行的斜线命令：`discuss-phase`、`plan-phase`、`execute-phase` 或 `verify-phase`。当编排器正在运行或无可用推荐时设为 `null`。 |
| `next_phases` | YAML 流数组（如 `["4.5"]`） | 与 `next_action` 配合使用 | `next_action` 适用的阶段 ID（通常 1–2 项）。与 `next_action` 相同条件下设为 `null`。 |
| `progress.total_phases` | 整数 | 阶段数据可用时 | 当前里程碑中的阶段总数，从 ROADMAP.md 和阶段目录派生。 |
| `progress.completed_phases` | 整数 | 阶段数据可用时 | 磁盘上所有计划摘要均已存在的阶段数量（即每个计划均已完成）。 |
| `progress.total_plans` | 整数 | 计划文件存在时 | 当前里程碑中所有阶段的计划文件总数。 |
| `progress.completed_plans` | 整数 | 摘要文件存在时 | 已完成的计划摘要总数（每个已执行计划一个 SUMMARY.md）。 |
| `progress.percent` | 整数 0–100 | 进度数据可用时 | 里程碑在**阶段维度**的进度（`min(completed_plans/total_plans, completed_phases/total_phases)`）。状态行进度条仅在该字段存在时渲染——缺失时进度条不显示。 |
| `current_phase` | 字符串 | 阶段正在执行时 | 从正文 `Current Phase:` 字段提取的阶段编号。 |
| `current_phase_name` | 字符串 | 阶段有名称时 | 从正文 `Current Phase Name:` 字段提取的阶段名称。 |
| `current_plan` | 字符串 | 计划进行中时 | 从正文 `Current Plan:` 字段提取的计划编号。 |
| `last_updated` | ISO-8601 时间戳 | 始终（写入时） | 最后一次 `syncStateFrontmatter` 调用的时间戳；由 `realClock.nowIso()` 写入。 |
| `last_activity` | 字符串 | 正文中设置时 | 最后活动日期，从正文 `Last Activity:` 字段提取。 |
| `stopped_at` | 字符串 | 记录了停止点时 | 最后完成操作的描述；限定在 `## Session` 正文章节内，以避免匹配存档文本。 |
| `paused_at` | 字符串 | 项目已暂停时 | 暂停点的自由描述；未暂停时缺失或为 `null`。 |
### 状态值
`get-shit-done/bin/lib/state-document.cjs` 中的 `normalizeStateStatus()` 将原始正文文本映射到以下规范值：
| 规范值 | 匹配文本（不区分大小写） |
|---|---|
| `discussing` | 包含 `discussing` |
| `planning` | 包含 `planning` 或 `ready to plan` |
| `executing` | 包含 `executing`、`in progress` 或 `ready to execute` |
| `verifying` | 包含 `verif` |
| `completed` | 包含 `complete` 或 `done` |
| `paused` | 包含 `paused` 或 `stopped`，或 `paused_at` 有值 |
| `unknown` | 以上均不符合 |
当编排器命令正在运行时，惯例（issue #2833）是直接将生命周期阶段写入 `status`：
| 命令 | 运行期间的 `status` |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## 状态行渲染场景
`hooks/gsd-statusline.js` 中的 `formatGsdState()` 读取已解析的前置数据并输出**第一个匹配的场景**。如果没有新的生命周期字段适用，渲染将回退到与 v1.38.x 完全一致的原始格式。
| 场景 | 触发条件 | 显示示例 |
|---|---|---|
| **1. 阶段活跃** | `active_phase` 已填充 | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. 空闲，有下一步推荐** | `active_phase` 为 null 且 `next_action` 和 `next_phases` 均已填充 | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. 里程碑完成** | `percent` 为 `100` 或 `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. 默认回退** | 以上均不匹配 | `v1.9 Code Quality · executing · ph 1/5`（现有格式） |
**场景优先级：** 当 `active_phase` 和 `next_action` 均已填充时，场景 1 优先——编排器正在运行，显示"下一步推荐"会造成误导。此优先级由 `formatGsdState()` 中的检查顺序强制执行，并由 `tests/enh-2833-phase-lifecycle-statusline.test.cjs` 中的 `"scene priority"` 测试套件覆盖。
进度条（`[██░░░░░░░░] 20%`）仅在前置数据中存在 `progress.percent` 时才追加到里程碑段；缺失则不显示进度条。
---
## 前置数据解析约束
状态行钩子使用基于正则表达式的解析（无完整 YAML 库），因此以下约束适用。这些约束在 `tests/enh-2833-phase-lifecycle-statusline.test.cjs` 中经过测试。
1. **前置数据必须从文件的第一个字符开始。** 任何内容——包括注释——出现在开头 `---` 之前都会使匹配失效。开头的 `---` 行必须恰好如此，不能有尾随空格。
2. **不支持嵌套块内的注释。** `progress:` 块解析器要求下一行为 `[ \t]+\w+:`。在 `progress:` 和其第一个键之间插入 `# comment` 会破坏匹配，进度条将消失。任何说明文档应放在 `STATE.md` 正文中，而不是放在前置数据块内。
3. **`next_phases` 首选格式为单行流式。** 解析器首先尝试 `next_phases: ["4.5", "4.6"]`。块序列（`- 4.5\n- 4.6`）也可解析，但对状态行渲染的可靠性较低。优先使用单行流式格式的 `next_phases` 以保持基于正则表达式的解析器的可预测性。如果需要记录大量候选阶段以供文档说明，请将其存储在 `STATE.md` 正文中。
如果未来的变更将正则表达式解析器替换为完整的 YAML 库，则这些约束可以放宽，并相应更新测试。
---
## Markdown 正文章节
正文（结束 `---` 之后的所有内容）遵循 `get-shit-done/templates/state.md` 中的模板。标准章节为：
### 项目参考
指向 `.planning/PROJECT.md`。包含：
- **核心价值** — 来自 `PROJECT.md` 核心价值章节的一句话说明。
- **当前焦点** — 哪个阶段处于活跃状态。
### 当前位置
项目当前所处的状态：
| 字段 | 格式 |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | 自由文本，如 `Ready to execute`、`Executing Phase 4`、`Phase complete — ready for verification` |
| `Last activity:` | 处理器写入时为 ISO 日期（`YYYY-MM-DD`）；执行器编写时为叙述性文本 |
| `Progress:` | 可视化进度条，如 `[████░░░░░░] 40%` |
当现有值为已知模板默认值时，该章节中的 `Status:` 和 `Last activity:` 字段由 GSD 处理器更新（Knuth 不变式：执行器编写的值被保留）。已知处理器默认值的完整列表位于 `get-shit-done/bin/lib/state-document.cjs` 中的 `KNOWN_TEMPLATE_DEFAULTS`。
### 性能指标
执行速度跟踪：
- 已完成计划总数，每个计划的平均耗时。
- 每阶段明细表（`Phase | Plans | Total | Avg/Plan`）。
- 近期趋势：改善中 / 稳定 / 下降中。
每次计划完成后更新。
### 累积的上下文
**决策** — 影响当前工作的近期决策摘要（完整日志在 `PROJECT.md` 中）。通过 `gsd-tools state add-decision` 添加。
**待处理的待办事项** — 数量及对 `.planning/todos/pending/` 的引用。通过 `/gsd-capture` 捕获。
**阻碍/关切** — 影响未来工作的问题，以发起阶段为前缀。通过 `gsd-tools state add-blocker` 添加；通过 `gsd-tools state resolve-blocker` 解决。
### 会话连续性
实现即时会话恢复：
- `Last session:` — 上次会话的 ISO-8601 时间戳。
- `Stopped at:` — 最后完成操作的描述。
- `Resume file:` — 指向 `.continue-here*.md` 文件的路径（若存在），否则为 `None`。
---
## 向后兼容性
阶段生命周期字段（`active_phase`、`next_action`、`next_phases` 以及用于进度条的 `progress.percent`）是**按项目可选添加**的：
- 未填充任何生命周期字段的 `STATE.md` 渲染结果与 v1.38.x 及更早版本**逐字节完全相同**。
- 添加任何生命周期字段是可选的——当字段缺失时，渲染器会优雅降级。
- 即使 `progress` 块存在，进度条也是可选的：只有 `progress.percent` 触发进度条；单独的 `total_phases` 和 `completed_phases` 不会触发。
`tests/enh-2833-phase-lifecycle-statusline.test.cjs` 中的 `formatGsdState #2833 backward compatibility` 测试套件锁定了此保证；任何破坏旧版 `STATE.md` 渲染的变更都将导致该套件失败。
---
## 相关内容
- [规划产物](planning-artifacts.md)
- [配置](../CONFIGURATION.md)
- [阶段循环](../explanation/the-phase-loop.md)
- [文档索引](../README.md)