必须通过AGENTS.md定义规范+Codex扫描+多层验证闭环实现字段命名统一：先在AGENTS.md明确snake_case与camelCase使用场景；再用Codex定位所有违规引用；接着分三阶段迁移（兼容并存→批量替换→清理旧字段）；然后回归检查全链路；最后将映射关系固化为field-mapper Skill。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
当后端把 user_name 改成 userName，前端组件、TypeScript 类型、Mock 数据、测试断言全得同步改，但漏改一个就线上报错。Codex 本身不会自动统一命名，它只按你给的上下文和规则执行——而统一字段命名这件事，必须靠 AGENTS.md 定义规范 + Codex 主动检索 + 多层验证闭环来实现。
第一步：在 AGENTS.md 中明确定义字段命名规则
打开项目根目录，新建或编辑 AGENTS.md 文件，在「代码规范」章节下写入字段命名约束：
```markdown
### 字段命名规范
- 后端 DTO/Entity 字段名使用 snake_case（如：order_status, created_at）
- 前端 TypeScript interface / DTO 使用 camelCase（如：orderStatus, createdAt）
- 所有接口响应字段必须经由 ApiResponse<t></t> 包裹，data 内部结构严格遵循 camelCase
- 禁止在任何地方直接使用 snake_case 字符串字面量（如："user_name"）
```
这一步不做，Codex 后续所有搜索和修改都失去依据——它会按自己训练数据里的常见习惯猜，而不是按你项目的实际契约来。
第二步：让 Codex 扫描全项目，识别违反命名规范的字段引用
在 Codex CLI 或桌面端输入指令：
“请基于 AGENTS.md 的字段命名规范，扫描整个项目，列出所有不符合 camelCase 的前端字段引用位置，包括：TS 接口定义、JSX 模板中 .user_name 形式访问、Mock JSON 里的 key、测试断言中的字符串字面量。”
Codex 会读取当前工作区所有文件，比对规则后输出带路径的违规项列表。注意：它不会直接改代码，只做定位。如果没读到 AGENTS.md，结果里会出现 user_name 和 userName 混用，说明规则未生效。
第三步：生成并执行三阶段字段迁移方案
确认扫描无误后，执行以下三步操作：
① 第一阶段：新增兼容字段
让 Codex 修改后端响应体，同时保留旧字段（snake_case）与新字段（camelCase），例如：{"user_name": "Tom", "userName": "Tom"}
这一步确保旧客户端不崩溃，新前端可立即切到新字段。
通过 codex-reset-radar.pages.dev 监控 Codex 使用重置窗口。轮询 current.json，检测窗口开启/关闭、预测等级变化以及概率跳变。
② 第二阶段：批量替换前端引用
Codex 根据上一步扫描出的路径，自动生成修改命令：sed -i '' 's/user_name/userName/g' src/api/types.ts src/components/UserCard.tsx（macOS）
或 Windows 下用 PowerShell 替换脚本。替换前它会先输出 diff 预览，【务必人工核对每处替换是否在对象解构或属性访问上下文中】，避免把注释或字符串内容误改。
③ 第三阶段：清理旧字段
等所有前端发布完成、监控确认无 user_name 请求后，再让 Codex 删除后端响应中的旧字段，并移除前端残留的兼容逻辑。
第四步：用回归检查锁定字段引用链路
字段变更后，运行回归检查指令：
“请按 AGENTS.md 规范，检查以下层级是否还存在 user_name 引用：API 封装层、TS interface、adapter 解构、Vuex/Pinia state、JSX 模板、单测 expect 断言、E2E 页面断言。”
它会逐层返回命中文件及行号。若某一层（比如报表导出逻辑）未被扫描到，说明该文件未被 Codex 纳入工作区——需手动用 @report/export.ts 引用后再试。
第五步：把字段映射关系固化进 Skill
创建一个名为 field-mapper 的 Skill（注意命名必须符合规范：小写字母+数字+单连字符，64字符内，不以连字符开头结尾）：
→ 在项目根目录新建文件夹 skills/field-mapper
→ 新建 skills/field-mapper/SKILL.md，YAML frontmatter 中 name: field-mapper 必须与文件夹名完全一致
→ 在 skill 内置映射表：user_name → userName、order_status → orderStatus 等
→ 后续每次字段变更，只需更新这个 Skill，Codex 调用时自动按表转换
这一步做完，下次有人提“把 product_category 改成 productCategory”，Codex 就能直接调用 field-mapper 输出完整迁移清单，不用再重复解释规则。
