agent/docs/03-practice-playbook.md

Practice Playbook

1. Define the Task

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

需要明确：

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

2. Choose the Smallest Useful Agent

从最小闭环开始：

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 和日志。
• 设计失败和回滚路径。
• 记录已知限制。