四、后端开发场景实战：接口、数据、故障处理
后端为什么更需要“边界清楚”
前端很多返工是视觉和体验问题，后端很多返工直接就是稳定性和事故问题。
比如：
- 接口字段名改了，前端全挂。
- 迁移脚本写错，数据库状态不一致。
- 幂等没考虑，重复请求把数据写乱了。
- 外部依赖慢了，整个链路跟着超时。
这些问题有个共同点：
不是代码不能跑，而是风险太大。
所以后端的 AGENTS.md 不用写很多花样，重点是把高风险规则卡死。
一个很典型的场景
需求：加一个“批量导出订单”的接口。
很多人会觉得这就是写个导出逻辑，开个下载链接。
但现实里很快会遇到这些问题：
- 导出的数据量大，接口不能同步跑完。
- 用户反复点导出，会不会重复创建任务？
- 历史字段兼容怎么保证？
- 导出失败以后怎么追踪？
如果 AGENTS.md 没写相关约束，AI 很容易先给你一个“能跑”的版本，但离上线还差一大截。
后端 AGENTS.md 里最应该先写的内容
1. 接口兼容性
这是后端项目最常见的隐形雷。
建议明确写：
## 接口规则
- 没写兼容性说明，不要直接改公开接口行为
- 能加字段解决的，就不要上来就删旧字段
- 会影响现有调用方的改动，必须先确认
这三条不复杂，但能挡住很多“顺手改字段”的问题。
2. 数据写入规则
尤其是幂等和事务边界。
可以写：
- 可能被重复调用的写接口，要按幂等去设计
- 动数据库结构前，先想好回滚办法
如果不写，AI 往往会默认“写进去就算成功”，不会先想重试和重复请求。
3. 外部依赖规则
这是线上稳定性的基本盘。
- 调外部服务必须带超时
- 要不要重试、怎么重试，要写明白
- 失败要能在日志或监控里看见
4. 缺陷修复规则
这一条很适合直接写死：
- 线上事故修复必须补回归测试
别嫌它硬，这条在后端尤其值。
一个更完整的后端版示例
# AGENTS.md## 作用范围
- services/api 是主 HTTP 服务
- db/migrations 放数据库变更## 必跑命令
- make lint
- make test## 接口规则
- 能兼容就尽量兼容，不要顺手改掉老行为
- 会影响调用方的改动，要先确认并写清说明## 数据规则
- 可能重复触发的写路径要考虑幂等
- 迁移脚本要把回滚思路想清楚## 风险边界
- 动鉴权、计费、基础设施配置前先确认
- 不要直接跑破坏性数据库脚本## 最终汇报
- 先说行为有没有变化
- 再说怎么验证的
- 最后说剩余的运行风险
一个实打实的“坏例子”
下面这种实现，很多时候 AI 会给出来，而且代码表面看没毛病：
public async Task<string> CreateExportJobAsync(ExportQuery query)
{var job = new ExportJob { Query = query, Status = "Pending" };_db.ExportJobs.Add(job);await _db.SaveChangesAsync();return job.Id;
}
这段代码的问题是：
- 没考虑重复请求。
- 没考虑异步任务投递失败。
- 没有任何可观测信息。
- 没交代任务状态流转。
如果 AGENTS.md 里已经强调“写路径幂等、外部依赖可观测、行为变化要解释”，AI 至少会更容易往正确方向靠。
一个更稳一点的方向
public async Task<string> CreateExportJobAsync(string userId, ExportQuery query, CancellationToken ct)
{var existing = await _repository.FindPendingByUserAndRangeAsync(userId, query, ct);if (existing is not null)return existing.Id;var job = ExportJob.Create(userId, query);await _repository.SaveAsync(job, ct);await _queue.PublishAsync(new ExportRequested(job.Id), ct);return job.Id;
}
这段也不是说一定就完美了，但至少思路上已经更像线上代码：
- 先查是否已有任务。
- 保存任务和投递动作分清楚。
- 行为边界更容易解释。
后端规则为什么更适合写“硬规则”
前端有些规则还能留一点弹性，比如页面风格、布局方式。
后端很多地方不太适合模糊表达。
比如：
坏写法：
请注意数据安全。
好写法：
- 没明确确认之前，不要改鉴权逻辑
- 只要涉及 schema 变更，迁移脚本就要额外过一遍
- 新写入链路要把幂等预期写清楚
后者是能落地的，前者只是态度。
后端最容易漏写的一块：故障处理口径
很多团队写了测试、写了兼容、写了幂等，但忘了定义“失败以后怎么办”。
我很建议至少补上这类规则：
- 异步流程要返回可追踪的请求号或任务号
- 外部依赖失败不能静默吞掉
- 做不到完全成功时，要把降级行为说明白
因为后端问题最怕“失败了，但没人知道失败在哪”。
什么时候要给后端子目录单独放 AGENTS.md
如果仓库里这些内容差异明显，就很值得拆：
- API 服务和异步 worker 在同仓库。
- 应用代码和基础设施代码混在一起。
- 迁移脚本、运维脚本、业务代码规则完全不同。
拆分以后会更清楚：
- 根目录：通用风险边界。
services/api/AGENTS.md：接口和行为规则。workers/AGENTS.md：异步任务和重试策略。db/AGENTS.md：迁移和数据规则。
如何判断一条后端规则值不值得写进 AGENTS.md
我一般只看两个问题：
- 这事出错会不会贵？
- 这事是不是已经在 review 里重复出现？
如果两个答案都是“会”，那就很值得写。
比如：
- 幂等
- 兼容性
- 迁移回滚
- 权限变更
- 外部依赖超时
这些都属于典型高价值规则。
小结
后端场景里的 AGENTS.md，不需要追求写得很花，重点就是把那些“出了问题代价很高”的地方说死。
接口兼容、幂等、迁移、依赖超时、回归测试，这几类只要先写清楚，很多低级事故就能提前避开。