# GSD Core - AI 编码上下文工程与规范驱动开发框架

> **GitHub**: https://github.com/open-gsd/gsd-core
> **npm**: `@opengsd/gsd-core`
> **License**: MIT
> **Slogan**: Git. Ship. Done.
> **研究日期**: 2026-06-07

---

## 一句话总结

GSD Core 是一套**上下文工程（Context Engineering）+ 规范驱动开发**框架，通过**全新上下文子代理（fresh-context subagent）** 架构解决 AI 编码中「上下文腐化」问题，让 Claude Code、Cursor、Codex 等 AI 编程工具在大型项目中保持高质量输出。

## 解决的核心问题：上下文腐化（Context Rot）

AI 编码会话随着对话轮次增加，上下文窗口逐渐被填满。模型不会报错，但输出质量**静默下降**：
- 开始 contradicts 早期决策
- 代码风格偏离初始约定
- 计划忽略早期明确的需求
- 臆造之前正确记忆的文件名/函数签名

这不是 bug，是 Transformer 注意力机制在长序列上的**固有特性**——信噪比随窗口填充而劣化。

## 核心方案：全新上下文子代理

**核心洞察**：编码会话中大部分工作（研究、规划、编写、验证）不需要在主上下文中进行。

架构设计：
- **主会话（编排器）**：不碰源文件，只负责派发代理、收集结果、更新状态。上下文缓慢增长。
- **子代理**：每个子代理以**干净 200k token 上下文**启动，只接收当前任务所需上下文，完成后终止。

```
主会话（轻量编排器）
  ├── Researcher Agent (200k fresh context)
  ├── Planner Agent (200k fresh context)  
  ├── Plan-Checker Agent (200k fresh context)
  ├── Executor Agent × N (200k fresh context, 并行)
  └── Verifier Agent (200k fresh context)
```

## 5阶段循环（Phase Loop）

每个里程碑通过重复的 5 步循环推进：

```
Discuss → [UI Design] → Plan → Execute → Verify → Ship
```

### 1. Discuss（讨论）
- 在规划前捕获实现决策（用什么库、错误处理策略、边界情况）
- 输出 `CONTEXT.md`（结构化决策记录）
- 几分钟对话避免几小时返工

### 2. UI Design（可选）
- 视觉相关阶段可选 `/gsd-ui-phase`
- 输出 `UI-SPEC.md`（布局、交互、视觉行为的设计契约）

### 3. Plan（规划）
- 3个全新上下文子代理依次运行：
  - **Researcher** → 调研生态，输出 `RESEARCH.md`
  - **Planner** → 读研究+CONTEXT，输出 `PLAN.md`
  - **Plan-Checker** → 验证计划完整、一致、在范围内
- 计划按依赖波次排列，支持并行执行

### 4. Execute（执行）
- 每个 Executor 以 200k 干净上下文启动
- 只加载：项目摘要 + 阶段上下文 + 研究 + 具体 PLAN.md
- 原子提交，每 commit 对应一个计划任务
- 按波次并行，前波完成后启动后波

### 5. Verify（验证）
- 不只是测试，检查：
  - 需求覆盖率（REQ-ID 是否都处理了）
  - 决策覆盖率（CONTEXT.md 的决策是否落地了）
  - 整体阶段目标对齐
- 输出 `VERIFICATION.md` + 修复计划（如有偏差）

### 6. Ship（交付）
- 创建 PR，归档阶段产物
- 更新 `STATE.md` 标记阶段完成
- 开始下一个阶段循环

## 关键文件结构

```
.planning/
├── STATE.md           # 项目当前状态（里程碑/阶段/进度）——系统脊梁
├── phases/
│   ├── CONTEXT.md     # 讨论阶段的实现决策
│   ├── RESEARCH.md    # 调研发现
│   ├── PLAN.md        # 具体执行计划（按波次）
│   ├── UI-SPEC.md     # UI 设计契约（可选）
│   └── VERIFICATION.md # 验证报告
ROADMAP.md             # 项目路线图
```

## 支持平台

Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf 等。

## 快速开始

```bash
npx @opengsd/gsd-core@latest
# 选择运行时和安装方式
/gsd-new-project
```

也提供轻量模式：
- `/gsd-quick` — 不需要完整阶段循环的快速任务
- `/gsd-fast` — 更轻量的即时操作

## 三大支柱

1. **Fresh-context subagents** — 每个子代理干净启动，结构性地解决上下文腐化
2. **Spec-driven development** — 执行前产出结构化产物（CONTEXT/RESEARCH/PLAN/VERIFICATION），代理精确执行
3. **Meta-prompting** — 代理定义本身是精心工程化的 prompt，编码了领域知识

## 与 Trellis 对比

| 维度 | GSD Core | Trellis |
|------|----------|---------|
| **核心理念** | 上下文工程 + 子代理架构 | 规范持久化 + 记忆 |
| **解决痛点** | 上下文腐化（质量随窗口填充下降） | AI 每次从零开始（无记忆） |
| **架构** | 主会话编排 + fresh-context subagents | 4阶段循环（Plan→Implement→Verify→Finish） |
| **记忆机制** | 文件系统（.planning/ 目录） | .trellis/workspace/ journal |
| **平台支持** | 10+ 平台 | 14+ 平台 |
| **License** | MIT | AGPL-3.0 |
| **适用规模** | 中大型复杂项目（上下文腐化严重时收益最大） | 个人/团队通用 |
| **轻量模式** | /gsd-quick, /gsd-fast | 无 |
| **验证深度** | 需求+决策+目标三重验证 | lint+type-check+测试 |

## 评价

### ✅ 优点
- **深刻理解了 AI 编码的根本问题**（上下文腐化是 Transformer 固有特性，不是 workaround 能解决的）
- fresh-context subagent 是**结构性解决方案**，不是权宜之计
- 5阶段循环设计严谨，每步都有明确存在的理由
- 验证环节不仅是测试，而是需求+决策+目标三重覆盖
- MIT 许可证友好
- 诚实承认 trade-off（简单任务不需要用完整循环）

### ⚠️ 注意
- 对简单任务有**流程开销**（官方也承认）
- 子代理启动延迟比单会话编辑慢
- 需要一定学习曲线理解阶段循环概念
- 最适合**中大型复杂项目**，小项目用 /gsd-quick 即可

### 📊 项目成熟度
- 完整文档体系（教程/指南/参考/概念）
- CI/CD 测试覆盖
- 活跃的社区（Discord + 多语言 README）
- 多平台支持
- 有 CLI 工具和完整命令体系

## 核心洞察（值得记住）

> "The model is not forgetting — it never 'remembered' in the human sense. It is weighting relevance across a finite window, and as that window fills with accumulated noise, signal-to-noise degrades."

> "An executor that runs with 180k tokens of accumulated session history is a degraded executor. An executor that starts clean and reads only what its plan requires is an executor operating at full capacity."

## 相关链接

- [GitHub](https://github.com/open-gsd/gsd-core)
- [npm](https://www.npmjs.com/package/@opengsd/gsd-core)
- [Discord](https://discord.gg/mYgfVNfA2r)
- [上下文工程详解](https://github.com/open-gsd/gsd-core/blob/next/docs/explanation/context-engineering.md)
- [阶段循环详解](https://github.com/open-gsd/gsd-core/blob/next/docs/explanation/the-phase-loop.md)

---

*研究归档：2026-06-07 | 路径：/obsidian/AI工程/GSD_Core_上下文工程框架.md*