这是「GSD 全景代码解析」专题的第 31 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。
一、Context Engineering 的定义和重要性
在 GSD 的自我定位中，它被描述为一个轻量级且强大的 Meta-Prompting、Context Engineering 和 Spec-Driven Development 系统。这三个概念构成了 GSD 的技术三角，而 Context Engineering（上下文工程）正是其中最核心的创新。
1.1 什么是 Context Engineering
Context Engineering 是一种系统化的上下文管理方法论。它的目标不是让 Prompt 变得更大，而是让进入 AI 上下文窗口的每一段信息都经过精心筛选、结构化组织和动态调度。
传统 Prompt Engineering 的思维是："如何写出一个更好的提示词？"而 Context Engineering 的思维是："如何构建一个系统，让每个 Agent 在正确的时刻看到正确的信息？"
flowchart LR
subgraph "Prompt Engineering"
P1[用户写 Prompt] --> P2[一次性提交]
P2 --> P3[模型响应]
end
subgraph "Context Engineering"
C1[系统化上下文管理] --> C2[分层加载]
C2 --> C3[动态筛选]
C3 --> C4[预算分配]
C4 --> C5[模型响应]
end1.2 为什么 Context Engineering 比 Prompt Engineering 更重要
在 AI 编程的实践中，真正制约输出质量的往往不是 Prompt 的措辞，而是上下文的质量和密度：
| 维度 | Prompt Engineering | Context Engineering |
|---|---|---|
| 关注点 | 单次交互的措辞优化 | 多轮交互的信息架构 |
| 解决的问题 | "模型不理解我的意思" | "模型被噪声淹没了" |
| 技术深度 | 写作技巧 | 系统架构设计 |
| 可扩展性 | 线性增长，难以复用 | 模块化，可复用 |
| 对长对话的影响 | 有限 | 决定性 |
GSD 的哲学是：Prompt 的精确性很重要，但上下文的纯净度更重要。一个措辞普通的 Prompt 配合高质量的上下文，远胜过一个精心雕琢的 Prompt 被淹没在噪声中。
二、Context Rot 的深层机制
在 GSD 的设计文档中，Context Rot 被定义为随着 AI 模型的上下文窗口被逐渐填满，输出质量持续退化的现象。要真正理解 Context Engineering 的必要性，我们必须先深入 Context Rot 的底层机制。
2.1 Context Rot 的三层病因
Context Rot 不是单一问题，而是三个相互强化的效应的叠加：
flowchart TD
subgraph "Context Rot 的三层病因"
A1[注意力稀释
Attention Dilution] --> A2[关键信息权重下降]
B1[干扰累积
Interference Accumulation] --> B2[无关信息挤占空间]
C1[状态污染
State Contamination] --> C2[错误结论被继承]
A2 --> D[Context Rot]
B2 --> D
C2 --> D
end注意力稀释（Attention Dilution）
Transformer 架构的核心是自注意力机制。在理想情况下，模型会为关键 token 分配更高的注意力权重。但当序列长度增加时，每个 token 可用的"注意力预算"被稀释。一个在高密度上下文中被精确引用的架构约束，在长上下文中可能只获得微乎其微的注意力权重。
干扰累积（Interference Accumulation）
在单体对话中，每一次试错、每一条错误堆栈、每一个被否定的方案都会留在上下文中。这些信息对于当时的决策可能有价值，但对于后续任务却是纯粹的噪声。随着对话轮次增加，噪声与信号的比例持续恶化。
状态污染（State Contamination）
这是最隐蔽也最具破坏性的机制。当一个 Agent 基于错误假设得出了错误结论，这个结论会留在上下文中。后续的 Agent 不会知道这个结论是错误的——它只看到"之前的对话已经确认了这个事实"。错误的结论像病毒一样在对话链中传播。
2.2 为什么传统方法无法根治
| 应对策略 | 问题 | 根本原因 |
|---|---|---|
| 手动清理上下文 | 用户难以判断哪些信息是关键依赖 | 缺乏系统化的上下文审计机制 |
| 频繁开启新对话 | 丢失项目记忆，需重复描述背景 | 没有持久化的上下文快照系统 |
| 依赖长上下文模型 | 200K 或 1M 窗口只是推迟 Rot | 注意力稀释是数学上的必然 |
Context Rot 的根本解不是"更大的窗口"，而是系统化的上下文隔离、刷新和筛选机制——这正是 Context Engineering 的核心使命。
三、上下文预算分配策略：200K Token 如何分配
GSD 将上下文管理工程化到协议级别。标准的上下文预算是 200K tokens（对于 Opus 4.6、Sonnet 4.6 等 1M 级模型可扩展至 1M），但这 200K 并非随意使用，而是按照严格的协议进行预算拆分。
3.1 标准预算分配表
pie title 200K Token 预算分配
"代码基线" : 80
"执行计划" : 40
"阶段上下文" : 30
"项目基础" : 20
"参考文档" : 20
"输出缓冲" : 10| 预算项 | 占比 | Token 数 | 内容 |
|---|---|---|---|
| 代码基线 | ~40% | ~80K | 相关源代码文件（按需读取） |
| 执行计划 | ~20% | ~40K | XX-YY-PLAN.md 完整内容 |
| 阶段上下文 | ~15% | ~30K | XX-CONTEXT.md + XX-RESEARCH.md |
| 项目基础 | ~10% | ~20K | PROJECT.md + STATE.md 摘要 |
| 参考文档 | ~10% | ~20K | references/*.md 中标记为必读的部分 |
| 输出缓冲 | ~5% | ~10K | Agent 输出预留 |
3.2 预算分配的工程约束
这种分配不是建议，而是硬性工程约束：
- 代码基线占 40%：确保 Agent 有足够空间理解相关代码，但不加载无关模块
- 执行计划占 20%：Agent 必须完整看到当前任务的目标、约束和验收标准
- 项目基础不超过 10%：
PROJECT.md和STATE.md只加载摘要版本，避免巨型项目文档吞噬预算 - 参考文档按需加载：不是一次性加载所有 references，而是根据当前任务选择性地加载 1-2 个
3.3 自适应扩展机制
对于 1M 级模型，GSD 启用自适应上下文增强：
# orchestrator 读取 context_window 配置
INIT=$(gsd-sdk query config-get context_window)
# 当 >= 500000 时，启用自适应上下文增强
# Executor 接收前一波的 SUMMARY.md + 阶段 CONTEXT.md/RESEARCH.md
# Verifier 接收所有 PLAN.md + SUMMARY.md + REQUIREMENTS.md这种机制使得大模型能够在保持 Fresh Context 原则的同时，获得跨计划的 awareness，而非盲目执行孤立任务。
四、@reference 机制：如何引用外部文档
@reference 是 GSD 上下文工程的关键基础设施。它允许工作流和 Agent 按需引用外部文档，而非将所有内容内联到主上下文中。
4.1 @reference 的基本语法
@~/.claude/get-shit-done/references/verification-patterns.md
@~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/references/questioning.md当 AI 运行时解析到 @reference 标记时，它会将对应文件的内容注入到当前上下文中。这与静态内联的区别在于：注入时机和范围是可控的。
4.2 @reference 的使用场景
| 场景 | 示例 | 效果 |
|---|---|---|
| 按需加载验证标准 | @reference verification-patterns.md | code-review 工作流只在审查阶段加载审查标准 |
| 按模式加载配置 | @reference questioning.md | discuss-phase 只在提问阶段加载提问策略 |
| 按项目加载品牌规范 | @reference ui-brand.md | UI 相关任务才加载设计系统规范 |
| Agent 技能外置 | @reference agent-skills/debugging.md | 调试 Agent 加载专用技能文档 |
4.3 @reference 与内联的对比
flowchart TD
subgraph "内联模式"
I1[工作流文件
包含所有逻辑] --> I2[一次性加载
1500+ 行] --> I3[大量无关内容
占用上下文]
end
subgraph "@reference 模式"
R1[工作流文件
核心逻辑] --> R2[按需 @reference
加载子文档] --> R3[只加载需要的内容
节省上下文]
end以 code-review 工作流为例：
- 内联方式：将 verification-patterns 的 300+ 行检查清单直接写入工作流 → 每个 code-review 调用都加载全部 300 行
- @reference 方式：工作流只保留
"参考 verification-patterns.md 中的标准"，实际审查时才加载 → 非审查任务完全不占用预算
4.4 Reference 文档的组织体系
GSD 的 references 目录包含 51 个共享知识文档，按职能分层：
references/
├── context-budget.md # 上下文预算协议
├── gates.md # 质量门控标准
├── verification-patterns.md # 验证模式库
├── questioning.md # 提问策略指南
├── ui-brand.md # UI/品牌规范
├── agent-skills/ # Agent 专业技能
│ ├── debugging.md
│ ├── refactoring.md
│ └── security.md
└── ...五、渐进式加载：按需加载，避免信息过载
渐进式加载（Progressive Disclosure） 是 GSD 上下文工程的核心设计技巧。它的原则很简单：只在需要的时候提供必要的信息。
5.1 为什么需要渐进式加载
83 个工作流中，有 3 个顶级编排器（execute-phase.md、plan-phase.md、new-project.md）的体量接近 XL 级别（1700 行）。如果一次性全部加载到 Agent 的上下文中，会迅速耗尽 token 预算。
更关键的是，工作流内部往往包含大量条件分支。例如 --auto 模式与交互模式的逻辑完全不同，但如果全部内联，那些当前条件不会触发的分支代码也会被加载，造成无效上下文浪费。
5.2 渐进式加载的四种模式
flowchart LR
A[渐进式加载] --> B[Mode 拆分]
A --> C[Template 外置]
A --> D[Reference 下沉]
A --> E[Agent 技能外置]
B --> B1[workflows/name/modes/]
C --> C1[workflows/name/templates/]
D --> D1[references/]
E --> E1[references/agent-skills/]| 模式 | 适用场景 | 文件组织 |
|---|---|---|
| Mode 拆分 | 同一工作流有多种互斥执行模式 | workflows/<name>/modes/*.md |
| Template 外置 | 需要填充的大段模板文本 | workflows/<name>/templates/*.md |
| Reference 下沉 | 共享知识被多个工作流引用 | references/*.md |
| Agent 技能外置 | Agent 专用技能描述 | references/agent-skills/*.md |
5.3 典范实现：discuss-phase 的重构
discuss-phase.md 是渐进式加载的最佳范例。原始文件曾是一个 2000+ 行的单体文件，经重构后变成：
workflows/
├── discuss-phase.md # 薄分发器 (~300 行)
└── discuss-phase/
├── modes/
│ ├── default.md # 默认交互模式
│ ├── power.md # Power-user 模式
│ ├── auto.md # 自动模式
│ ├── all.md # 全量问题模式
│ ├── chain.md # 链式追问模式
│ ├── text.md # 纯文本模式
│ ├── batch.md # 批量处理模式
│ ├── analyze.md # 分析模式
│ └── advisor.md # 顾问模式
└── templates/
├── CONTEXT.md
├── DISCUSSION-LOG.md
└── checkpoint.json父文件 discuss-phase.md 的逻辑简化为三步：
- 解析
--mode参数（默认default） - Read
discuss-phase/modes/{mode}.md - 按 mode 文件中的 process 执行
当用户以默认模式调用 /gsd:discuss-phase 时，只有 default.md 被加载；其他 8 个 mode 文件对当前上下文完全不可见，节省了约 70% 的 token。
5.4 大小预算的硬约束
渐进式加载不是可选项，而是硬约束——GSD 通过自动化测试强制工作流遵守大小预算：
| Tier | 行数限制 | 适用工作流 |
|---|---|---|
| XL | 1700 行 | 顶级编排器（execute-phase、plan-phase、new-project） |
| LARGE | 1500 行 | 多步骤规划器和大型特性工作流 |
| DEFAULT | 1000 行 | 标准工作流（目标层级） |
| 特殊约束 | <500 行 | discuss-phase（强制渐进式披露） |
超过限制的 workflow 必须拆分为多个文件或使用引用机制。
六、上下文分层：系统指令、参考文档、状态信息、任务上下文
GSD 的上下文不是扁平的文本堆叠，而是一个四层结构化体系。每一层有明确的职责、加载时机和更新频率。
6.1 四层上下文架构
flowchart TB
subgraph "上下文分层模型"
direction TB
L1["Layer 1: 系统指令
System Instructions
~20% 预算"] --> L2["Layer 2: 参考文档
Reference Documents
~30% 预算"]
L2 --> L3["Layer 3: 状态信息
State Information
~20% 预算"]
L3 --> L4["Layer 4: 任务上下文
Task Context
~20% 预算"]
L4 --> BUF["Reserve Buffer
~10% 预算"]
end6.2 各层详解
Layer 1：系统指令（System Instructions）
- 内容：工作流的核心逻辑、Agent 的角色定义、工具权限
- 加载时机：每次 spawn Agent 时固定加载
- 更新频率：低（随框架版本更新）
- 示例：
execute-phase.md中的 Wave 调度协议、gsd-executor的角色描述
Layer 2：参考文档（Reference Documents）
- 内容：共享知识库、验证标准、设计模式、提问策略
- 加载时机：按需通过
@reference加载 - 更新频率：中（随项目演进补充）
- 示例：
verification-patterns.md、ui-brand.md、context-budget.md
Layer 3：状态信息（State Information）
- 内容：项目全局状态、阶段进度、决策记录、阻塞项
- 加载时机：每次任务开始时加载摘要
- 更新频率：高（每个任务完成后更新）
- 示例：
STATE.md、ROADMAP.md、PROJECT.md摘要
Layer 4：任务上下文（Task Context）
- 内容：当前任务的具体信息、执行计划、代码上下文、验证标准
- 加载时机：针对特定任务定制
- 更新频率：每次任务都不同
- 示例：
XX-YY-PLAN.md、相关源代码文件、XX-CONTEXT.md
6.3 分层加载的执行流程
sequenceDiagram
participant O as Orchestrator
participant SDK as gsd-sdk
participant A as Agent
participant FS as File System
O->>SDK: query init.execute-phase "1"
SDK->>FS: 读取 PROJECT.md 摘要
SDK->>FS: 读取 STATE.md
SDK->>FS: 读取 01-CONTEXT.md
SDK->>FS: 读取 01-01-PLAN.md
SDK-->>O: JSON payload (分层上下文)
O->>A: spawn with Layer 1 + 3 + 4
Note over A: Layer 2 按需通过 @reference 加载
A->>FS: write 01-01-SUMMARY.md
A-->>O: done signal only这种分层架构确保了：
- 系统指令始终完整，Agent 不会遗忘核心协议
- 参考文档按需加载，避免无关知识干扰
- 状态信息保持最新，Agent 了解项目全局
- 任务上下文精确聚焦，Agent 清楚当前要做什么
七、GSD 的上下文管理 vs 其他框架的对比
理解了 GSD 的 Context Engineering 之后，我们将其与其他主流 AI 编程工具的上下文管理策略进行对比。
7.1 多维度对比
flowchart LR
subgraph "单体 Agent 模式"
M1[用户对话] --> M2[上下文持续累积]
M2 --> M3[Context Rot 递增]
M3 --> M4[质量下降]
end
subgraph "GSD Fresh Context 模式"
G1[Orchestrator] --> G2[Spawn Agent-1]
G1 --> G3[Spawn Agent-2]
G1 --> G4[Spawn Agent-3]
G2 --> G5[独立上下文]
G3 --> G5
G4 --> G5
G5 --> G6[质量稳定]
end| 维度 | 单体 Agent（传统模式） | Cursor/Windsurf（IDE 模式） | GSD（Fresh Context） |
|---|---|---|---|
| 上下文窗口 | 持续累积，无上限 | 当前文件 + 部分相关文件 | 每次 spawn 严格控制在 200K |
| Context Rot | 严重，随时间递增 | 中等，随会话增长 | 不存在，每次 fresh |
| 错误传播 | 错误结论持续影响后续 | 依赖人工介入修正 | 错误被隔离在单个 Agent 内 |
| 并行能力 | 伪并行，实际串行 | 不支持真正的 Agent 并行 | 真正并行（Wave 执行模型） |
| 上下文策略 | 无策略，全部保留 | 文件级上下文感知 | 四层分层 + 渐进式加载 |
| 调试难度 | 困难，需追溯整个对话 | 中等，可查看对话历史 | 简单，每个 Agent 独立审计 |
| 参考文档 | 无系统化支持 | 无系统化支持 | 51 个 reference + @reference 机制 |
7.2 各框架的定位差异
单体 Agent 模式（ChatGPT、Claude Web）
适合探索性任务和一次性编码。缺乏项目级状态管理，Context Rot 不可避免。当对话超过 20 轮时，输出质量开始明显下降。
IDE 模式（Cursor、Windsurf、GitHub Copilot）
通过代码索引和语义搜索提供文件级上下文感知。优势是实时代码补全和跳转，劣势是缺乏跨任务的持久化状态管理和系统化的 Agent 编排。
GSD 模式
将复杂度从对话层提升到系统层。通过文件系统作为状态存储、通过 Orchestrator 进行任务编排、通过 Fresh Context 隔离错误传播。代价是需要预先定义工作流和规划文档，收益是在复杂项目上的持续稳定输出。
7.3 Context Engineering 的普适价值
GSD 的 Context Engineering 方法论不仅适用于 GSD 框架本身，也可以借鉴到其他 AI Agent 系统的设计中：
- 预算意识：任何使用长上下文模型的系统都应该有明确的 token 预算分配策略
- 分层加载：将上下文分为系统层、知识层、状态层、任务层，按需组合
- 引用机制：使用外部引用替代内联，降低耦合，提高复用
- 渐进式披露：只在需要时加载信息，避免信息过载
- Fresh Context：关键任务使用全新上下文，避免历史噪声干扰
八、小结
上下文工程是 GSD 框架区别于其他 AI 编程工具的核心竞争力。它不是一项单一技术，而是一套完整的方法论体系：
| 核心机制 | 解决的问题 | 关键收益 |
|---|---|---|
| 200K Token 预算分配 | 上下文空间不足 | 确保每个 Agent 都有足够且适量的上下文 |
| @reference 引用机制 | 共享知识的复用和按需加载 | 避免重复内联，降低工作流耦合 |
| 渐进式加载 | 大工作流占用过多上下文 | 只加载当前需要的逻辑分支 |
| 四层上下文分层 | 信息组织混乱 | 系统指令、参考文档、状态信息、任务上下文各司其职 |
| Fresh Context 隔离 | Context Rot 和错误传播 | 每个 Agent 在纯净的上下文中工作 |
GSD 的设计哲学——"The complexity is in the system, not in your workflow"——在上下文工程层面体现得淋漓尽致。用户看到的只是简单的 /gsd:* 命令，背后却是一整套经过精心设计的上下文筛选、加载、隔离和刷新机制。
正如 TÂCHES 所说，他不是让 AI "替他写代码"，而是建立了一套系统化的上下文工程框架，让 AI 能够持续、可靠、高质量地为他工作。
下一篇预告： 第 32 篇《核心参考文档上》——深入拆解 GSD 的 51 个 reference 文档中最核心的部分，包括 context-budget.md、gates.md、verification-patterns.md 等共享知识库的设计原理和使用方法。这是理解 GSD 如何将"领域知识"编码为"可引用的系统资产"的关键一课，敬请期待！