AI 编程最佳实践

01AI 写代码走到了哪一步

补全、对话、Agent、再到带工程的 Agent 协作，是一层层叠上来的，到今天四层同时都有人在用，你手上大概率不止一层。这个分法按工程视角来分。

补全和对话今天照样有用。真正变了的是 AI 能接的任务范围越来越大，你要盯的东西跟着往上挪：从「这一句代码写得对不对」，挪到「任务说清楚了没有、上下文给够了没有、跑完怎么验证、改坏了能不能退回去」。

OpenAI 复盘了自己团队怎么用 Codex，Anthropic 写了 Claude Code 的实践建议，两份材料落到工程上是同一件事：把 AI 放进真实代码库和真实流程里，给它清楚的上下文、能动手的任务、跑完之后的反馈。

02一次任务跑完的样子

一句万能提示词解决不了问题。管用的是把每次交付做成一个能自己纠偏的圈，跑五步：

• 说清任务：目标、范围、约束、什么算做完
• 喂上下文：项目规范、现有实现、架构、相关测试
• 规划并动手：拆解、改文件、处理依赖
• 跑验证：测试、构建、类型检查、真打开页面看一眼
• 审 diff 再交付：确认改了哪些、风险在哪、要不要提交

它自己说做完了不算做完。我收的是证据：测试有没有跑过、构建有没有报错、页面点开是什么样、diff 里到底动了哪几行。它写的那段总结我不看。

03八项实践，各解决什么问题

前四项值得单独说，后四项表里那一行就是全部要点。

1. 交给它的是一件事，不是一段代码

区别在于谁在做决定。写代码时你要一行一行盯着；让它做任务时你只管三件事：任务边界画在哪、能动哪些文件不能动哪些、跑完拿什么证明它对了。中间「先读哪个模块、这个函数拆不拆」这类判断交给它。

• 简单任务直接让它动手，别为凑规范先写三份文档
• 复杂任务先要方案：列出要改的文件、打算怎么改、有什么风险，你点过头它再动
• 高风险动作留人工确认：删数据、改权限、动线上配置、发版

2. 别把整个代码库塞进对话框

要的是跟这次任务相关、准确、够用的那几块。少给一块，它就开始瞎猜：

全局规则保持短，能一屏看完；细节等具体任务再喂进去。一个问题反复出现三次以上，才值得写成长期规则塞进项目文件。

3. 规格按任务大小分级，别每次写大文档

一份够用的任务规格就五行：目标（要解决什么）、范围（这次改什么、明确不改什么）、约束（现有架构、兼容性、安全）、验收标准（怎么证明是对的）、验证方式（跑哪些测试或检查）。

4. 验证要跑真的，别让它自己给自己打分

• 后端任务：单元测试 + 接口测试 + 构建通过 + 关键业务场景走一遍
• 前端任务：类型检查和构建之外，要真打开浏览器点一遍，必要时留截图对比
• 改动前先记下现状：当前测试通过数、页面长什么样，改完才有对照
• 验证失败就把完整报错原样贴回去，别只丢一句「失败了」让它自己猜

不用一上来就建完整测试体系，但核心路径至少要有一种能重复跑的验证方式。没有的话，就只能听它说好了。

04两个工具怎么搭配

一个人做东西、维护手上的项目，不用一上来就搭多 Agent 系统。两个角色就够用：

• 一个主执行的：Claude Code 或 Codex 都行，负责读项目、规划、改代码、跑验证、汇总改了什么
• 一个给第二意见的：只在架构选择、难查的 Bug、涉及安全的代码、影响面大的改动上，让另一个工具单独看方案、看 diff、看测试有没有漏

别让两个 Agent 同时改同一批文件，冲突了最后是你收拾。真要并行，先切清边界，各占一个工作目录或分支。

换工具不用换流程：任务怎么定、上下文给什么、怎么验证、谁来审，这四块不变。具体用哪个模型、哪个客户端，看任务类型、成本和当时的能力挑。

05项目里先放哪几样，后放哪几样

先把最小的一套用起来，空目录不用提前占位：

project/
├── AGENTS.md              # 通用 Agent 协作规范
├── CLAUDE.md              # Claude Code 专用补充（按需）
├── README.md              # 项目介绍与启动方式
├── docs/
│   ├── architecture.md    # 架构说明（按需）
│   └── specs/
│       └── feature-x.md   # 中大型需求规格（按需）
├── src/                   # 业务代码
├── tests/                 # 测试代码
├── scripts/
│   └── verify.sh          # 统一验证入口（按需）
└── .github/workflows/
    └── ci.yml             # 持续集成（按需）

• 今天就要有：README.md、一份简短真实的 AGENTS.md、现有代码和测试
• 接到复杂任务再加：需求规格、架构说明、分步计划
• 同一套动作重复到第三遍才自动化：验证脚本、CI、Skills、专门的 Agent 流程

AGENTS.md 和 CLAUDE.md 撞了怎么办通用规则写进 AGENTS.md，CLAUDE.md 只补 Claude Code 自己的那点事。两处重复的规则一定会漂移，定一个为准，另一边写「以 AGENTS.md 为准」。

06一个真实任务怎么交给它

举个手上有项目就能换的例子：在一个已有的后端服务里加设备分页查询接口。把需求、上下文、约束和完成标准写在一起，比一句「帮我写个接口」更容易拿到能审的结果。项目名和字段换成你自己的，直接贴给 Agent。

目标：
新增设备分页查询接口，支持按设备名称和状态筛选。

开始前：
1. 读项目规范和相关模块。
2. 找到现有的分页查询接口，沿用项目已有的写法。
3. 先不要改代码，把方案、要动的文件、潜在风险说一遍。

实现要求：
1. 保持现有分层和接口风格。
2. 明确分页参数、非法参数、空结果这三种情况怎么处理。
3. 不改无关模块，不引入不必要的依赖。

验收标准：
1. 正常查询、条件筛选、空结果、非法参数都有测试覆盖。
2. 相关测试通过，项目能构建起来。
3. 最后列出改了哪些文件、验证跑过什么、还有什么没解决。

执行方式：
方案我确认后再动手；每轮按真实测试结果修，不要凭猜。

这份模板比「帮我写个接口」多出来的是：动手前先要方案、把分页参数和非法参数和空结果这三种情况点名、结尾必须交代还有什么没解决。加上这几条，它自己猜需求的空间就小了一半。

07四个数，从你自己的仓库里查

这套做法有没有起作用，不用靠术语证明。下面四个数都能从自己的仓库和终端里查出来。

指标别造假这些数字要从你自己的项目里来。编一个「效率提升 40%」，被人追问一句怎么量的就露了。说不清就别写数字，改说具体哪件事。

08AGENTS.md 里可以直接抄的那一段

这些规矩与其每次在对话框里重讲一遍，不如写进项目根目录的 AGENTS.md，长期有效的那几条一次写清。下面这段是起点，用不上的行删掉：

# AI 协作规则

## 动手前
- 先读 AGENTS.md 和要改的模块，再给方案：要改哪几个文件、打算怎么改、有什么风险。
- 方案确认后再改代码。改一处文案、明显的小 bug 这类简单任务，可以直接动手。
- 范围只圈本次任务，无关的文件不顺手改。

## 给上下文
- 长期有效的规则写在本文件里，保持一屏能看完；细节按任务临时给。
- 报错给完整日志，不要转述。
- 一个问题反复出现三次以上，才写进本文件成为长期规则。

## 算不算做完
- 看证据：测试通过、构建无报错、类型检查干净；前端改动要真打开页面看过。
- 每轮修改按真实测试结果来，不凭猜。
- 结尾列出：改了哪些文件、跑过哪些验证、还有什么没解决。

## 红线
- 删数据、改权限、动线上配置、发版，这四类动作一律先问人。
- 大范围改动走分支，小步提交，diff 人工看过再合。

09值得继续跟的几份材料

下面这几份都核对过能打开（2026-10-29）。

• How OpenAI Uses Codex to Accelerate Engineering ↗

  真实工程场景里怎么规划任务、怎么写项目指令、怎么迭代

• Claude Code Best Practices ↗

  探索、规划、实现、测试，以及代码库上下文怎么管

• Codex Best Practices ↗

  任务上下文、AGENTS.md、规划、验证和可复用的工作流

• 2026 Agentic Coding Trends Report ↗

  Agent 对开发流程和工程师工作方式的改变（PDF）

工具明年会换一批。任务说清楚、上下文给够、结果能验证、改坏了能退回，这四件事跟用哪个模型、哪个客户端无关。