> ## Documentation Index
> Fetch the complete documentation index at: https://docs.embedder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 最佳实践
本页总结了让 Embedder 稳定产出高质量结果的关键做法。
最关键的变量是**会话长度**。会话越长，Embedder 累积的聊天历史、文件内容和命令输出越多，注意力就越容易分散。**保持任务聚焦、及时清理上下文，是提升准确率最有效的方法。**
## 1. 让 Embedder 能自证正确
在需求里写清“如何验证成功”，例如测试、构建命令或预期输出。
没有明确验收标准时，模型可能给出“看起来对”的答案，但运行后失败。
推荐写法：
* 先描述输入与预期输出
* 指定必须通过的测试
* 要求修复根因，不要绕过错误
示例：
| 场景 | 不佳提示 | 更佳提示 |
| ----- | ---------- | ----------------------------------------------------------------- |
| 传感器读取 | "实现温度读取函数" | "实现 `read_temperature()`；当原始值为 `0x0190` 时返回 `25.0°C`。补充单测并覆盖边界值。" |
| 构建失败 | "build 挂了" | "这里是报错信息：\[粘贴]。修复根因并验证 build 通过，不要屏蔽错误。" |
## 2. 先计划，再实施
复杂任务先用 Plan 模式做调研和计划，再切到 Act 模式落地。
推荐流程：
在 Plan 模式阅读代码、确认约束。
让 Embedder 输出分步计划与验证策略。
切到 Act 模式按计划改代码并验证。
让 Embedder 生成清晰 commit message，并创建 PR。
对于小改动（例如小 bug、重命名、日志增强），可以直接 Act 模式执行。
## 3. Prompt 要具体
约束越明确，返工越少。
高质量提示应包含：
* 修改范围（文件路径、模块）
* 目标行为与边界条件
* 不可突破的约束（性能、风格、框架限制）
* 验证方式（测试命令、验收标准）
示例对比：
* 不佳："加 I2C 传感器驱动"
* 更佳："参考 `drivers/adc.c` 与 `drivers/uart.c` 的风格，实现 `drivers/i2c_temp_sensor.c`，保持命名与错误处理一致，不引入新框架。"
## 4. 配置好 `EMBEDDER.md`
在新项目执行 `/init` 生成初稿，再人工精简。
`EMBEDDER.md` 应写“模型无法从代码中直接推断的信息”，例如：
* 必须执行的构建/测试命令
* 团队特有编码约定
* 环境限制与已知坑点
不要写成超长手册。内容过多会稀释重点，导致规则命中率下降。
## 5. 管理上下文与会话
* 不相关任务之间运行 `/clear`
* 连续两三次修不动同一问题时，`/clear` 后重开题
* 用 `/compress` 主动压缩长会话
* 用 `/history` 恢复历史会话
* 用 `/rewind` 或 `/undo` 快速回滚错误尝试
## 6. 善用子代理（Subagents）
让子代理负责大范围调研，把主会话留给实现。
示例：
```txt theme={"system"}
Use subagents to investigate CAN initialization, TX/RX interrupt handling,
and existing reusable drivers in this firmware project.
```
这样可以减少主上下文噪声，保持执行阶段更稳定。
## 7. 常见坑位
* 不做上下文清理，导致旧信息干扰当前任务
* Prompt 只有目标，没有验收标准
* `EMBEDDER.md` 过长、规则冲突
* 让模型“广泛探索”但不给范围，导致上下文被快速耗尽
先把任务边界、成功标准和参考文件写清楚，通常就能显著提升一次成功率。