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% | — |

超限处理

1. STATE.md 超限：只保留最近 10 条决策日志，历史归档到 docs/memory/decisions.md。
2. REQUIREMENTS.md 超限：已完成需求标注 [DONE] 后迁移到 docs/artifacts/{slug}/requirements-archive.md。
3. ROADMAP.md 超限：已完成阶段折叠为单行摘要。
4. PROJECT.md 超限：审查假设列表，移除已验证项。

工作流集成

写入时机

| 命令 / 事件 | 写入文档 | 操作 |

|-------------|----------|------|

| /team-intake 完成 | PROJECT.md, REQUIREMENTS.md | 创建或刷新 |

| /team-plan 完成 | ROADMAP.md, STATE.md | 创建或刷新 |

| /team-execute 每步完成 | STATE.md | 更新进度和决策 |

| /team-review 完成 | STATE.md | 更新放行结论 |

| /pause | STATE.md | 写入暂停快照 |

| /resume | — | 读取全部四层作为恢复上下文 |

| 角色 handoff | STATE.md | 追加交接记录 |

读取策略

Agent 启动时加载顺序：
1. PROJECT.md   → 建立背景
2. ROADMAP.md   → 确认阶段
3. STATE.md     → 获取当前焦点和阻塞
4. REQUIREMENTS.md → 按需参考（仅在需求相关任务时）

与既有体系映射

| context-engineering 文档 | Team Skills Platform 既有产物 | 关系 |

|--------------------------|---------------------|------|

| PROJECT.md | PRD 背景/约束 + Delivery Plan 版本目标 | 精简聚合 |

| REQUIREMENTS.md | PRD 用户故事/验收标准 | token 受控子集 |

| ROADMAP.md | Delivery Plan 工作拆解 | 阶段视图 |

| STATE.md | Execute Log + docs/memory/decisions.md | 运行时快照 |

配套约束

1. 四层文档是 快速加载视图，不替代 PRD / Delivery Plan / ADR 等正式交付物。
2. 预算上限是硬约束：超限时必须裁剪而非放任增长。
3. STATE.md 的决策日志必须与 docs/memory/decisions.md 双向同步。
4. 多 agent 并行写同一个 STATE.md 时，以最后合并为准；冲突时保留更高信息密度的版本。
5. 不在这四层文档中存放代码片段、完整测试结果或大段日志——这些属于 L2 归档。

验证标准

• [ ] 四层文档均在 token 预算之内
• [ ] STATE.md 最后更新时间 < 当前会话开始时间（即已经在会话初始化时加载）
• [ ] 决策日志条数 ≤ 10 条，超出部分已归档
• [ ] 已完成需求有 [DONE] 标记或已归档
• [ ] /resume 能在 < 15s 内加载全部四层并展示当前焦点