# 上下文体系

> 相关：[[Harness工程]]、[[Agent_as_Code]]、[[AGENTS.md]]、[[过程方案vs事实方案]]

## 定义

**上下文体系**是AI协作的文档组织结构，通过分层文档为AI提供完整的上下文信息，让AI能够理解和遵循项目规范。

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

## 核心特征

### 1. 分层结构
- 宪法级：AGENTS.md
- 标准层：standards/
- 需求层：features/
- 设计层：designs/
- 计划层：plans/

### 2. 引用关系
- 上层文档引用下层文档
- 形成清晰的依赖关系
- AI可以理解完整上下文

### 3. 双轨管理
- 过程方案：Plans（追加不修改）
- 事实方案：Designs（覆盖更新）

## 文档分层结构

```
AGENTS.md          ← 宪法（所有AI工具读取）
docs/
├── standards/     ← 标准规格（架构/命名/API/安全规范）
├── features/      ← 需求规格（产品/BA维护）
├── designs/       ← 设计规格（事实方案，Source of Truth）
├── plans/         ← 计划规格（过程方案，追加不修改）
└── others/        ← 架构决策、Release、测试用例等
skills/            ← AI技能（可复用能力单元）
mcp/               ← MCP配置（外部工具接入）
```

## 各层职责

### AGENTS.md（宪法级）
- 定义项目基本信息
- 定义AI行为规则
- 定义目录结构
- 所有AI工具都从这个文件开始

### standards/（标准层）
- 代码风格规范
- API设计规范
- 数据库设计规范
- 安全规范

### features/（需求层）
- 产品需求文档
- 用户故事
- 验收标准
- 由产品/BA维护

### designs/（设计层）
- 数据库设计
- API设计
- 架构设计
- 事实方案，必须保持最新

### plans/（计划层）
- 任务计划
- 实现方案
- 过程方案，追加不修改

### skills/（技能层）
- 可复用的AI能力单元
- 包含提示词、脚本、文档

### mcp/（工具层）
- MCP配置
- 外部工具接入

## 构建引用关系

### 示例：AGENTS.md
```markdown
# 项目信息
- 项目名称：电商平台
- 技术栈：Java 17, Spring Boot 3.x

# 引用文件
- 代码规范：./docs/standards/coding-style.md
- API规范：./docs/standards/api-style.md
- 数据库规范：./docs/standards/db-style.md
```

### 示例：Plan引用Design
```markdown
# Plan: 实现用户注册功能

## 参考设计
- 数据库设计：../designs/database-schema.md
- API设计：../designs/api-design.md

## 实现方案
根据设计文档实现...
```

## 适用场景

- **团队协作**：多人协作需要统一的上下文
- **复杂项目**：复杂项目需要完整的文档体系
- **长期维护**：长期项目需要持续的上下文管理
- **知识传承**：新成员需要快速理解项目

## 优势

- **完整上下文**：AI可以理解完整的项目背景
- **易于维护**：分层结构，职责清晰
- **可追溯**：文档变更有历史记录
- **可复用**：标准和设计可以在项目间复用

## 挑战

- **初始成本**：需要建立完整的文档体系
- **维护成本**：需要持续维护文档
- **学习曲线**：团队需要理解文档体系

## 最佳实践

1. **从AGENTS.md开始**：先定义最基本的规则
2. **逐步扩展**：根据实践逐步添加文档
3. **明确职责**：每层文档有明确的职责
4. **定期Review**：定期审查和优化文档
5. **保持最新**：事实方案必须保持最新

## 相关概念

- [[Harness工程]]：上下文体系是Harness的组成部分
- [[Agent_as_Code]]：上下文体系是Agent as Code的文档组织
- [[AGENTS.md]]：上下文体系的宪法级文件
- [[过程方案vs事实方案]]：上下文体系的双轨管理方式