3bb2f8f1c5
* 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>
149 lines
6.4 KiB
Markdown
149 lines
6.4 KiB
Markdown
# 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)
|