AI Coding 使用指南

本文档用于沉淀后端团队使用 Codex / AI 编码代理的工作方式。目标不是让 AI 代替工程判断，而是把需求规格化、代码实现、测试、review 和发布检查串成稳定流程。

维护： Codex、模型、CLI 参数、Subagents、Skills、Hooks、Goals、权限策略等能力变化较快。涉及具体功能时，以 OpenAI 官方文档和当前账号实际界面为准；本仓库最后核对日期为 2026-05-26。

核心原则

AI 先做规格化，再做实现。
小步提交，小步验证，避免一次性交给 AI 大范围重写。
业务关键路径必须有人 review，不能只看 AI 自述。
测试、CI、日志、监控和回滚机制是 AI 编码的安全网。
强模型用于需求拆解、架构判断、复杂 review；快模型用于明确范围内的执行。
Subagents 用于并行探索和分项 review，不用于互相覆盖的同一文件改造；子代理会继承当前 sandbox 和审批策略。
高频任务沉淀成 Skills、Hooks、Goals 或脚本，而不是长期依赖口头提示词。

任务规格模板

给 AI 的任务尽量包含以下几块：

目标：

背景：

涉及模块：

不涉及范围：

约束：

验收标准：

需要运行的命令：

输出要求：

示例：

目标：
为 app-server 和 app-manager 的 HTTP 请求增加 traceId 链路。

背景：
项目是单体架构，服务端和管理端分离，公共能力下沉到 framework。

涉及模块：
- framework-web
- app-server
- app-manager

不涉及范围：
- 不调整业务接口返回结构
- 不改数据库结构
- 不引入新的日志平台

约束：
- 如果请求头已有 X-Trace-Id，则复用。
- 如果没有，则生成新的 traceId。
- 响应头返回 X-Trace-Id。
- 日志 MDC 中必须包含 traceId。
- 不记录 token、password、secret。

验收标准：
- 单元测试覆盖 traceId 生成和复用。
- 集成测试验证响应头。
- 现有接口行为不变。

模型分工

模型 / 角色	适合任务
强模型	规格化、架构权衡、复杂 bug 分析、生产风险 review
快模型	小范围实现、补测试、改文档、改配置、脚本调整
`explorer`	只读梳理代码结构、调用链、配置来源
`worker`	按明确规格实现代码、补测试
reviewer	检查业务 bug、事务、并发、边界条件
tester	补测试、找缺失场景、检查测试稳定性
security	检查鉴权、越权、敏感日志、密钥泄露

后端常见任务拆法

新增业务接口

先让 AI 输出规格：

1	接口路径、请求参数、响应结构、错误码、权限、事务边界、数据表影响、缓存影响、测试清单。

再执行：

1	controller -> service -> repository/mapper -> migration -> tests -> docs

修改数据层

必须明确：

是否需要数据库迁移脚本。
是否影响 app-server 和 app-manager。
是否影响共同依赖的 framework。
是否需要回填数据。
是否存在兼容旧数据的问题。
是否需要回滚脚本。

引入 Redis

必须明确：

Redis 用途是缓存、锁、限流、验证码还是会话。
key 命名规则。
TTL 策略。
缓存一致性策略。
穿透、击穿、雪崩处理。
主从延迟或故障时的降级行为。

调用第三方 API

不要让业务代码直接调用第三方。建议通过适配层隔离：

1
2
3

业务 service
  -> ThirdPartyGateway / Client
      -> 第三方 API

适配层负责：

请求参数转换。
签名和 token。
超时、重试、熔断。
第三方错误码转换。
日志脱敏。
幂等号和补偿查询。

测试中默认使用 mock server；少量契约测试或发布前检查使用第三方 sandbox。

Subagents 使用建议

Codex 只在明确要求时启动子代理。使用时要把任务拆成互相独立的读写范围，并在 prompt 中要求“等待所有子代理完成后再汇总”。

适合并行的任务：

explorer A：梳理订单创建链路
explorer B：梳理支付回调链路
tester：列出缺失测试场景
security：检查鉴权和日志脱敏风险
reviewer：检查事务、幂等和并发问题

不适合并行的任务：

多个 worker 同时改同一个文件。
一个任务的下一步强依赖另一个子代理的结果。
没有清晰范围的大重构。
需要频繁人工确认的生产操作、数据库操作或密钥操作。

可沉淀的工作流资产

重复出现的 AI 编码流程，建议按稳定性沉淀：

资产	适合内容	注意事项
`AGENTS.md`	项目约定、测试命令、目录边界、review 规则	不写密钥和频繁变化的临时状态
Skills	重复执行的 review、排障、发布检查、迁移清单	`description` 要写清触发条件和不适用边界
Hooks	提交前检查、敏感信息拦截、格式化、审计日志	会阻断流程，必须可靠且可快速失败
Goals	跨多个 turn 的长期任务目标	目标要可验证，不要写成模糊愿望
`codex exec` 脚本	CI 总结、release notes、批量报告	显式指定 sandbox，避免加载不受控用户配置

测试要求

单元测试关注纯业务规则：

状态流转。
金额、库存、权限判断。
参数校验。
工具类和公共 framework 能力。

集成测试关注真实协作：

controller 到 service 到 DB 的链路。
SQL、分页、排序、事务。
Redis key、TTL、锁和缓存一致性。
权限、token、拦截器。

部署后脚本测试关注上线可用：

健康检查。
版本号。
数据库连接。
Redis 连接。
登录和权限失败场景。
核心读接口。
低风险写入流程。

完成标准

AI 任务完成时，应输出：

改了哪些文件。
解决了什么问题。
跑了哪些命令。
测试是否通过。
哪些地方没有验证。
是否存在迁移、回滚、配置或运维风险。

参考

迭代记录

2026-05-26：按当前 Codex 能力补充 Skills、Hooks、Goals、codex exec 和 Subagents 使用边界；更新维护日期和参考链接。
2026-05-11：初始化 AI Coding 使用指南，整理后端团队使用 Codex / AI 编码代理的规格化、实现、测试、review 和发布检查流程。