📢 转载信息
原文链接：https://machinelearningmastery.com/5-agentic-coding-tips-tricks/
原文作者：Nahla Davies
5 智能体编程技巧与窍门
图片来源：Editor
引言
只有当智能体生成的差异（diffs）正确无误、通过了测试，并且留下了你可以信任的记录时，智能体编程才会显得“智能”。要最快达到这个目标，就不要要求智能体“构建一个功能”，而是给它一个它无法逃脱的工作流程。
该工作流程应强制要求清晰性（修改了什么）、证据（哪些通过了）和约束性（它能触碰什么）。下面的技巧是你可以立即应用到日常代码智能体工作中的具体模式，无论你使用的是 CLI 智能体、IDE 助手还是定制的工具调用模型。
1. 使用代码库地图（Repo Map）来防止盲目重构
当智能体不了解代码库拓扑结构时，它们会变得泛泛而谈。它们倾向于进行广泛的重构，因为它们无法可靠地定位正确的切入点。给智能体一个简短、有主见的、并锚定在关键部分的仓库地图。
创建项目结构和关键入口点的机器可读快照。保持在几百行以内。当主要文件夹发生变化时进行更新。然后在进行任何编码前将地图输入给智能体。
这是一个你可以放在 tools/repo_map.py 中的简单生成器：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
from pathlib import Path
INCLUDE_EXT = {".py", ".ts", ".tsx", ".go", ".java", ".rs"}
SKIP_DIRS = {"node_modules", ".git", "dist", "build", "__pycache__"}
root = Path(__file__).resolve().parents[1]
lines = []
for p in sorted(root.rglob("*")):
if any(part in SKIP_DIRS for part in p.parts):
continue
if p.is_file() and p.suffix in INCLUDE_EXT:
rel = p.relative_to(root)
lines.append(str(rel))
print(" ".join(lines[:600]))
|
添加第二个部分，命名真正的“热点”文件，而不是所有文件。例如：
入口点 (Entry Points)：
api/server.ts(HTTP 路由)core/agent.ts(规划 + 工具调用)core/executor.ts(命令运行器)packages/ui/App.tsx(前端外壳)
关键约定 (Key Conventions)：
- 绝不编辑
dist/中的生成文件 - 所有数据库写入都通过
db/index.ts - 功能标志（Feature flags）位于
config/flags.ts
这缩小了智能体的搜索空间，防止它因迷失方向而“乐于助人地”重写存储库的一半内容。
2. 使用差异预算强制执行“补丁优先”的编辑
当智能体像一个拥有无限时间的人类一样编辑时，它们就会偏离轨道。强迫它们像一个严谨的贡献者一样行事：提出一个补丁，保持其小规模，并解释意图。一个实用的技巧是差异预算，即每次迭代更改的行数有一个明确的限制。
使用如下工作流程：
- 智能体生成计划和文件列表
- 智能体仅生成一个统一的差异（unified diff）
- 你应用该补丁
- 运行测试
- 如有必要，进行下一个补丁
如果你在构建自己的智能体循环，请确保在机械层面强制执行此操作。伪代码示例如下：
|
1
2
3
4
5
6
7
8
|
MAX_CHANGED_LINES = 120
def count_changed_lines(unified_diff: str) -> int:
return sum(1 for line in unified_diff.splitlines() if line.startswith(("+", "-")) and not line.startswith(("+++", "---")))
changed = count_changed_lines(diff)
if changed > MAX_CHANGED_LINES:
raise ValueError(f"Diff too large: {changed} changed lines")
|
对于手动工作流程，将约束嵌入到你的提示中：
- 仅输出一个统一的差异（unified diff）
- 硬性限制：总共更改 120 行
- 不进行不相关的格式设置或重构
- 如果需要更多更改，请停止并请求第二个补丁
智能体对可衡量的约束反应良好。“保持最小化”是模糊的。“120 行更改”是可强制执行的。
3. 将需求转化为可执行的验收测试
模糊的请求可能会阻止智能体正确编辑你的电子表格，更不用说生成恰当的代码了。让智能体变得具体的最快方法，无论其设计模式如何，就是先将需求转化为测试，然后再进行实现。将测试视为智能体必须满足的合同，而不是一个尽力而为的附加组件。
一个轻量级的模式：
- 编写一个捕获功能行为的失败测试
- 运行测试以确认其因正确原因失败
- 让智能体实现，直到测试通过
例如，Python（pytest）中用于限速器的示例：
|
1
2
3
4
5
6
7
8
9
10
11
|
import time
from myapp.ratelimit import SlidingWindowLimiter
def test_allows_n_requests_per_window():
lim = SlidingWindowLimiter(limit=3, window_seconds=1)
assert lim.allow("u1")
assert lim.allow("u1")
assert lim.allow("u1")
assert not lim.allow("u1")
time.sleep(1.05)
assert lim.allow("u1")
|
现在智能体有了一个客观的目标。如果它“认为”自己完成了，测试会决定。
将此与工具反馈结合起来：智能体必须运行测试套件并粘贴命令输出。这个要求可以消除一整类“自信但错误”的完成。
效果很好的提示片段：
- 步骤 1：编写或完善测试
- 步骤 2：运行测试
- 步骤 3：实现直到测试通过
始终包含你运行的确切命令和最终的测试摘要。
如果测试失败，用一个自然段解释失败原因，然后打补丁。
4. 添加一个“橡皮鸭”步骤来捕获隐藏的假设
智能体会在数据形状、时区、错误处理和并发性方面做出静默的假设。在编码之前，通过一个强制的“橡皮鸭”时刻来暴露这些假设。
按顺序询问三件事：
- 智能体正在做出的假设
- 什么可能会破坏这些假设？
- 我们将如何验证它们？
保持简短和强制性。示例：
- 编码前：列出 5 个假设
- 针对每一个：使用现有代码或日志执行一个验证步骤
- 如果任何假设无法验证，提出一个澄清问题并停止
这会产生一个停顿，通常可以防止不好的架构提交。它还为你提供了一个简单的审查检查点。如果你不同意某个假设，可以在智能体编写代码将其固化之前进行更正。
一个常见的收获是及早发现数据合同不匹配。例如：智能体假设时间戳是 ISO-8601 格式，但 API 返回的是 epoch 毫秒。这种不匹配可能会级联成“修复错误”的重复工作。橡皮鸭步骤可以将其冲刷出来。
5. 使用运行配方（Run Recipes）使智能体的输出可复现
当团队中没有人能复现智能体所做的工作时，智能体编程就会失败。通过要求提供运行配方来解决这个问题：重复该结果所需的准确命令和环境说明。
采用一个简单的约定：每次智能体运行结束时，都生成一个 RUN.md 片段，你可以将其粘贴到 PR 描述中。它应包括设置、命令和预期输出。
模板：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
|
## Run Recipe
Environment:
- OS:
- Runtime: (node/python/go version)
Commands:
1) <command>
2) <command>
Expected:
- Tests: <summary>
- Lint: <summary>
- Manual check: <what to click or curl>
Example for a Node API change:
## Run Recipe
Environment:
- Node 20
Commands:
1) npm ci
2) npm test
3) npm run lint
4) node scripts/smoke.js
Expected:
- Tests: 142 passed
- Lint: 0 errors
- Smoke: "OK" printed
|
这使得智能体的工作具有可移植性。这也使自主性保持诚实。如果智能体无法提供干净的运行配方，那么它可能没有验证所做的更改。
总结
当你像对待工程实践而不是凭感觉一样对待智能体编程时，它的进步会很快。代码库地图可以阻止盲目游荡。补丁优先的差异可以保持更改的可审查性。可执行的测试将空泛的需求转化为客观的目标。橡皮鸭检查点可以在隐藏的假设固化成错误之前将其暴露。运行配方使整个过程对团队成员来说都是可复现的。
这些技巧并不会削弱智能体的能力。它们会使它更加锋利。一旦自主性被界定、可衡量并与真实工具反馈挂钩，它就会变得有用。那时，智能体就会停止听起来令人印象深刻，而是开始交付你可以合并的工作。
🚀 想要体验更好更全面的AI调用？
欢迎使用青云聚合API，约为官网价格的十分之一，支持300+全球最新模型，以及全球各种生图生视频模型，无需翻墙高速稳定，文档丰富，小白也可以简单操作。
评论区