# Practice Playbook

## 1. Define the Task

先写清楚任务，而不是先写 prompt。

需要明确：

- 用户是谁？
- 高频任务是什么？
- 成功输出长什么样？
- 失败成本是什么？
- 哪些动作需要人工确认？
- 哪些上下文必须实时获取？

## 2. Choose the Smallest Useful Agent

从最小闭环开始：

```text
input -> context -> one decision -> one tool/action -> verification -> output
```

只有当任务确实需要时，再加入长期记忆、多 Agent、复杂规划或自动反思。

## 3. Design Tool Contracts

每个工具都应该说明：

- 它做什么。
- 它不做什么。
- 输入字段和约束。
- 输出结构和错误结构。
- 是否有副作用。
- 是否需要权限或确认。

## 4. Manage Context

上下文分三类处理：

| Context | Source | Strategy |
| --- | --- | --- |
| Task state | 当前对话、计划、工具结果 | 保持短摘要和待办 |
| Domain knowledge | 文档、代码、业务规则 | 检索并引用来源 |
| User preference | 历史习惯、明确指令 | 稳定保存，冲突时以当前指令为准 |

## 5. Add Verification

不要只问模型“你确定吗”。更好的验证方式：

- 运行测试。
- 检查输出格式。
- 对比预期 schema。
- 用独立样例回放。
- 对关键事实要求来源。
- 对高风险动作增加人工确认。

## 6. Observe Runs

一次 Agent 运行至少应该能回答：

- 输入是什么？
- 取了哪些上下文？
- 做了哪些决策？
- 调用了哪些工具？
- 工具返回了什么？
- 最后为什么停止？
- 成本、延迟、错误在哪里？

## 7. Improve With Experiments

优化不要凭感觉。把改动写成实验：

- 假设：我认为某个改变会提升某个指标。
- 变量：只改一个主要因素。
- 数据：使用固定任务集或真实样本。
- 指标：正确率、完成率、成本、延迟、人工改动量。
- 决策：保留、回滚、继续实验。

## Project Start Checklist

- [ ] 写项目目标和非目标。
- [ ] 定义核心用户旅程。
- [ ] 列出工具和权限。
- [ ] 定义数据和上下文来源。
- [ ] 明确成功指标。
- [ ] 准备最小评估集。
- [ ] 加入 trace 和日志。
- [ ] 设计失败和回滚路径。
- [ ] 记录已知限制。