142 lines
3.7 KiB
Markdown
Executable File
142 lines
3.7 KiB
Markdown
Executable File
# 上下文体系
|
||
|
||
> 相关：[[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事实方案]]：上下文体系的双轨管理方式
|