编码代理入门：真正完成工作的艺术
现在是 2025 年。**编码代理不是魔法，但它们已经是最接近魔法的东西了。**我们注意到，一些工程师，特别是高级到资深级别的工程师，找到成功的速度比其他人更快。在这里，我们分享一些从客户和我们自己的经验中得出的顶级经验教训。
关于本指南
产品无关
我们讨论的技巧将帮助你成功使用任何编码代理。
战术性
我们提供我们最喜欢的可操作建议。
技术性
虽然编码代理对很多人都有价值，但本指南是为工程师编写的。
开发者工具一直在快速发展。十年前，是自动补全和智能感知，能够建议方法名称并执行程序化重构。四年前，是副驾驶和制表符补全，能够为你编写接下来的几行代码。两年前，是生成式聊天机器人，能够协助你的开发并为你生成整个文件。今天，是自主代理，能够在很少人工干预的情况下将初始描述转换为最终的拉取请求。
在过去的两年里，我们通过构建 Devin 专注于实现这一愿景。现在，对自主代理的兴趣达到了新的高度，特别是随着类似产品的最近发布。除了 Devin 外，最近的发布还包括 OpenAI 的 Codex 和 Google 的 Jules。一些本地代理如 Cursor 和 Claude Code 可以在并行工作空间中运行以复制类似的效果。这些代理可以以多种形式出现，包括网络应用、移动应用，以及在 Slack、GitHub、Linear 和 Jira 等流行工具中的集成。
虽然人类与 AI 助手配对可以比任何单独的 AI 实现更多，但自主代理端到端处理任务的能力允许了一个新的多任务处理级别，将每个工程师变成工程经理。
适应与这些新的 AI 同事有效合作可能需要一些时间。有趣的是，我们观察到高级到资深级别的工程师往往采用这些工具并变得最快的速度最快。最终，这些工具将在各级工程中变得普遍。基于我们的经验和客户反馈，我们想分享关键的见解和经验教训，以帮助每个人成功地将这些工具集成到他们的工作流程中。
提示基础
这些基本指南将帮助你在 2025 年有效地与编码代理互动。如果你只能记住一件事，那至少应该是这些。
说清楚如何做，而不仅仅是做什么
将代理视为一个初级编码伙伴，其决策可能不可靠。简单的任务可以直接描述，但对于更复杂的任务，从一开始就清楚地概述你的首选方法。向代理提供整体架构和逻辑不仅能增加其成功的机会，还能减少你审查代码的时间，因为你已经熟悉了预定的方法。
例子：
不要说"添加单元测试"，而是指定要测试的功能，识别重要的边缘情况，并澄清需要模拟什么（如果有的话）。
告诉代理从哪里开始
想想如果你自己处理任务会从哪里开始。即使你不知道具体的文件或函数名，也要提及仓库、相关文档和涉及的关键组件。清楚地指明这些元素可以最大限度地减少浪费的努力和混淆。
例子：
"请为我们的代码添加对 Google 模型的支持。你应该查看最新文档，并在模型组目录中创建新的实现文件"
练习防御性提示
想象一下给新实习生同样的提示。哪里会出现混淆或错误？预见这些点并主动澄清你的指令以避免歧义。
例子：
"请修复我们搜索模块的 C++ 绑定以通过新的单元测试。小心，你可能需要在每次更改代码后重新编译绑定才能测试。"
给予访问 CI、测试、类型检查器和代码检查器的权限
代理的魔力很大程度上来自于它们修复自己错误并根据错误消息迭代的能力。通过类型检查器、代码检查器和单元测试等工具提供强大的反馈循环大大增强了它们的性能。考虑使用类型化的 Python 而不是普通 Python，或者使用 TypeScript 而不是 JavaScript。教你的代理如何运行常见的检查和测试，确保它拥有所有必要的包和访问权限。如果代理可以与浏览器交互，提供关于运行前端开发环境的清晰指令。
例子：
我们的团队从大部分非类型化 Python SDK 转换到专门使用类型化 SDK（这理想情况下也是编码代理的好任务）。
利用你的专业知识
当你熟悉你的代码库时，以上所有一切都变得更容易。即使是简单的任务也受益于你验证逻辑和结果的能力。人类监督仍然必不可少——最终，你要对代码的最终正确性负责。所有权和验证将继续是人类工程师的关键职责，即使这些工具变得越来越复杂。
在工作流程中使用代理
一旦你掌握了与代理交谈的基础，是时候将这些 AI 助手带入你的日常工作流程中了。以下是一些让代理成为你例行工作的实用方法：
立即接受新任务
想象一下队友给你发消息，"嘿，我们能快速构建 X 吗？"或者"我们需要调整 Y"。不要让它打断你的流程，只需向自主代理发送一个快速提示来调查或进行更改。这让你能够专注于主要任务。有有趣的副项目想法？需要快速制作原型、抓取数据或重现研究？委托给你的代理，稍后再回来处理。
例子：
许多团队在讨论错误修复或次要功能更新时只需在 Slack 上标记 @Devin。
随时编码
想象一下你在通勤或旅行时突然出现紧急错误，或者你意识到代码中可能留下了错误。不用担心！自主代理通常支持移动访问，让你能够立即解决这些问题。无论是通过 Slack 的移动应用还是专门的移动应用，许多代理都让你随时随地解决问题，即使你的 wifi 不稳定。
例子：
拥有这种选择权使我们的团队在乘车和飞行时变得更有生产力。
交出你的杂务
陷入为旧提交进行二分查找或为新功能更新文档的困境？将这些重复性任务交给你的代理。你将节省宝贵的时间，并专注于更有创造性和影响力的工作。
例子：
在我们的团队中，工程师经常在发布更改后让代理更新所有相关文档和面向用户的文本。
跳过分析瘫痪
困在决定重构是否真的会简化你的代码？无法在两种架构方法之间选择？让你的代理实现两个选项。通过具体的例子进行比较，决策变得简单明了，而且丢弃一个解决方案不会伤害任何感情。
例子：
当在文本框的 Lexical 和 Slate 之间选择时，我们让代理实现每一个。Slate 因为提供更好的最终结果而胜出。
设置预览部署
设置 CI/CD 管道为每个新 PR 自动创建预览部署，给你一个即时在线 URL。这在审查 AI 代理完成的前端任务时特别方便。
例子：
Vercel 是一个让预览部署变得超级简单的部署平台。
委托更大的工单
随着你的拉取请求的大小和复杂性增长到超过几个文件，一次性处理它们变得具有挑战性。然而，掌握如何委托中到大任务（通常是 1-6 小时的工作）是自主代理提供最高 ROI 的地方。不仅仅是节省几分钟，你可以重新获得数小时的生产力。小任务可能毫不费力地工作，但扩展代理处理更大任务的能力带来最大的回报。
自动化你的初稿
对于重要任务，使用自主代理为你的 PR 创建初稿可以启动进展并大幅减少你的工作量。这里的成功取决于从一开始就清楚地传达你想要的方法。将自己视为指导初级开发者的架构师。清晰、详细的指令有助于避免花费不必要的时间来纠正代理代码中的根本性误解。
| 领域 | 起草 | 完善 |
|---|---|---|
| 新闻业 | 记者收集初始信息，撰写文章初稿 | 编辑审阅草稿，事实检查，润色并最终确定出版 |
| 餐厅 | 配菜厨师准备食材并制作初步菜肴 | 副厨师添加调味料并调整菜品以更好地调味，然后送给用餐者 |
| 编码 | 自主代理基于初始计划开始任务并创建初稿解决方案 | 人类开发者审查草案 PR，提供反馈，并在合并前添加手动完善 |
🛑 记住，大任务还不是完全免提（还）。预计更挑战性的任务会有多个反馈周期，并预期一些手动的完善。一个现实的目标是大约节省 80% 的时间，而不是完全自动化，你的专业知识对于验证和最终质量保证仍然至关重要。
共同开发 PRD
对于复杂或定义不清的任务，与你的自主代理合作创建详细计划可能非常有效。如果你一开始不知道每个细微差别或要求，那完全没关系。首先提示你的代理探索发现性问题，比如"我们的身份验证系统如何运作？"或"哪些服务可能会受到影响？"你也可以要求代理为你识别具体的相关代码目标，让你尽早确认。
某些代理，如 Devin 和 Claude Code，提供专门的规划模式，专注于读取和探索现有代码而不是立即修改它。如果你希望在委托任务之前进行更深入的准备，专门的代码库搜索工具如 deepwiki.com 和 Devin Search 可以快速提供你的代码库的洞察，帮助简化流程。
设置检查点
对于多部分任务，特别是涉及多个代码库的任务，沿途建立清晰的检查点：
计划 → 实现块 → 测试 → 修复 → 检查点审查 → 下一个块
明确要求在每个重要阶段后暂停，特别是对于在多个层（例如，数据库、后端、前端）构建的复杂功能。使用这些检查点确保实现符合你的期望，澄清疑问（例如"解释身份验证过程并确认其安全性"），并及早纠正路线以避免级联问题。
例子：
"我希望你实现这个将跨越我们数据库、后端和多个前端界面的功能。请首先规划所需的数据库模式更改，并在完成时让我知道，这样我就可以应用迁移。" → "现在请实现后端更改并添加测试以确保 XYZ 工作。让我知道完成时" → "现在在我们的 web 和移动界面中实现更改以调用新的后端端点"
教它验证自己的工作
在给出反馈时，不要仅仅指出问题（"这个函数不工作"）。清楚地表达你的测试过程，使代理能够独立验证未来的任务。对于你将经常重复的测试模式，将这些集成到代理的永久知识库中。
例子：
在 Devin 中，我们主动提示用户将基本测试程序保存到代理的持续记忆中，简化未来的互动。
在 AI 热点增加测试覆盖率
目前，代理还没有能力完全彻底地交互测试所有场景。在 AI 大量修改的区域增强测试覆盖率确保了对代理输出的更大信心。可靠的测试意味着看起来正确的代码可以放心地合并而不用担心。
例子：
我们的团队在信任 AI 将实现从 Python 转换为 C 之前，加强了代码库关键部分的单元测试。
自动化工作流程
代理可以比人类快得多地响应传入事件，而且它们比人类对应物更愿意做无聊、重复的工作。
为你最重复的工作创建快捷方式
工程团队经常遇到重复、例行的任务。这些是代理自动化的完美候选者。常见例子包括：
- 功能标志移除
- 依赖升级
- 在新功能 PR 上修复和添加测试
为了有效地设置这个，有经验的工程师通常创建一个强大、可重用的提示模板。在 Devin 中，这些称为 playbooks，可以为这些场景重复运行。
例子：
我们的一个客户在开发新功能时自动触发三个专门编写单元测试的代理。
智能代码审查和强制执行
虽然存在用于快速代码审查的专业工具（如 Greptile 和 CodeRabbit），自主代理可以是提供更准确洞察的有趣选择，特别是如果它们已经索引了你仓库的功能。
例子：
在 Cognition，我们喜欢维护一个工程师最常见的错误列表，并将此列表提交到代码库。然后，不是编写传统的 lint 规则来捕获这些（通常不可能），我们让代理在每个新 PR 上运行以检查这些错误。
钩入事件和警报
你也可以设置自主代理在响应特定事件时自动触发。例如，Devin 提供了一个可访问的 API，其他代理可以通过 CLI 命令集成到自定义工作流程中。这些设置与 MCPs 一起工作特别好，可以摄取第三方错误日志。
⚠️ 当涉及到对生产服务问题进行分类时，AI 的调试技能不是那么好。与其要求 AI 在错误出现时端到端地修复错误，通常更实际的是要求 AI 只是标记最可疑的错误、更改等。
定制和提高性能
环境设置
没有什么比不完整或不匹配的环境更能减慢代理速度。为了保持事情顺利进行，将代理的设置与你的团队完全对齐。这包括语言版本、包依赖和自动检查。例如，pre-commit 应该安装在代理的环境中，环境配置（秘密、语言版本、虚拟环境、浏览器登录）应该使用 .envrc 或 .bashrc 的自定义配置自动获取。
例子：
我们用预认证登录设置了代理的浏览器，消除了手动认证的麻烦，使测试更容易。
构建自定义 CLI 工具和 MCPs
MCPs 广泛可用，并且设置快速，实验连接你的代理到外部工具。但很多人忽视了为代理设置简单的 CLI 脚本。作为一个简单的例子，你可以给你的代理一个脚本，根据工单 ID 提取关于 linear 工单的信息。你可能还想给你的代理一个工具来可靠地执行工作流程的常见部分，比如重启本地开发环境的脚本。
例子：
我们有一个客户在创建一个 CLI 工具方面取得了很大成功，该工具只在测试套件中显示第一个失败的测试。CLI 提示代理只专注于那个测试并带有详细错误信息，这个 CLI 导致代理在长任务上有更高的成功率和更快的完成时间。
添加到代理的知识库
如果你的代理犯了一些常见错误，这是将你的反馈编入代理知识库的好时机。在 Devin 中，有一个专门的知识管理系统。许多产品提供 .rules 文件、代理永久摄入的 .md 文件。不要只给它关于你使用的框架的指导，还要告诉它你项目的整体架构。告诉它不同类型的任务常见的测试类型，如何运行重要命令以及你推荐使用哪些工具。
例子：
我们给我们的代理关于添加新服务路线时应遵循的特定程序的知识。信息包括它需要在前端和后端添加样板代码的所有地方。因此，这些任务现在很容易委托给我们的 AI。
实际考虑因素
自主代理的局限性
有限的调试技能
错误报告可能具有欺骗性的简单。但许多错误不仅需要访问数据库和日志，还需要超过今天大多数 AI 代理的调试级别。如果使用 AI 来帮助调试，我们建议询问可能的根本原因列表，而不是试图调试和修复一切。然后，人类可以根据自己的经验决定哪一个是真正的根本原因。但一旦原因已知，代理在实现修复方面仍然非常有帮助。
细粒度视觉推理差
通常今天的模型在匹配设计截图或 Figma 模型所需细节级别的视觉推理能力方面不是很好。它们在可以用代码级别描述的视觉效果上最可靠（例如给它来自 Figma 的代码）。如果你想让它匹配你的视觉风格，你应该使用带有可重用组件的良好设计系统。
知识截止
每当你想要使用新库时，你应该明确指出最新的文档。否则，由于预训练基础模型中的知识截止，大多数代理会假设这些库的旧模式。如果你指向文档，一个好的代理可以克服这一点，但你必须意识到这一点（记住，代理甚至不知道这些库有新版本）。
管理时间和最小化损失
不是每次使用代理都会导致成功。在 2025 年，这些代理的结果存在一些真正的变化。工作的一部分涉及学习如何使用代理，以最大化遇到成功结果的机会，同时最小化浪费的时间和令牌。
愿意更早止损
刚开始使用代理的人的一个常见错误是他们致力于让交互成功，即使代理的工作偏离轨道。如果你发现自己认为"它忽略了我的指令"或"这东西在兜圈子"，你应该可以停止那个对话或手动接管。发送更多消息更可能是你的任务固有的复杂性高于代理能力的标志，而不是一些可以纠正的简单错误。
多样化你的实验
如果你是代理工作的新手，我们建议在开始时多样化你的赌注。尝试一系列不同的提示和想法。加倍投入你看到代理自然表现良好的任务类型——并在它们不行的任务上止损。不要觉得需要强迫你的代理每次都找到成功。
当你没有进展时重新开始
在代理中，重新开始是比人类更正确的答案。如果你给代理一个任务，它在处理反馈或纠正路线时遇到困难，用一个新的代理和所有的指令重新开始通常可以更快地到达成功。代理纠正混乱环境的能力比它从头开始吐出新代码的能力差得多。
安全和权限
为你的代理创建账户
一次性电子邮件有助于安全测试网站。如果代理需要访问云资源，创建自定义 IAM 角色。
给它一个开发/暂存环境
理想情况下，代理使用与你团队工程师相同的测试设置。我们建议完全避免给予对生产服务的访问。当使用远程代理时，你可以在代理的远程机器上运行完全隔离的测试环境。
只读 API 密钥
尽可能给它只读访问。我们发现让人类手动运行任何与外部服务交互的脚本仍然是有帮助的。
巨大变化即将到来
我们坚信软件工程师不会去任何地方。即使编码代理变得更智能、更有能力，深厚的技术专业知识和对你代码库的亲密了解仍然是无价的。对你的项目、你的系统和你的代码的真正所有权现在比任何时候都更关键。
在我们团队今天，工程师被期望监督多个系统，同时保持深入理解和深思熟虑的判断。随着自动化放大你的影响，同时处理并行任务的能力不仅将变得可能；它将变得必要。我们很高兴分享我们在为自己的组织准备这一转变时收集的见解，这样你和你的团队也可以在不断发展的软件开发世界中茁壮成长。