# 用 AI agent 开发

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

基础 · /zh/agent-development/ · 2026-11-05

## 给出目标，不要给出修法

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

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

**较差的 prompt**

```text
上传后清掉个人资料页的图片缓存，每次启动应用时重新加载。这样旧头像应该就不会再出现了。
```

**更好的 prompt**

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

原因：上传成功，不代表个人资料已经指向新图片；先清缓存，会把证据抹掉。参见[读懂 ticket](/zh/deliver-a-change/#1-understand-the-ticket)。

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

**较差的 prompt**

```text
把应用里所有 Download 字符串都换成 Export CSV，让措辞统一。
```

**更好的 prompt**

```text
把订单导出按钮的英文文案从 Download 改成 Export CSV。检查渲染出来的按钮和无障碍名称，汇报 diff 和检查结果。其他无关的下载文案不要动；先不要 commit 或 push。
```

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

## 改动只限于 ticket 范围

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

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

**较差的 prompt**

```text
实现 CSV 导出，顺便把订单导出模块重构一下，helper 也重新命名，让代码干净点。
```

**更好的 prompt**

```text
只实现 ENG-123 的 CSV 导出。你建议的重构写进 PR 描述，作为后续事项，并说明理由。不要改无关代码。汇报 diff 和你跑过的检查。
```

原因：把功能和重构混在一起的 PR，评审更难，回滚也更难。[一个 PR 只做一件事](/zh/deliver-a-change/#r-pr-1)。

## 先要证据，再接受结果

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

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

**较差的 prompt**

```text
还是失败。再试一次。
```

**更好的 prompt**

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

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

## 跟着一个会话从头走到尾

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

评审照样重要：在[代码评审](/zh/code-review/#2-check-findings-and-fix-defects)里，一个全新的会话会发现这个会话漏掉的问题。

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

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

## 每个会话只围绕一个目标

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

## 按名称运行 skill

- skill 是 agent 在重复性任务上照着执行的一套固定流程，省得每次都在 prompt 里重写一遍步骤。
- 本手册用到五个：上手项目时用 `project-discovery`，代码评审时用 `pr-review`，部署前用 `release-check`，每次发布后用 `release-closeout`，上线或大版本发布前用 `ssat-review`。
- 每人装一次就行，之后在任何仓库里都能用，包括客户的仓库。把下面这段贴进 Claude Code 或 Codex；想自己跑命令的话，看[安装与更新说明](https://github.com/neutronsg/neutron-agent-skills#install)。

**Prompt**

```text
从公开的 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 或测试能强制执行的规则；这些放进检查里。
- 保持简短、准确。一行过时的内容会误导每一个会话；[发布收尾](/zh/release-mgmt/#4-merge-back-and-align-the-docs)负责让它和代码保持一致。
- `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 的[模型](https://platform.claude.com/docs/en/models/overview)和 [effort](https://platform.claude.com/docs/en/build-with-claude/effort) 文档；OpenAI 的 [Codex 模型](https://developers.openai.com/codex/models)和[推理强度](https://developers.openai.com/api/docs/guides/reasoning)文档。

下一步：带着你的第一个 ticket，进入[上手项目](/zh/new-project/)。