# AI上下文体系 - 团队级AI Coding简明手册

> 来源：幻灯片分享，2026-06-20 归档

## 核心理念

使用完整的文档来描述上下文和约束体系，**区分过程方案和事实方案，减少维护成本**。

---

## 文档分层结构

| 目录 | 用途 | 维护者 | 性质 |
|------|------|--------|------|
| `docs/standards` | 标准规格（API、命名、安全规范） | Tech Lead | 事实方案 |
| `docs/features` | 需求规格 | 产品/BA | 事实方案 |
| `docs/plans` | 计划规格（每轮任务实现方案） | AI/开发 | **过程方案** |
| `docs/designs` | 设计规格（DB、表等 Source of Truth） | AI/开发 | 事实方案 |
| `docs/others` | 架构决策、Release、测试用例 | — | 按需 |
| `AGENTS.md` | 宪法级约束 | — | 事实方案 |

---

## 过程方案 vs 事实方案

### 过程方案（Plans）

**定义**：每次 Plan/Go 循环产生的**执行计划**，记录"我们打算怎么做"。

**特点**：
- 临时的、一次性的
- 每次创建**新文件**（如 `plan-2026-06-20-feature-x.md`）
- 细微修改**不再更新**旧文件，直接创建新版本
- 作为执行记录，不是长期参考

**示例**：
```
docs/plans/
├── plan-2026-06-01-user-auth.md
├── plan-2026-06-05-user-auth-v2.md
└── plan-2026-06-10-payment-flow.md
```

**为什么这样设计**：
- 避免反复修改同一文件导致的 Git 冲突
- 保留历史决策轨迹，方便复盘
- AI 每次执行完可以"丢弃"，不污染长期文档

---

### 事实方案（Designs / Standards / Features）

**定义**：反映系统**当前真实状态**的文档，是 Source of Truth。

**特点**：
- 长期有效的、稳定的
- 每次变更以**最终态更新**（覆盖式修改）
- 作为下一次 Plan 的**起点和依据**
- 必须与实际代码/系统保持一致

**示例**：
```
docs/designs/
├── database-schema.md        # 当前数据库表结构
├── api-endpoints.md          # 当前 API 定义
└── architecture.md           # 当前架构图

docs/standards/
├── coding-style.md           # 编码规范
└── security-guidelines.md    # 安全规范
```

**为什么这样设计**：
- AI 每次 Plan 时读取这些文档，获得"当前真相"
- 避免 AI 基于过时的信息做决策
- 减少维护成本：只维护一份最终态

---

## Plan/Go 模式的规格流转

```
起点 Features
    ↓
Standards（约束）
    ↓
TDD 驱动测试 + 代码
    ↓
事实方案 Designs（更新最终态）
    ↓
过程方案 Plans（执行记录）
    ↓
回到起点 Features（验收）
```

**流转规则**：
- **追加**：创建新文件，细微修改不再更新 → 过程方案
- **变更**：以最终态更新，作为下一次 Plan 的事实依据 → 事实方案

---

## 实践建议

1. **AGENTS.md 作为宪法**：定义 AI 的行为边界和基本原则
2. **区分"打算做"和"已做完"**：Plans 是意图，Designs 是事实
3. **减少维护成本**：过程方案不维护，事实方案必须维护
4. **AI 友好**：每次 Plan 前读取事实方案，执行后更新事实方案

---

## 参考

- 幻灯片：如何让AI听话-构建AI上下文体系
- 归档日期：2026-06-20