context-engineering

Context Engineering

用途

• 为复杂、多会话、多角色任务建立 结构化项目上下文，保证每轮 agent 启动时拿到完整且受控的项目背景。
• 与 context-lifecycle（运行时记忆管理）互补：本 skill 管 项目级文档层（L3+），context-lifecycle 管 运行时窗口层（L0-L2）。
• 控制文档 token 预算，避免"文档越来越多、上下文越来越模糊"的腐烂问题。

触发信号

• 新任务 intake 阶段需要建立或刷新项目上下文。
• /team-intake、/team-plan 输出后需要落盘为结构化文档。
• 跨会话恢复时需要快速加载上下文而不丢失关键决策。
• 多个 agent 并行工作需要共享一致的项目背景。
• 上下文窗口利用率接近阈值，需裁剪文档到预算范围。

四层文档模型

docs/artifacts/{slug}/
├── PROJECT.md          # 项目愿景、边界、关键假设   (≤ 3000 tokens)
├── REQUIREMENTS.md     # 范围化需求与验收标准       (≤ 5000 tokens)
├── ROADMAP.md          # 阶段路线与里程碑           (≤ 3000 tokens)
└── STATE.md            # 运行时状态：决策、阻塞、进度 (≤ 4000 tokens)

PROJECT.md — 项目愿景（≤ 3000 tokens）

不变频率最低，只在项目方向调整时更新。

# {Project Name}

## 愿景
一句话说明项目存在的原因和最终目标。

## 边界
- In Scope: ...
- Out of Scope: ...

## 关键假设
- [ ] 假设 1（待验证 / 已验证 / 已推翻）
- [ ] 假设 2

## 技术栈
- 语言 / 框架 / 基础设施

## 利益相关方
- 角色: 关注点

REQUIREMENTS.md — 范围化需求（≤ 5000 tokens）

每个 /team-intake 结束后由 product-manager 或 tech-lead 刷新。

# Requirements — {slug}

## 用户故事
- US-001: 作为…我希望…以便…
  - AC: 验收标准 1, 2, 3

## 功能需求
| ID | 需求 | 优先级 | 状态 |
|----|------|--------|------|

## 非功能需求
| 维度 | 目标 | 验证方式 |

## 约束
- 技术约束
- 业务约束
- 时间约束

ROADMAP.md — 阶段路线（≤ 3000 tokens）

里程碑粒度的阶段划分，由 project-manager 维护。

# Roadmap — {slug}

## 当前阶段
Phase N: {name} — {status}

## 阶段划分
| Phase | 名称 | 关键产出 | 完成标准 | 状态 |
|-------|------|----------|----------|------|

## 依赖图
Phase 1 → Phase 2 → Phase 3
              ↘ Phase 2b ↗

STATE.md — 运行时状态（≤ 4000 tokens）

频率最高，每个 /team-execute、/team-review、/pause 后刷新。

# State — {slug}

## 最后更新
{ISO timestamp} by {role}

## 当前焦点
当前正在推进的工作项。

## 决策日志（最近 10 条）
| # | 日期 | 决策 | 原因 | 影响 |
|---|------|------|------|------|

## 阻塞项
| 阻塞 | Owner | 状态 |

## 进度快照
| 工作项 | 状态 | 负责角色 | 备注 |

## 下一步
1. ...
2. ...

Token 预算管理

预算分配

文档	上限	占上下文比例	更新频率
PROJECT.md	3000 tokens	~1.5%	极低
REQUIREMENTS.md	5000 tokens	~2.5%	低
ROADMAP.md	3000 tokens	~1.5%	低
STATE.md	4000 tokens	~2%	高
合计	15000 tokens	~7.5%	—