上下文模板与模式

这是「GSD 全景代码解析」专题的第 36 篇。

---

在 GSD 框架中，上下文（Context）不仅是传递给 Agent 的信息集合，更是一种行为契约。通过切换不同的上下文模板，同一个底层模型可以在开发、研究、审查三种模式下表现出截然不同的输出风格与关注重点。

GSD 将上下文工程提炼为一套可复用的模板系统，存放在 get-shit-done/contexts/ 和 get-shit-done/references/ 目录中。本文将逐一解析其中的核心文件。

---

一、contexts/ 目录：三种核心上下文模板

contexts/ 目录包含三个上下文配置文件，分别对应开发、研究和审查三种工作模式。它们通过 config.json 中的 context 字段被动态加载，决定 Agent 的输出风格、关注领域和详细程度。

1.1 dev.md：开发上下文

dev.md 是面向代码实现的上下文模板，其核心哲学是简洁、行动导向。当 context: dev 被设置时，Agent 会收到如下指令：

# Dev Context Profile

Agent output guidance for dev mode. Loaded when `context: dev` is set in config.json.

## Output Style

- Concise, action-oriented responses
- Lead with the code change or command, follow with brief rationale
- Skip preamble — assume the developer has full context
- Use inline code references (`file:line`) over prose descriptions

## Focus Areas

- Working code that compiles and passes tests
- Minimal diff — change only what is necessary
- Flag side effects or breaking changes immediately
- Surface the next actionable step at the end of every response

## Verbosity

Low. One-liner explanations unless the change is non-obvious. Omit background theory, alternative approaches, and caveats that do not affect the current task.

设计意图解析：

• Lead with code：要求 Agent 先给出代码变更或命令，再附简要理由。这符合开发者的工作流——先看到结果，再理解原因。
• Skip preamble：假设开发者已具备完整上下文，避免重复解释已知信息。
• Minimal diff：强调最小化变更范围，只修改必要内容。这与代码审查中的「最小惊讶原则」一脉相承。
• Flag side effects：要求立即标记副作用或破坏性变更，防止静默引入问题。

适用场景： 编写功能代码、修复 Bug、重构实现、执行单元测试等需要高效产出的开发任务。

1.2 research.md：研究上下文

research.md 与 dev.md 形成鲜明对比，它面向探索与调研，要求 Agent 输出详尽、开放的分析：

# Research Context Profile

Agent output guidance for research mode. Loaded when `context: research` is set in config.json.

## Output Style

- Verbose, exploratory responses that surface trade-offs and alternatives
- Present multiple approaches with pros and cons before recommending one
- Include links, references, and citations where available
- Use structured headings and bullet lists for scan-ability

## Focus Areas

- Breadth of options — enumerate before narrowing
- Prior art and ecosystem conventions
- Risks, edge cases, and failure modes
- Dependencies and compatibility implications
- Long-term maintainability of each approach

## Verbosity

High. Explain reasoning, show evidence, and document assumptions. Include background context even if the developer likely knows it — research artifacts are read by future contributors who may not.

设计意图解析：

• Enumerate before narrowing：先枚举选项再收敛，防止过早陷入单一方案。
• Prior art and ecosystem：要求调研现有生态中的最佳实践，避免「重新发明轮子」。
• Future contributors：强调研究产物的持久价值——未来的贡献者可能不了解背景，因此需要完整的上下文记录。
• Risks and edge cases：专门关注风险、边界情况和失败模式，为后续决策提供充分信息。

适用场景： 技术选型、架构调研、第三方库评估、方案对比分析等需要深度探索的任务。

1.3 review.md：审查上下文

review.md 定义了代码审查模式下的 Agent 行为，其核心是批判性思维与结构化反馈：

# Review Context Profile

Agent output guidance for review mode. Loaded when `context: review` is set in config.json.

## Output Style

- Critical, detail-focused responses that prioritize correctness
- Organize findings by severity: blocking, important, nit
- Reference specific lines and files for every finding
- State what is correct as well as what needs change — confirm the good parts

## Focus Areas

- Correctness — logic errors, off-by-ones, missing edge cases
- Security — input validation, injection vectors, secret exposure
- Performance — unnecessary allocations, O(n^2) patterns, missing caching
- Style and consistency — naming, formatting, import order
- Test coverage — untested branches, missing assertions, flaky patterns

## Verbosity

Medium. Be thorough on findings but terse in explanation. Each issue should be one to three sentences: what is wrong, why it matters, how to fix it.

设计意图解析：

• Severity classification：将发现按 blocking / important / nit 三级分类，帮助审查者快速识别优先级。
• Confirm the good parts：不仅指出问题，也确认正确之处。这是高效审查的关键——正向反馈能维护团队士气，也帮助作者理解标准。
• Specific lines and files：要求每个发现都引用具体行号和文件路径，确保可执行性。
• One to three sentences：限定每个问题的描述长度，追求「足够清晰但不过度冗长」。

适用场景： 代码审查（Code Review）、安全审计、性能评估、测试覆盖分析等质量保障任务。

1.4 三种模板的对比总结

维度	dev.md	research.md	review.md
输出风格	简洁、行动导向	详尽、探索性	批判性、结构化
详细程度	Low	High	Medium
核心目标	高效产出代码	全面调研方案	发现质量问题
前置假设	开发者已有上下文	需要从零建立认知	代码已存在待评估
反馈格式	代码 + 简要理由	选项 + 利弊分析	严重程度 + 定位 + 修复建议

---

二、continuation-format.md：会话续写格式

在 GSD 的交互设计中，每个命令或工作流完成后，系统需要向用户清晰地呈现「下一步该做什么」。continuation-format.md 正是规范这一交互的标准模板。

2.1 核心结构

---

## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}

**{identifier}: {name}** — {one-line description}

`/clear` then:

`{command to copy-paste}`

---

**Also available:**
- `{alternative option 1}` — description
- `{alternative option 2}` — description

---

2.2 七条格式规则

continuation-format.md 定义了七条严格的格式规则：

1. Always show what it is — 必须展示名称 + 描述，绝不能只给命令路径
2. Pull context from source — 从 ROADMAP.md 获取阶段信息，从 PLAN.md 的 <objective> 获取计划信息
3. Command in inline code — 命令使用行内代码格式，方便复制粘贴，且渲染为可点击链接
4. /clear first — 总是在命令前显示 /clear，确保用户按正确顺序执行
5. "Also available" not "Other options" — 使用 "Also available" 而非 "Other options"，听起来更像应用界面
6. Visual separators — 使用 --- 作为上下分隔线，使其在视觉上突出
7. Project identity in heading — 在标题中包含 [PROJECT_CODE] PROJECT_TITLE，使跨会话的交接能自我识别

2.3 变体格式

continuation-format.md 还定义了两种变体格式。

执行计划变体（Execute Next Plan）：

---

## ▶ Next Up — [Execute Plan N - {title}]

**Plus required:** `{command}` — description

**Plus optional:** `{command}` — description

**Tests verify:** {verification steps}

`/clear` then:

`{command}`

---

此变体用于规划完成后，按顺序列出多个计划，标明哪些是必需的、哪些是可选的，并包含验证步骤。

规划完成变体（Planning Complete）：

---

## ▶ Next Up — [Planning Complete]

**What's next:** {what's next}

`/clear` then:

`{default command}`

**Also available:**
- `{alternative option 1}` — description

---

2.4 设计价值

continuation-format 的设计体现了 GSD 的**渐进式披露（Progressive Disclosure）**哲学：

• 主操作路径清晰突出（▶ Next Up）
• 替代选项存在但不喧宾夺主（Also available）
• 跨会话可识别（PROJECT_CODE）
• 操作顺序明确（/clear 在前）

这种格式让用户无需思考「下一步该做什么」，只需复制粘贴即可继续工作流。

---

三、revision-loop.md：修订循环模式

在 GSD 的多 Agent 协作体系中，一个 Agent 产出结果后，通常需要另一个专门的检查 Agent（checker/validator）进行质量验证。当检查发现问题时，系统需要驱动迭代修订。revision-loop.md 就是规范这一过程的模式文档。

3.1 核心模式：Check-Revise-Escalate

revision-loop.md 定义了一个最大 3 次迭代的三阶段模式：

prev_issue_count = Infinity
iteration = 0
LOOP:
  1. Run checker/validator on current output
  2. Read checker results
  3. If PASSED or only INFO-level issues:
     -> Accept output, exit loop
  4. If BLOCKER or WARNING issues found:
     a. iteration += 1
     b. If iteration > 3:
        -> Escalate to user
     c. Parse issue count from checker output
     d. If issue_count >= prev_issue_count:
        -> Escalate to user: "Revision loop stalled"
     e. prev_issue_count = issue_count
     f. Re-spawn the producing agent with checker feedback appended
     g. After revision completes, go to LOOP

3.2 两个关键的终止条件

revision-loop.md 设置了两个智能的终止条件，防止无限循环：

条件一：最大迭代次数（max 3 iterations）

超过 3 次迭代后，Agent 往往会陷入「在自己的反馈上打转」的状态，无法产生有意义的改进。此时必须将决策权交还给用户。

条件二：问题数停滞检测（issue count not decreasing）

如果连续两次迭代的问题数没有减少，说明生产 Agent 已经「卡死」，继续迭代无济于事。这是一个非常精妙的设计——它用可量化的指标替代了模糊的「足够好」判断。

3.3 升级后的用户交互

当循环因上述条件终止时，系统会执行以下操作：

1. 向用户展示当前输出 + 检查器反馈
2. 解释循环无法解决剩余问题的原因
3. 询问用户：接受现状（accept as-is）、放弃（drop）、或升级到不同的 Agent（escalate to a different agent）
4. 绝不自动继续修订——这是保障用户控制权的底线

3.4 反馈输入格式

revision-loop.md 还规范了向生产 Agent 发送反馈的标准格式：

### Checker Feedback (Iteration {N})

[[BLOCKING]] {title}
- File: `{file}` (line {n})
- Issue: {what is wrong}
- Why: {why it matters}
- Fix: {how to fix}

[[WARNING]] {title}
- File: `{file}` (line {n})
- Issue: {what is wrong}
- Why: {why it matters}
- Fix: {how to fix}

[[NIT]] {title}
- File: `{file}` (line {n})
- Suggestion: {what to consider}

这种结构化格式确保反馈的可执行性：每个问题都包含定位（文件+行号）、描述、影响分析和修复建议，生产 Agent 可以据此直接修改，无需二次解读。

---

四、scout-codebase.md：代码库侦察模式

当 GSD 处理已有代码库的项目（Brownfield）时，需要在讨论阶段（discuss-phase）加载代码库地图（codebase maps）来辅助决策。scout-codebase.md 是一张「懒加载」的参考表，用于根据阶段类型智能选择加载哪些地图文件。

4.1 核心思想：按需加载，而非全量加载

GSD 的代码库地图包含 7 个文档（STACK.md、ARCHITECTURE.md、STRUCTURE.md、CONVENTIONS.md、TESTING.md、INTEGRATIONS.md、CONCERNS.md）。一次性加载全部会膨胀上下文而不提升讨论质量。scout-codebase.md 的解决方案是：根据阶段类型，只加载 2-3 个最相关的地图。

4.2 阶段类型到地图的映射表

阶段类型	推荐加载的地图
UI / frontend / styling / design	CONVENTIONS.md, STRUCTURE.md, STACK.md
Backend / API / service / data model	STACK.md, ARCHITECTURE.md, INTEGRATIONS.md
Integration / third-party / provider	STACK.md, INTEGRATIONS.md, ARCHITECTURE.md
Infrastructure / DevOps / CI / deploy	STACK.md, ARCHITECTURE.md, INTEGRATIONS.md
Testing / QA / coverage	TESTING.md, CONVENTIONS.md, STRUCTURE.md
Documentation / content	CONVENTIONS.md, STRUCTURE.md
Mixed / unclear	STACK.md, ARCHITECTURE.md, CONVENTIONS.md

特殊规则：仅在阶段明确涉及已知问题或安全事项时，才加载 CONCERNS.md。

4.3 单文件单次读取规则

scout-codebase.md 还包含一条性能优化规则：

Read each map file in a single Read call. Do not read the same file at two different offsets — split reads break prompt-cache reuse and cost more tokens.

这条规则针对 Claude 的 prompt-cache 机制进行了优化。如果同一个文件被分两次读取（不同偏移量），会破坏缓存复用，导致额外的 Token 消耗。因此要求每个地图文件必须在单次 Read 调用中完整加载。

4.4 设计价值

scout-codebase.md 是 GSD **上下文预算管理（Context Budget Management）**的典范实践：

• 选择性加载：只加载与当前阶段相关的上下文
• 避免过载：7 个地图文件同时加载会淹没讨论的焦点
• 缓存优化：单次完整读取复用 prompt cache，降低 API 成本
• 模式驱动：用查表代替推理，决策速度快且一致

---

五、上下文模板的设计原则

综合以上五个文件，我们可以提炼出 GSD 上下文工程的五大设计原则：

5.1 行为契约原则

上下文模板不是信息摘要，而是行为契约。它明确告诉 Agent：「在这种模式下，你应该如何思考、如何表达、关注什么、忽略什么。」dev/research/review 三个模板几乎覆盖了软件开发中的所有认知模式。

5.2 渐进式披露原则

从 continuation-format 的「主操作 + 替代选项」分层，到 scout-codebase 的「按需加载」，GSD 始终遵循渐进式披露：先呈现最必要的信息，再按需展开细节。这避免了上下文窗口的浪费，也减少了用户的认知负荷。

5.3 可量化终止原则

revision-loop 的「最大 3 次迭代 + 问题数停滞检测」展示了如何用量化指标替代模糊判断。在 Agent 协作中，如果没有明确的终止条件，循环可能无限进行或过早放弃。GSD 用具体数字定义了「足够好」的边界。

5.4 结构化输出原则

无论是 review.md 的 blocking/important/nit 三级分类，还是 revision-loop 的 [[BLOCKING]] File/Issue/Why/Fix 格式，GSD 都强调结构化输出。结构化不仅便于人类阅读，更便于其他 Agent 解析和自动化处理。

5.5 自我识别原则

continuation-format 要求在每个会话结尾包含 PROJECT_CODE 和 PROJECT_TITLE，使跨会话的交接能够自我识别。这一原则贯穿 GSD 的设计——STATE.md、HANDOFF.json 等文件都服务于同一目标：让系统在不同会话间保持连续性。

---

六、总结

GSD 的上下文模板系统展现了「元提示工程（Meta-Prompting）」的精妙之处。通过约 200 行 Markdown 文件，它实现了：

• 三种认知模式的切换（dev / research / review）
• 清晰的会话续写引导（continuation-format）
• 受控的迭代修订循环（revision-loop）
• 智能的代码库上下文加载（scout-codebase）

这些模板不是孤立存在的，它们与 GSD 的工作流、Agent 体系和配置系统紧密协作，共同构成了一个自洽的上下文工程框架。理解这些模板的设计哲学，是掌握 GSD 精髓的关键一步。

下一篇预告： 第 37 篇《参考文档编写最佳实践》

我们将深入 GSD 的 references/ 目录，解析 mandatory-initial-read.md、thinking-models-planning.md、verification-patterns.md 等参考文档的编写规范。 敬请期待。