基础 / 用 AI agent 开发
English

用 AI agent 开发

把问题讲清楚，让 agent 去调查、提出建议，并证明结果成立。

更新于 2026年11月5日查看 Markdown
本页内容

给出目标，不要给出修法

  • 提供目标、约束、仓库说明和相关示例；让 agent 自己找到代码，推荐一个稳妥的做法。
  • 除了范围小、目标明确的修改，其他都先让它出计划，商定后再动手实现。改计划只要一条消息，改代码就得返工。

场景： 头像上传成功了，但重新打开移动应用后，显示的还是旧头像。

较差的 prompt
上传后清掉个人资料页的图片缓存，每次启动应用时重新加载。这样旧头像应该就不会再出现了。
更好的 prompt
上传成功后，重新打开 [版本号] 的应用，显示的还是旧头像。复现步骤和合成测试账号：[详情]。追踪一次上传和紧接着的一次读取：存储的图片版本、个人资料里保存的引用、图片服务返回的内容，以及应用的缓存 key。找出它们从哪一步开始不一致，汇报证据，并提出一个能区分“显示过期”和“保存失败”的检查。不要改代码，也不要清缓存。

原因： 上传成功，不代表个人资料已经指向新图片；先清缓存，会把证据抹掉。参见读懂 ticket。

场景： 订单导出按钮上已批准的英文文案，从“Download”改为“Export CSV”。

较差的 prompt
把应用里所有 Download 字符串都换成 Export CSV，让措辞统一。
更好的 prompt
把订单导出按钮的英文文案从 Download 改成 Export CSV。检查渲染出来的按钮和无障碍名称，汇报 diff 和检查结果。其他无关的下载文案不要动；先不要 commit 或 push。

原因： 较差的 prompt 把一个按钮的改动扩大成了改全部“Download”字符串。小而明确的改动，就说清楚具体改什么、用什么检查来证明，然后直接实现，不需要先出计划。参见实现改动。

改动只限于 ticket 范围

  • agent 看到问题就会顺手修。只让它做 ticket 要求的改动，其他问题请它列在 PR 描述里，由你逐个建 ticket。

场景： 实现 ENG-123 时，你发现订单导出的代码很乱。

较差的 prompt
实现 CSV 导出，顺便把订单导出模块重构一下，helper 也重新命名，让代码干净点。
更好的 prompt
只实现 ENG-123 的 CSV 导出。你建议的重构写进 PR 描述，作为后续事项，并说明理由。不要改无关代码。汇报 diff 和你跑过的检查。

原因： 把功能和重构混在一起的 PR，评审更难，回滚也更难。一个 PR 只做一件事。

先要证据，再接受结果

  • 对照约定的目标，检查输出、测试或实际运行的流程。“做完了”“测试全过了”都只是说法；要它给出命令和输出。
  • 一旦跑偏，尽早指出哪里不对。
  • agent 反复做错时，不要自己动手改代码。补上缺失的上下文、把指令写得更明确，或者写一个会失败的测试，再让 agent 去改。手工改掉会把原因藏起来，下次它还会犯同样的错；反复出现的错误，变成回归检查，或写进仓库说明。
  • 独立评审和人工批准放在代码评审里做。

场景： 一个测试失败，agent 已经试了四种修法，每次都弄坏别的地方。

较差的 prompt
还是失败。再试一次。
更好的 prompt
先停下，别再改了。列出你试过什么、每次尝试说明了什么、你目前的假设，以及能证实或排除这个假设的那一个检查。在我们商定下一步之前，不要改代码。

原因： 没有新证据，再试一次也只是重复同样的猜测。说清假设和对应的检查，才能从瞎猜回到排查。

跟着一个会话从头走到尾

示例ENG-123 · 一个会话，从头到尾
  1. 你发出交付改动的第一个 prompt，带上 ENG-123。
    agent 读完 ticket，给出计划：新建一个导出任务，从请求里取 merchant_id，复用列表的筛选条件。
    检查：商户必须取自当前登录用户，否则任何人都能请求别的商户的订单。
  2. 你回复：“商户从当前登录用户取，不要从请求里取。其余按计划来，实现并附上测试。”
    agent 实现后汇报：所有测试都通过了。
    检查：这时还没什么可查。“都通过了”只是它说的，不是证据。
  3. 你发出验证 prompt。
    agent 逐条给出每个验收标准的证据，还有一处失败：结果为空时返回了错误，而不是只返回表头。
    检查：每一项都写明了命令、输出和对应的 commit。
  4. 你回复：“修好空结果的情况，给我看新测试在修复前失败、修复后通过。”
    agent 给出两次运行结果。
    检查：自己读一遍 diff；评审时你得讲得清楚。
  5. 你让 agent 检查 diff 里有没有意料之外的文件，再按描述模板开 PR。
    检查：描述写清了为什么改、证据，以及还剩下的缺口。

评审照样重要：在代码评审里，一个全新的会话会发现这个会话漏掉的问题。

决定哪些事 agent 可以不问就做

  • 在仓库里读文件、搜索、跑测试、改文件，都可以放手让它做。凡是超出仓库范围的，都要你批准：push、部署、写共享或生产数据库、发消息、安装工具。
  • 不要为了省事改成全部自动批准。命令要是指错了地方，批准提示是你拦下它的最后机会；参见访问、密钥与数据。

每个会话只围绕一个目标

  • 同一个目标，在原对话里接着做；不相关的工作，另开新对话。
  • 交接前，让 agent 记下 ticket、分支、已做的决定、改过的文件、检查情况和下一步。接手的 agent 要对照仓库核实这些内容。
  • 给并行的 agent 分配不同的任务和文件，各用各的 worktree，最后验证合起来的结果。分开对话并不能隔离文件。

按名称运行 skill

  • skill 是 agent 在重复性任务上照着执行的一套固定流程，省得每次都在 prompt 里重写一遍步骤。
  • 本手册用到五个：上手项目时用 project-discovery，代码评审时用 pr-review，部署前用 release-check，每次发布后用 release-closeout，上线或大版本发布前用 ssat-review。
  • 每人装一次就行，之后在任何仓库里都能用，包括客户的仓库。把下面这段贴进 Claude Code 或 Codex；想自己跑命令的话，看安装与更新说明。
Prompt
从公开的 GitHub 仓库 neutronsg/neutron-agent-skills 安装 Neutron 的 agent skill，只装给我这个用户。
- 如果你是 Claude Code，运行：claude plugin marketplace add neutronsg/neutron-agent-skills，然后运行：claude plugin install neutron@neutron
- 如果你是 Codex，运行：codex plugin marketplace add neutronsg/neutron-agent-skills，然后运行：codex plugin add neutron@neutron
如果 Claude Code 因为没有 GitHub SSH key 添加 marketplace 失败，给这条命令设上 CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 再试一次。
装完列出已安装的 plugin，确认 neutron 在里面，并告诉我怎么加载（开一个新会话，或者在 Claude Code 里运行 /reload-plugins）。
不要改动其他任何设置。
  • 在请求前面输入它的名字来启动：Claude Code 里是 /project-discovery，Codex 里是 $neutron:project-discovery。用到 skill 的 prompt 卡片，会按你选的 agent 显示对应命令。

让仓库的 AGENTS.md 真正有用

  • agent 在每个会话开始时读 AGENTS.md；Claude Code 通过下文的 CLAUDE.md 读它。里面写 agent 猜不到的东西：安装、运行和测试的确切命令；代码遵循的约定；文档放在哪里（文档索引）；以及以前让 agent 栽过跟头的坑。
  • 不要写变更记录、计划和 ticket 笔记，也不要写 linter 或测试能强制执行的规则；这些放进检查里。
  • 保持简短、准确。一行过时的内容会误导每一个会话；发布收尾负责让它和代码保持一致。
  • CLAUDE.md 只写一行 @AGENTS.md，让 Claude Code 和 Codex 读同一份说明。

按任务选模型和思考强度

  • 先用各家的通用模型（Opus 5.5、GPT-6.1 Sol）和默认思考强度。范围小、容易检查的工作降一档；出错不容易发现或代价高时升一档。
  • 先提高思考强度，再换最强的模型；两家厂商都建议按这个顺序来。agent 读不到的日志，思考再多也补不回来，所以先补齐缺失的上下文。
  • 评判选得对不对，看验证后的结果，并把重试和返工都算进去，而不是看单次回复的成本或速度。
任务 例子 模型（Claude / OpenAI，2026 年 10 月） 思考强度
范围小、容易检查 改文案、提取字段、交给子 agent 执行的搜索 Haiku 5.5 / GPT-6 Luna low
日常 ticket 验收标准清楚的 ENG-123；有复现步骤的缺陷 Opus 5.5，追求速度时用 Sonnet 5.5 / GPT-6.1 Sol 默认（medium）
难验证或出错代价高 不熟悉的代码、跨系统排查、数据库迁移、并发、资金和奖励的变动、代码评审和安全评审 Opus 5.5 / GPT-6.1 Sol high；评审用 xhigh
长时间自主运行，或用 high 仍未解决 耗时数小时的重构；用 high 没查出原因的事故 Fable 5.1 / GPT-6 Astra xhigh 或 max

来源：Claude 的模型和 effort 文档；OpenAI 的 Codex 模型和推理强度文档。