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>
91 lines
7.2 KiB
Markdown
91 lines
7.2 KiB
Markdown
# 上下文工程
|
||
|
||
> GSD Core 的存在原因及其旨在解决的问题。
|
||
|
||
---
|
||
|
||
## 问题：上下文腐化
|
||
|
||
每次 AI 编码会话都从全新开始。模型读取你的问题，对其进行推理，然后作出回复。但一次会话很少只有一轮交互。你会追问后续问题、粘贴错误信息、迭代代码，并在模型偏离方向时加以纠正。每一轮都会向上下文窗口中添加令牌——这是一个模型在同一时刻能"看到"的有限文本缓冲区。
|
||
|
||
随着该窗口逐渐填满，一些微妙的变化随之而来。模型不会高调地出错，它仍然持续作答，但答案的质量会悄然下降。早期的指令被推到它所能关注范围的边缘。最初几轮交互中的细节——你陈述的约束、你达成共识的架构、你标注的边界情况——都在与后续堆积的内容争夺注意力。研究人员将这种现象称为**上下文腐化**。
|
||
|
||
上下文腐化会以多种方式显现：
|
||
|
||
- 模型开始与它此前已认可的决定相矛盾。
|
||
- 代码风格偏离了会话开始时确立的规范。
|
||
- 计划开始忽略那些明确陈述过、但如今已深埋于历史记录中的需求。
|
||
- 模型产生幻觉，给出二十条消息前还正确的文件名或函数签名。
|
||
|
||
这些问题都不是模型的 bug。这是 Transformer 注意力机制在长序列上运作的基本属性。模型并非在"遗忘"——它从未以人类的方式"记住"过任何东西。它在有限窗口中对相关性进行加权，而随着窗口被积累的噪声填满，信噪比不断下降。
|
||
|
||
最直觉的应对方式是使用 `/clear` 重新开始。但这会丢失连贯性。你必须重新解释背景、重新粘贴相关文件、重新陈述约束条件。会话实质上归零重启了。
|
||
|
||
---
|
||
|
||
## GSD Core 的答案：全新上下文的子智能体
|
||
|
||
GSD Core 的核心洞见是：编码会话中*大多数*工作根本无需在主上下文中完成。研究、规划、代码编写和验证各自是独立且边界清晰的任务。每项任务都可以交给一个专门的子智能体来处理——该智能体以一个干净、精心限定范围的上下文窗口启动，并将其结果报告给一个保持精简状态的薄层编排器。
|
||
|
||
这不是上下文腐化的变通之法，而是一种结构性解决方案。
|
||
|
||
编排器——也就是你的主会话——从不接触源文件。它生成智能体、收集其结果、更新共享状态，并路由到下一个步骤。正因为它自身承担的工作很少，其上下文窗口的增长缓慢且可预测。繁重的工作发生在各个智能体中——每个智能体都以全新状态启动，仅接收完成其任务所需的上下文，并在完成后终止。
|
||
|
||
考虑这在实践中意味着什么。当你运行 `/gsd-plan-phase` 时，编排器会：
|
||
|
||
1. 加载一个紧凑的 JSON 上下文有效载荷（项目摘要、阶段目标、相关配置）。
|
||
2. 生成一个拥有 20 万令牌全新窗口的研究智能体。
|
||
3. 以研究输出和阶段需求为输入，生成一个规划智能体。
|
||
4. 生成一个计划检查智能体，在执行前验证计划。
|
||
|
||
每个智能体都以满负荷运行，不受会话积累历史的拖累。当规划器将其 `PLAN.md` 文件写入 `.planning/phases/` 时，该输出成为持久的产物——而非共享上下文窗口中脆弱的记忆。
|
||
|
||
---
|
||
|
||
## 规格驱动开发与元提示
|
||
|
||
仅靠上下文工程还不够。如果一个智能体以全新状态启动，却接收到模糊的指令，它产生的输出也将是模糊的。GSD Core 将全新上下文的子智能体与两项互补的原则相结合：
|
||
|
||
**规格驱动开发**意味着每个阶段在执行开始之前都会生成结构化产物。`CONTEXT.md` 捕获来自讨论步骤的实现决策。`RESEARCH.md` 记录研究智能体的发现。`PLAN.md` 将工作分解为离散的、按依赖关系排序的任务，并附有明确的验收标准。在执行器智能体接触文件之时，它已拥有一份精确的规格说明——而非对一段漫长对话的重新解读。
|
||
|
||
**元提示**意味着智能体定义本身就是经过精心设计的提示，而非临时指令。`get-shit-done/workflows/` 和 `agents/` 中的文件编码了关于如何限定任务范围、需要验证什么，以及何时上报至人工检查点的宝贵经验。用户无需在每次会话中重新解释这些知识；它已内嵌于系统自身的提示中。
|
||
|
||
这种组合是刻意为之的。全新上下文确保每个智能体清晰推理。规格驱动的产物确保每个智能体针对*正确的*事物进行推理。元提示确保每个智能体知道*如何*将其做好。
|
||
|
||
---
|
||
|
||
## `.planning/` 的作用
|
||
|
||
上下文工程要求知识能在上下文重置后得以保留。GSD Core 为此使用文件系统。每一项有意义的输出都以人类可读的 Markdown 或 JSON 格式写入 `.planning/`。这意味着：
|
||
|
||
- 重启会话（或模型崩溃）不会丢失工作成果。
|
||
- 任何后续智能体都可以直接读取先前的产物，而无需依赖共享的对话历史。
|
||
- 你可以检查、编辑规划产物，或将其提交到 git——它们是纯文本，而非数据库中不透明的状态。
|
||
|
||
`STATE.md` 是这个系统的支柱。它记录项目的当前位置（处于哪个里程碑、哪个阶段、哪些计划已完成）、活跃的决策和阻碍项，以及进度指标。每当工作流启动时，它都会读取 `STATE.md` 来定向自身。每当工作流完成一个有意义的步骤时，它都会回写 `STATE.md`。智能体不依赖记忆；它们依赖文件。
|
||
|
||
---
|
||
|
||
## 权衡
|
||
|
||
这里需要如实说明权衡之处。
|
||
|
||
**额外开销。** 阶段循环引入了真实的摩擦。将 `/gsd-discuss-phase`、`/gsd-plan-phase` 和 `/gsd-execute-phase` 作为独立步骤运行，比直接在普通会话中输入"实现这个功能"需要更多的耗时。对于小型、已充分理解的改动，这种开销并不值得。
|
||
|
||
**延迟。** 生成多个拥有全新上下文的子智能体，比单次上下文内编辑要慢。研究、规划和执行各自都会产生往返成本。
|
||
|
||
**简单任务的繁文缛节。** 如果你只需要重命名一个变量、修复一个错别字，或添加一个缺失的导入，阶段循环就是杀鸡用牛刀。GSD Core 提供了 `/gsd-quick` 和 `/gsd-fast`，用于处理不需要完整阶段的临时工作。请参阅[处理快速任务](../how-to/handle-quick-and-fast-tasks.md)。
|
||
|
||
当工作足够复杂、上下文腐化成为真实风险时，阶段循环才物有所值——例如多文件功能、横切重构、跨越数小时或多个会话的工作。其他情况下，请使用更轻量的原语。
|
||
|
||
一个有用的经验法则：如果任务可以用一个简短的提示完整描述，且无需进一步澄清就能在一次智能体回合中完成，跳过阶段循环。如果任务需要研究、涉及你近期未读取的文件，或依赖尚未确定的决策，阶段循环则能保护你。
|
||
|
||
---
|
||
|
||
## 相关内容
|
||
|
||
- [阶段循环](the-phase-loop.md) — 讨论 → 规划 → 执行 → 验证 → 发布的循环如何将上下文工程付诸实践
|
||
- [多智能体编排](multi-agent-orchestration.md) — 子智能体如何被生成、限定范围和协调
|
||
- [架构](../ARCHITECTURE.md) — 系统架构、智能体模型和数据流
|
||
- [文档索引](../README.md)
|