ConcertoNotes 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% | — |
超限处理
- STATE.md 超限：只保留最近 10 条决策日志，历史归档到
docs/memory/decisions.md。 - REQUIREMENTS.md 超限：已完成需求标注
[DONE]后迁移到docs/artifacts/{slug}/requirements-archive.md。 - ROADMAP.md 超限：已完成阶段折叠为单行摘要。
- 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 | 运行时快照 |
配套约束
- 四层文档是 快速加载视图，不替代 PRD / Delivery Plan / ADR 等正式交付物。
- 预算上限是硬约束：超限时必须裁剪而非放任增长。
- STATE.md 的决策日志必须与
docs/memory/decisions.md双向同步。 - 多 agent 并行写同一个 STATE.md 时，以最后合并为准；冲突时保留更高信息密度的版本。
- 不在这四层文档中存放代码片段、完整测试结果或大段日志——这些属于 L2 归档。
验证标准
- 四层文档均在 token 预算之内
- STATE.md 最后更新时间 < 当前会话开始时间（即已经在会话初始化时加载）
- 决策日志条数 ≤ 10 条，超出部分已归档
- 已完成需求有
[DONE]标记或已归档 -
/resume能在 < 15s 内加载全部四层并展示当前焦点