chill_notes/AI工程/概念/上下文体系.md

上下文体系

相关：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

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

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

示例：Plan引用Design

# 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事实方案：上下文体系的双轨管理方式