AI 编程助手使用指南：高效协作的艺术

AI 助手（Agents）是一项引人入胜的技术。它们是如此新颖和强大，以至于我们仍在不断探索其全部潜力以及有效利用它们的新方法。

在这篇博文中，我们总结了我们内部以及与我们优秀的早期测试用户群体共同探索出的 Augment 助手（Augment Agent）最佳实践。为了便于理解，我们将其组织成了常见问题解答（FAQ）的形式。

1- 目录

2- 前言

近期人工智能领域的许多进展都映射了人类的实际工作方式：

  • 更多时间，更好结果 – 如同人类，给予 AI 充足的思考时间能让其表现更优异 (链接)。
  • 善用工具 – AI 拥有更佳工具时能力会更强——正如人类一样 (链接)。
  • 从反馈中学习 – AI 通过反馈循环不断改进，这与人类从经验中学习非常相似 (链接)。
  • 受 💰 奖励驱动 – 像人类一样，提供物质奖励有时也能激励 AI 表现得更好 🙂 (链接)。

这一点对于 AI 助手尤其适用。与它们高效协作的关键在于 将其视为一位（经验或许稍浅，但非常聪明的）工程师同事。理解了这一点，其他所有方法论都会自然而然地清晰起来。

3- AI 助手擅长处理哪些任务？

在 Augment，我们观察到工程师们开始将 AI 助手应用于几乎所有工作场景——从前端、后端开发到代码合并请求（PR）审查、编写文档和设计规范，乃至协助进行头脑风暴。

当然，显而易见的是，某些任务相比其他任务更容易从 AI 助手中获益。以下是我们发现 AI 助手表现尤为出色的场景：

  • 修复可复现且易于验证（" 可测试 "）的 Bug。
  • 根据清晰的需求规格（来自任务工单或设计文档）或明确定义的需求来实现功能。
  • 进行头脑风暴和新想法的原型设计。
  • 深入探索复杂的代码库。
  • 处理 PR 中的审查意见。

更令人欣喜的是，随着 Augment 的开发者和用户每天都在发现新的应用场景，这份 列表 还在持续扩充 📈。我们鼓励您大胆尝试——AI 助手的潜力无限 ✨。

4- 应该如何向 AI 助手下达任务？

一旦开始使用 AI 助手，您很快就会形成自己的一套方法。在此之前，这里有一些我们发现非常有效的策略：

  1. 指令应详尽，避免过于简略

    • 对于复杂任务尤其如此。试图用寥寥数语的指令让 AI 完成复杂任务，几乎注定会失败。
    ❌ 将 `SettingsWebviewPanel` 类改为使用事件。
----------------------------------------------
✅ 当前，我们通过导入 `SettingsWebviewPanel` 类来直接调用 `SettingsWebviewPanel.statusUpdate()` 方法。代码审查者建议改用 VSCode 的事件机制来触发 `statusUpdate()`，目的是降低组件间的紧密耦合。请按以下步骤实现：
1. 创建一个新的 VSCode 事件。
2. 在 `SettingsWebviewPanel` 类的构造函数中添加相应的事件监听器。
3. 在原先直接调用 `statusUpdate()` 的地方，改为触发这个新创建的事件。

  2. 向 AI 助手提供充分的背景信息

    • 不仅要说明最终目标，还要解释其原因、相关的约束条件等。
      ✅ （参见上方示例）

    • 利用 Augment 集成功能 分享相关文档，例如任务工单、GitHub Issues 或 PR。
      ✅ … 请先阅读工单 AU-1858，并在 Notion 中查找关于身份验证的设计文档 …

    • 提供有帮助的参考示例。
      ❌ … 为 'ImageProcessor' 类编写测试 …
      ✅ … 为 'ImageProcessor' 类编写测试。可以参考 'text_processor.py' 文件中的测试组织方式作为示例 …

    • 明确指出相关的关键词和文件路径。
      ❌ … 为聊天后端启用 JSON 解析器 …
      ✅ … 为聊天后端启用 JSON 解析器。这个解析器应该在 'LLMOutputParsing' 类中使用，该类大致位于 'services' 子目录下 …

  3. 将复杂任务分解为更小、更易于管理的部分（循序渐进）

    • ❌ … 阅读工单 BC-986，实现设置菜单功能，编写单元测试，并更新相关文档 …
    • ✅ … 阅读工单 BC-986 … → 实现设置菜单功能 → 编写单元测试 → 更新相关文档 (分步执行)

  4. 对于复杂任务，先与 AI 助手讨论并细化执行计划

    • ❌ … 在设置菜单中增加时区选择功能 …
    • ✅ … 我需要在设置菜单中增加时区选择功能。请先构思一个实施方案，待我确认该方案可行后，再开始编码实现 …

  5. AI 助手擅长基于测试结果和代码执行输出来进行迭代优化。请充分利用这一点！

    • ❌ … 为 'TextGenerator' 类实现测试 … → (手动运行测试) → (将失败的输出复制给 AI 助手) → … 测试用例失败了，请修复 …
    • ✅ … 为 'TextGenerator' 类实现测试，并运行这些测试，确保它们能够成功通过 …

  6. 即使面对不熟悉的任务，也无需犹豫让 AI 助手尝试！ 让它去探索并给出初步方案——您将在此过程中学习到很多新知识。

    • ❌ （哦，这个任务我不太清楚怎么做，这样的话怎么委托给 AI 助手呢？）
    • ✅ … 我需要实现一种新的数据过滤算法。请先研究一下现有代码，然后提出一些可能的实现思路 …

  7. 当 AI 助手表现出色时，给予积极的反馈。 这有助于强化正确的行为模式。

    • ✅ … 非常棒，这基本上就是我想要的！现在只需要再处理一下这个边缘情况 …

以下是一个来自我们工程团队的真实、有效的指令示例：


(图片描述：展示了一个详细的指令，要求 AI 助手修改代码以采用事件驱动模式，替代原有的直接方法调用，并清晰列出了执行步骤。)


(图片描述：接续上图，可能展示了指令的更多细节、上下文信息或具体要求。)

5- 如果 AI 助手的行为不符合预期怎么办？

这种情况偶尔会发生，但无需过分担心——几乎总有办法解决！

您有两个主要选择：

  1. 如果 AI 助手完全偏离了方向，建议开启一个新的会话重新开始。
  2. 如果 AI 助手只是略有偏差，但已经取得了一些有用的进展，可以在当前会话中对其进行引导，纠正其方向。

无论选择哪种方式，最佳策略是尝试理解可能导致 AI 助手困惑的原因，并真诚地提供帮助：


(图片描述：可能是一张示意图，展示了如何通过沟通和提供更清晰的指令来引导 AI 助手纠正错误。)

其他实用技巧：

  • 当 AI 助手对文件进行了不正确的修改时，随时可以利用 Augment 助手强大的**检查点（Checkpointing）系统** 来回滚更改。
  • 策略性地创建新的 AI 助手会话：
    ❌ 所有任务都挤在一个冗长的会话中。
    ✅ 为每个逻辑上独立的任务开启新的会话。
  • 拥抱迭代式开发：
    ❌ " 这个模型没能一次性解决我的问题——看来它不怎么样。"
    ✅ 将复杂问题分解为若干易于管理的小步骤，逐步推进。
  • 语言选择：如果您主要使用非英语语言工作，考虑到现代大语言模型（LLM）的训练数据以英语为主，切换到英语指令可能会获得更好的效果。
  • 如果 AI 助手在理解某个特定框架的语法时遇到困难，可以明确指示它上网查询官方文档。

6- 如果我暂时无法完全信任 AI 助手怎么办？

这完全可以理解！如同人与人之间的信任，对 AI 的信任也并非一蹴而就——它需要逐步建立！

如果您担心 AI 助手可能在您的本地计算机上执行有潜在风险的命令，可以从使用**非自动模式（non-auto mode）** 开始。在此模式下，AI 助手执行任何命令前都需要得到您的明确批准。

如果 AI 助手对文件进行了错误的修改，您随时可以依赖我们的**检查点（Checkpointing）系统** 来撤销这些更改。

如果您对 AI 助手的能力尚不确定：

  • 初期可以将其用作 " 问答 " 工具，以检验它对您代码库的理解程度。例如，提问：请向我解释一下我们支持网站的授权（authorization）机制是如何运作的。 温馨提示：由于 AI 助手倾向于执行操作，提问时最好明确说明意图，例如加上：" 这只是一个问题，请不要修改任何文件。"
  • 之后，可以尝试一些简单的、边界清晰的任务：
    • … 请参照这个模式，实现更多的单元测试 …
    • … 将这几个函数重构到一个类中，作为静态方法 …

随着您不断看到积极的成果，您对 AI 助手的信心自然会随之增长！

7- 在 AI 助手运行期间，我应该做些什么？


(图片描述：该图可能描绘了开发者在等待 AI 助手执行任务时的不同状态或可以进行的活动。)

如同技术领域的许多技能一样，与 AI 助手协作的能力也需要时间来培养和提升。根据我们的内部观察，用户在使用 AI 助手方面大致可以分为三个熟练度级别——不同级别的用户在 AI 助手运行时倾向于采取不同的互动方式：


(图片描述：此图展示了三个用户熟练度级别及其在 AI 助手运行时可能采取的行动：初级用户可能被动等待或处理无关事务；中级用户会监控进度并准备反馈；高级用户则可能并行处理相关工作或主动引导 AI 助手。)

  • 初级用户 (Beginner): 通常会启动 AI 助手后就切换去做别的事情或 просто等待。他们主要在 AI 助手完成任务或遇到障碍时才进行干预。
  • 中级用户 (Intermediate): 会关注 AI 助手的执行过程，思考接下来的步骤，并准备在 AI 助手偏离预期时及时介入。他们可能会利用 AI 助手运行的间隙进行代码审查或准备后续的指令。
  • 高级用户 (Advanced): 将 AI 助手视为真正的协作伙伴。他们可能会在 AI 助手处理任务的一部分时，自己同步处理另一部分，或者主动利用 AI 助手的 " 思考 " 时间来规划更复杂的策略、进行并行研究或准备上下文信息。他们与 AI 助手的互动更为流畅和主动。

8- 如何审查由 AI 助手编写的代码？

代码审查（Code Review）的工作流程与审查人类工程师编写的代码大体上是相似的。

以下是一些旨在提高审查效率的建议：

  • 当利用 AI 助手进行较大规模的代码变更时，建议在每个子任务完成后及时进行审查，避免积压过多的 " 审查债务（review debt）"。
  • 对于 AI 助手生成的代码，随时可以向它提问以获取解释。
    • 注意：鉴于 AI 助手通常以行动为导向，直接提问（如 " 你为什么这么做？"）有时可能被误解为否定或要求更改。为了避免这种情况，可以在问题前加上明确的说明，例如：“纯粹好奇/只是想问一下：”。
  • 如果发现多处需要改进的地方，可以考虑在代码中留下注释，例如 #TODO(agent): 这里应该使用那个通用的工具函数，然后一次性要求 AI 助手处理所有标记了 #TODO 的注释，而不是逐一提出修改要求。
  • 可以要求 AI 助手运行 git diff 命令，帮助您核对变更的完整性，并检查是否有遗漏的清理工作。
  • 充分利用 AI 助手通过测试来迭代优化代码的能力。让它编写测试用例，运行测试，并根据结果验证功能的正确性。

9- 结语

这篇博文汇集了我们目前发现的、在使用 Augment 助手时效果良好的最佳实践。然而，我们深信，这仅仅是冰山一角，未来还有无限的技术和方法等待我们去发掘。我们非常期待听到您的实践经验——欢迎在我们的 社区 中分享您的心得体会。祝您编码愉快！