Codex 工程化落地指南 04：AGENTS.md 项目规则体系——根目录规则、子目录规则与覆盖规则

码东

189人浏览 · 2026-07-24 15:20:21

码东 · 2026-07-24 15:20:21 发布

一：教程定位🎯

前一篇教程完成了 Codex 对现有 Git 仓库的接入分析。

Codex 已经能够识别：

项目技术栈目录结构启动命令测试命令数据库配置已有业务模块

但“理解项目”并不代表“知道应该如何修改项目”。

如果没有长期规则，每次开发都需要重复告诉 Codex：

⚠️ 注意： 不要直接修改 main 每个功能都创建独立分支后端业务逻辑放在 Service 数据库变更必须新增迁移前端不能硬编码接口地址测试失败不能提交允许 Commit 和 Push 禁止 Force Push 不要提交 .env 和密钥

一旦遗漏其中某项，Codex 可能：

⚠️ 注意： 在错误分支修改代码使用不同的编码风格绕过项目现有架构把业务逻辑写进 Controller 修改已经发布的历史迁移提交无关文件跳过失败测试执行危险 Git 命令

AGENTS.md 的作用，就是把这些长期约束放进仓库，形成 Codex 每次进入项目时都能读取的开发规则。

本篇将建立一套三级规则体系：

根目录 AGENTS.md ↓ 子目录 AGENTS.md ↓ AGENTS.override.md

并统一管理：

项目背景技术架构目录边界编码规范分支规范测试要求 Commit 与 Push 数据库规则安全规则禁止事项任务完成报告

二：教程信息📌

目标读者：Codex 中级使用者、项目负责人、DevOps 工程师预计时长：约 2 小时难度等级：★★☆ 案例项目：城市随手拍平台

三：学习目标📌

完成本篇后，你应该能够：

理解 AGENTS.md 的作用范围理解根目录与子目录规则的关系理解规则冲突时的优先级创建项目根目录 AGENTS.md 为后端、前端和数据库建立独立规则使用 AGENTS.override.md 做临时或局部覆盖统一分支、Commit 和 Push 规则统一测试和构建要求限制 Codex 的危险操作验证 Codex 是否正确读取规则维护规则版本和审查流程

第一部分：理解 AGENTS.md

四：AGENTS.md 是什么📖

AGENTS.md 是提供给 Codex 的项目工作说明。

它可以告诉 Codex：

项目是做什么的代码放在哪里使用什么架构如何安装依赖如何启动项目如何执行测试哪些目录可以修改哪些目录禁止修改使用什么分支命名是否允许 Commit 和 Push 任务完成后如何汇报

可以把它理解为：

面向编码 Agent 的项目开发手册

它与 README.md 的用途不同。

README.md 面向人类使用者

通常包含：

项目介绍安装方式启动方式部署说明接口文档入口

AGENTS.md 面向编码 Agent

通常包含：

修改边界工程约束测试要求 Git 工作流禁止操作完成报告格式

两者可以共享部分信息，但不应该完全重复。

五：为什么不能只靠任务提示词💡

单次提示词适合描述：

本次要开发什么功能本次允许修改哪些模块本次验收标准是什么

AGENTS.md 适合保存：

所有任务长期遵守的规则

例如：

所有新功能分支都使用 fea-{功能简介拼音}

这项规则不应该在每一个功能提示词中重复几十次。

推荐结构：

AGENTS.md：长期工程规则

本次任务提示词：当前功能要求

两者结合：

长期规则 + 当前任务

完整开发约束

第二部分：规则加载与作用范围

六：根目录规则🔍

仓库根目录：

city-snapshot-platform/ ├── AGENTS.md ├── server/ ├── citizen-h5/ ├── admin-web/ └── database/

根目录的 AGENTS.md 对整个项目生效。

适合写：

项目目标全局业务约束 Git 分支规范 Commit 规范测试总原则安全规则禁止事项完成报告

不适合在根目录详细写：

某个 Vue 组件的命名方式某张数据库表的字段约束某个 Java 包的特殊规则

这些更适合放在对应子目录。

七：子目录规则📂

可以在子目录继续创建：

city-snapshot-platform/ ├── AGENTS.md ├── server/ │ └── AGENTS.md ├── citizen-h5/ │ └── AGENTS.md ├── admin-web/ │ └── AGENTS.md └── database/ └── AGENTS.md

当 Codex 修改：

server/src/modules/issue/issue.service.ts

需要同时遵守：

根目录 AGENTS.md server/AGENTS.md

当 Codex 修改：

citizen-h5/src/pages/report/index.vue

需要遵守：

根目录 AGENTS.md citizen-h5/AGENTS.md

子目录规则用于补充更具体的技术规范。

八：更深层规则🗂️

大型项目可以继续细分：

server/ ├── AGENTS.md ├── src/ │ ├── modules/ │ │ ├── issue/ │ │ │ └── AGENTS.md │ │ └── user/ │ └── common/ └── tests/

例如：

server/AGENTS.md：后端通用架构

server/src/modules/issue/AGENTS.md：事项模块状态机和事务规则

规则不要拆得过细。

不建议为每个普通目录都创建一个文件：

controllers/AGENTS.md services/AGENTS.md dto/AGENTS.md entities/AGENTS.md

过多规则会增加：

维护成本冲突概率上下文长度理解难度

九：规则冲突优先级🔀

可以按照以下方式理解：

当前任务直接要求

更深层目录规则

上层目录规则

用户级通用规则

例如根目录写：

所有前端文件使用 2 个空格缩进。

某个旧版后台子目录写：

本目录历史代码统一使用 4 个空格，不做全量格式化。

当修改旧版后台目录时，应遵守更具体的子目录要求。

但是如果当前任务明确要求：

本次只分析，不修改任何文件。

即使 AGENTS.md 允许自动修改和提交，也不能修改文件。

第三部分：AGENTS.override.md

十：什么是覆盖规则🔄

AGENTS.override.md 用于覆盖同一位置的常规规则。

典型场景：

临时迁移特殊实验目录历史遗留模块紧急修复工作区个人本地调试

例如：

server/legacy/ ├── AGENTS.md └── AGENTS.override.md

覆盖规则可以写：

# Temporary migration rules

- 本目录正在执行框架迁移。
- 暂停新增业务功能。
- 只允许修改迁移清单中的文件。
- 禁止执行全量格式化。
- 禁止升级数据库依赖。
- 每次修改后只运行 legacy 模块测试。

十一：不要滥用 override🛡️

不建议把长期规则全部写进：

AGENTS.override.md

推荐：

长期规则： AGENTS.md

临时覆盖： AGENTS.override.md

临时任务结束后，应评估：

删除覆盖文件或将有效规则合并回正式 AGENTS.md

覆盖文件长期存在却没人维护，容易造成：

新成员不知道为什么规则不同正常规则长期失效临时例外变成永久例外

第四部分：设计 AGENTS.md 的原则

十二：规则必须可执行📋

差的规则：

写高质量代码。

问题：

无法验证没有明确行为不同人理解不同

更好的规则：

✅ 推荐： 新增后端接口必须包含参数校验，并补充至少一个成功场景和一个失败场景测试。

十三：规则必须基于真实项目✅

不要直接复制其他项目模板。

例如项目实际使用：

PNPM Vitest Prisma Vue 3 NestJS

就不要写：

运行 npm test 使用 Jest 使用 TypeORM

所有命令必须从真实仓库确认。

十四：规则保持简洁🔧

不要把整个架构文档复制进 AGENTS.md。

推荐写：

项目架构详见 docs/architecture.md。修改跨模块公共接口前必须先阅读该文档。

而不是把几十页架构说明全部粘贴进去。

根目录规则建议控制在：

100～250 行

子目录规则建议控制在：

30～120 行

这不是硬性限制，而是便于维护的工程建议。

十五：规则不要重复📝

根目录已经写：

⚠️ 注意： 禁止 Force Push。

子目录无需再次重复。

子目录只写差异：

本目录测试命令为 pnpm test:api。

重复规则会增加：

上下文浪费维护遗漏内容不一致

十六：规则要说明失败时如何处理📝

不要只写：

✅ 推荐： 必须运行测试。

更完整：

测试失败时先分析失败是否由本次修改引起。不得删除、跳过或屏蔽失败测试。无法修复时停止提交，并在完成报告中说明失败命令、退出码和原因。

第五部分：项目规则目录设计

十七：案例仓库结构🚀

city-snapshot-platform/ ├── AGENTS.md ├── docs/ ├── server/ │ ├── AGENTS.md │ ├── src/ │ └── tests/ ├── citizen-h5/ │ ├── AGENTS.md │ └── src/ ├── admin-web/ │ ├── AGENTS.md │ └── src/ ├── database/ │ ├── AGENTS.md │ ├── migrations/ │ └── seeds/ └── deployment/ └── AGENTS.md

规则职责：

文件	主要内容
根目录 AGENTS.md	全局业务、Git、测试、安全
server/AGENTS.md	后端架构、接口、事务、测试
citizen-h5/AGENTS.md	H5 页面、移动端、上传、地图
admin-web/AGENTS.md	管理端、权限、表格和表单
database/AGENTS.md	迁移、索引、回滚和数据安全
deployment/AGENTS.md	Docker、Kubernetes 和生产限制

第六部分：根目录 AGENTS.md 完整模板

十八：创建文件💬

在仓库根目录执行：

cd ~/projects/city-snapshot-platform
touch AGENTS.md

十九：根目录模板✅

# AGENTS.md

## 1. 项目概述

本项目为“城市随手拍平台”。

平台角色：

1. 市民用户
2. 平台管理员
3. 处置部门人员

核心业务流程：

市民上报
→ 管理员审核
→ 管理员派发
→ 部门接收或退回
→ 部门处理
→ 管理员跟踪
→ 事项办结
→ 市民查看结果

## 2. 固定业务约束

- 市民端采用 H5。
- 不开发微信小程序。
- 不开发原生 APP。
- 手机号注册不发送短信验证码。
- 手机号只校验格式和唯一性。
- 单个事项最多上传 5 张图片。
- 不支持上传视频。
- 地图服务使用百度地图。
- 支持自动定位。
- 支持手动地图选点。
- 定位地址允许用户修改。
- 事项类型由后台字典配置。
- 事项由平台管理员手动派发。
- 一个事项不能同时派发给多个部门。

## 3. 仓库结构

- `server/`：后端 API。
- `citizen-h5/`：市民 H5。
- `admin-web/`：管理端 Web。
- `database/`：数据库迁移和种子数据。
- `deployment/`：Docker、Kubernetes 和部署配置。
- `docs/`：需求、架构和开发文档。

不要在仓库根目录直接创建业务源代码。

## 4. 任务执行流程

接到开发任务后：

1. 阅读当前任务。
2. 阅读当前目录生效的 AGENTS.md。
3. 执行 `git status --short --branch`。
4. 阅读相关现有代码和测试。
5. 输出影响范围和实施计划。
6. 复杂任务先计划，后编码。
7. 每次只完成一个可验证阶段。
8. 修改完成后运行相关测试。
9. 检查 `git diff`。
10. 测试通过后才能 Commit 和 Push。

如果当前任务明确要求只分析，则不得修改文件。

## 5. Git 分支规范

每个新功能必须创建独立分支。

分支格式：

`fea-{功能简介拼音}`

示例：

- `fea-yonghuzhuce`
- `fea-shixiangshangbao`
- `fea-dituxuandian`
- `fea-shixiangpaifa`
- `fea-bumenchuzhi`

禁止直接在以下分支开发：

- `main`
- `master`
- `develop`

开始新功能前：

```
bash
git status --short --branch
git switch main
git pull --ff-only
git switch -c fea-{功能简介拼音}

如果工作区存在用户未提交修改，不得切换分支、清理或覆盖，先报告状态。

6. Commit 规范

使用 Conventional Commits：

feat: 新功能
fix: Bug 修复
refactor: 重构
test: 测试
docs: 文档
chore: 工程配置
build: 构建系统
ci: CI/CD 配置

示例：

text
feat: add citizen issue submission
fix: prevent duplicate issue assignment
test: add mobile registration validation cases

一个 Commit 只包含一个逻辑变更。

禁止把以下内容混入功能 Commit：

无关格式化
临时调试代码
本地环境配置
无关锁文件变化
其他功能代码

7. Push 规则

允许 Codex 自动执行：

git add
git commit
git push

但必须满足：

当前分支不是受保护分支。
相关测试已通过。
已执行 git diff。
没有无关修改。
没有 Secret。
Commit message 合规。

禁止：

git push --force
git push --force-with-lease
自动合并到 main
自动删除远程分支
修改或覆盖他人 Commit

首次 Push 使用：

bash
git push -u origin 当前功能分支

8. 测试总原则

修改代码后，根据受影响模块运行真实命令。

至少检查：

Lint
类型检查
单元测试
构建

不得根据经验虚构测试结果。

报告必须包含：

实际命令
退出码
通过数量
失败数量
未执行原因

如果命令不存在：

检查项目配置。
检查 README 和 CI。
使用项目真实命令。
不得假装已执行。

测试失败时：

不得删除失败测试。
不得跳过失败用例。
不得降低断言。
不得屏蔽错误后提交。
无法修复时停止 Commit。

9. 依赖管理

新增生产依赖前必须说明：

新依赖解决什么问题。
项目现有依赖为何无法满足。
是否有更轻量的实现。
依赖许可证和维护状态。
对构建体积的影响。

禁止：

为简单功能引入大型框架。
未经说明升级所有依赖。
删除锁文件重新生成。
混用 npm、pnpm 和 yarn。

10. 安全规则

禁止读取、输出、提交或记录：

.env
API Token
密码
SSH 私钥
云平台密钥
数据库生产凭证
Kubeconfig
TLS 私钥

只允许读取：

.env.example
配置项名称
不包含真实值的示例文件

禁止在日志中打印 Secret。

11. 高风险操作

未经当前任务明确授权，不得执行：

生产部署
生产数据库迁移
删除数据库或表
清理生产数据
修改云资源
修改 DNS
修改生产 Secret
执行 git reset --hard
执行 git clean -fd
执行 Force Push
批量删除文件

12. 修改边界

优先修改与当前任务直接相关的文件。
不为了“顺便优化”重构无关模块。
不修改公共接口，除非任务明确要求。
不删除暂时无法理解的历史逻辑。
不全量格式化仓库。
不修改用户未提交的代码。

13. 文档要求

发生以下变化时更新对应文档：

新增公共接口
修改环境变量
修改数据库结构
修改部署方式
修改业务状态机
修改开发命令

文档变更应与对应代码保持一致。

14. 完成报告

任务完成后输出：

完成内容。
修改文件。
数据库变化。
API 变化。
配置变化。
测试命令和结果。
未完成事项。
风险和注意事项。
当前分支。
Commit ID。
Push 状态。
工作区是否干净。

`

---

# 第七部分：后端子目录规则

## 二十：`server/AGENTS.md`📝


```markdown
# Backend AGENTS.md

本文件适用于 `server/` 及其子目录。

同时遵守仓库根目录 AGENTS.md。

## 1. 架构边界

- Controller 负责接收参数、调用 Service 和返回结果。
- 业务逻辑放在 Service。
- 数据访问放在 Repository、DAO 或 Mapper。
- DTO 负责输入校验。
- Entity 不承载复杂业务流程。
- 公共异常使用项目统一异常体系。
- 公共响应使用项目统一响应结构。

禁止：

- 在 Controller 中直接操作数据库。
- 在 DTO 中访问外部服务。
- 在 Repository 中实现业务状态机。
- 为单个功能创建第二套响应格式。

## 2. 接口规范

新增或修改接口时检查：

- HTTP 方法
- 路径
- 请求参数
- 参数校验
- 权限
- 错误码
- 幂等性
- 事务
- 日志
- 测试

不得静默改变已有接口字段含义。

## 3. 业务事务

以下操作应评估事务：

- 事项创建与图片关联
- 事项派发与状态变更
- 部门接收与操作记录
- 事项办结与反馈
- 用户创建与角色关联

事务中不要执行耗时外部网络调用。

## 4. 权限

- 市民只能访问自己的事项。
- 平台管理员负责审核和派发。
- 部门人员只能处理分配给本部门的事项。
- 后端必须进行权限校验，不能只依赖前端隐藏按钮。

## 5. 测试

新增接口至少包含：

- 一个成功场景
- 一个参数错误场景
- 一个业务失败场景
- 涉及权限时增加越权场景

修改 Service 时优先补充 Service 单元测试。

## 6. 命令

以项目真实配置为准，常用验证顺序：

bash pnpm --filter server lint pnpm --filter server typecheck pnpm --filter server test pnpm --filter server build


如果仓库实际命令不同，先检查 `server/package.json`。

```
`

---

# 第八部分：市民 H5 子目录规则

## 二十一：`citizen-h5/AGENTS.md`🗂️


```markdown
# Citizen H5 AGENTS.md

本文件适用于 `citizen-h5/` 及其子目录。

同时遵守仓库根目录 AGENTS.md。

## 1. 产品形态

- 当前客户端是 H5。
- 不生成微信小程序代码。
- 不使用小程序专有 API。
- 不开发原生 APP 逻辑。

## 2. 页面规范

- 页面组件和通用业务组件分离。
- API 请求集中管理。
- 不在页面中硬编码后端地址。
- 表单必须包含校验和错误提示。
- 页面必须适配常见移动端宽度。
- 关键操作必须提供加载和失败状态。

## 3. 事项上报

- 最多上传 5 张图片。
- 不支持视频上传。
- 图片上传失败时允许重试。
- 提交前必须校验事项类型、地址和描述。
- 防止用户重复点击导致重复提交。

## 4. 地图

- 使用百度地图。
- 支持自动定位。
- 支持手动选点。
- 允许用户修改解析后的地址。
- 坐标和地址必须分别保存。
- 不将地图密钥硬编码到源码。

## 5. API 和类型

- 请求和响应类型集中定义。
- 不使用 `any` 绕过明确类型错误。
- 接口字段变更时同步更新类型和调用页面。
- 不在多个页面重复定义同一接口类型。

## 6. 测试

涉及表单时测试：

- 必填项
- 图片数量限制
- 提交成功
- 提交失败
- 防重复提交

涉及地图时测试：

- 定位成功
- 定位失败
- 手动选点
- 地址修改
```
`

---

# 第九部分：管理端子目录规则

## 二十二：`admin-web/AGENTS.md`🗂️


```markdown
# Admin Web AGENTS.md

本文件适用于 `admin-web/` 及其子目录。

同时遵守仓库根目录 AGENTS.md。

## 1. 权限原则

- 路由权限和后端权限必须同时存在。
- 隐藏按钮不能替代后端权限校验。
- 不使用前端本地变量伪造管理员身份。
- 新权限点必须使用项目现有权限体系。

## 2. 页面规范

- 列表页统一使用现有分页组件。
- 搜索条件必须能够重置。
- 表格加载、空状态和错误状态必须完整。
- 状态字段使用统一字典。
- 不在页面中硬编码事项类型和部门数据。

## 3. 事项派发

- 只能选择一个处置部门。
- 派发前显示事项和部门确认信息。
- 派发成功后刷新事项状态和操作记录。
- 禁止通过前端绕过事项状态限制。

## 4. 表单

- 保存期间禁用重复提交。
- 后端错误必须展示可理解信息。
- 编辑页面需要处理数据加载失败。
- 不用 mock 数据替代真实接口交付。

## 5. 测试

新增管理页面至少验证：

- 页面加载
- 权限控制
- 搜索
- 分页
- 成功操作
- 失败提示
```


---

# 第十部分：数据库规则

## 二十三：`database/AGENTS.md`🗂️


```markdown
# Database AGENTS.md

本文件适用于 `database/` 及其子目录。

同时遵守仓库根目录 AGENTS.md。

## 1. 迁移原则

- 所有结构变更必须新增迁移文件。
- 禁止修改已经合并或发布的历史迁移。
- 每个迁移只包含一个清晰主题。
- 迁移文件名遵守项目现有规范。
- 迁移应评估回滚方式。

## 2. 数据安全

未经明确授权不得：

- 连接生产数据库
- 执行生产迁移
- 删除表
- 删除字段
- 批量删除数据
- 清空数据库
- 重置迁移历史

执行迁移前必须确认连接目标为本地或专用测试数据库。

## 3. 字段设计

新增字段时评估：

- 是否允许 NULL
- 默认值
- 索引
- 唯一约束
- 外键
- 历史数据兼容
- 回滚影响

## 4. 索引

为以下查询评估索引：

- 手机号唯一查询
- 事项编号查询
- 用户事项列表
- 事项状态筛选
- 部门待办事项
- 创建时间范围查询

不得无依据为每个字段创建索引。

## 5. 种子数据

- 种子数据必须可重复执行或明确说明非幂等。
- 不在种子文件中保存真实用户密码。
- 默认账号仅用于本地开发。
- 生产初始化数据需要独立审批。

## 6. 验证

数据库变更至少验证：

- 迁移成功
- 新表或字段存在
- 约束生效
- 应用测试通过
- 回滚方案可执行或已说明限制
```


---

# 第十一部分：部署目录规则

## 二十四：`deployment/AGENTS.md`🗂️


````markdown
# Deployment AGENTS.md

本文件适用于 `deployment/` 及其子目录。

同时遵守仓库根目录 AGENTS.md。

## 1. 镜像

- 生产镜像禁止使用 `latest`。
- 镜像 Tag 必须可追溯到 Commit 或版本。
- 基础镜像优先使用企业 Harbor。
- 不将仓库凭证写入 Dockerfile。

## 2. 配置

- Secret 不提交 Git。
- 配置文件只保存非敏感默认值。
- 环境差异通过环境变量或独立 values 文件管理。
- 修改环境变量时更新 `.env.example` 和文档。

## 3. Kubernetes

- Deployment 必须配置 readinessProbe。
- 生产工作负载必须配置 resources。
- 不在 Manifest 中写明文密码。
- 不自动执行生产部署。

## 4. Docker Compose

- 发布前运行 `docker compose config`。
- 不执行 `docker compose down -v`。
- 不删除持久化数据卷。
- 生产使用固定镜像 Tag。

## 5. 验证

部署配置变更后，根据类型执行：

```
bash
docker compose config
helm lint
helm template
kubectl apply --dry-run=client

只运行仓库中实际适用的命令。

`

---

# 第十二部分：如何生成 AGENTS.md

## 二十五：先让 Codex 分析仓库🔍

不要直接让 Codex凭空生成规则。

推荐提示词：


> ⚠️ **注意：** 请基于当前仓库生成 AGENTS.md 规划，但先不要写文件。
> 
> 请分析：
> 
> 1. 仓库目录结构。
> 2. 技术栈。
> 3. 包管理器。
> 4. 真实测试命令。
> 5. 数据库和迁移工具。
> 6. 现有 Git 规范。
> 7. CI 中执行的质量命令。
> 8. 各子项目的差异。
> 
> 然后给出：
> 
> - 根目录规则应该包含什么
> - 哪些子目录需要独立 AGENTS.md
> - 哪些目录不需要
> - 可能发生的规则冲突
> - 需要项目负责人确认的事项
`

---

## 二十六：生成规则草案✍️

确认规划后：


> 请根据确认后的规划生成以下规则草案：
> 
> - AGENTS.md
> - server/AGENTS.md
> - citizen-h5/AGENTS.md
> - admin-web/AGENTS.md
> - database/AGENTS.md
> - deployment/AGENTS.md
> 
> 要求：
> 
> 1. 所有命令必须来自项目真实配置。
> 2. 不编造不存在的目录。
> 3. 不重复父级规则。
> 4. 子目录只写差异规则。
> 5. 暂时不要修改业务代码。
> 6. 暂时不要 Commit。
> 7. 完成后输出规则冲突检查结果。


---

# 第十三部分：验证规则是否生效

## 二十七：验证根目录规则✅

在仓库根目录启动 Codex：


```bash
codex

输入：

请只总结当前目录生效的项目规则，不修改文件。

请重点说明：

新功能分支命名。

是否允许自动 Commit。

是否允许自动 Push。

测试失败时如何处理。

哪些 Git 命令被禁止。

Secret 如何处理。

任务完成报告包含什么。

预期：

分支使用 fea-{功能简介拼音} 允许测试通过后 Commit 和 Push 禁止 Force Push 测试失败不得提交禁止读取和提交 Secret

二十八：验证后端规则✅

进入：

cd server
codex

输入：

请说明当前目录中生效的全部规则，并区分：

从根目录继承的规则。

server/AGENTS.md 增加的规则。

如果修改 Controller，需要遵守什么。

如果新增接口，需要运行什么测试。

应同时看到全局和后端规则。

二十九：验证前端规则✅

进入：

cd citizen-h5
codex

询问：

如果实现事项上报页面，请列出当前生效的规则。

重点回答：

客户端形态。

图片数量。

是否允许视频。

地图服务。

地址是否允许修改。

测试要求。

三十：验证冲突✅

可以暂时在测试目录创建：

sandbox-rule-test/ ├── AGENTS.md └── child/ └── AGENTS.md

父规则：

- 测试文件使用 `.test.ts`。

子规则：

- 本目录沿用历史规范，测试文件使用 `.spec.ts`。

在 child/ 中询问 Codex：

✅ 推荐： 本目录新增测试文件应该使用什么后缀？说明规则来源。

预期使用更具体的：

.spec.ts

验证完成后删除测试目录。

第十四部分：规则质量检查

三十一：规则检查清单🔍

每个 AGENTS.md 都检查：

是否包含真实命令是否存在过时目录是否与 CI 冲突是否与 README 冲突是否重复父级规则是否包含无法验证的口号是否包含 Secret 是否过长是否有模糊词是否说明失败处理

三十二：模糊词替换🔍

不推荐：

尽量写测试。

推荐：

新增接口至少补充一个成功场景和一个失败场景测试。

不推荐：

注意代码质量。

推荐：

✅ 推荐： 修改完成后必须运行 Lint、类型检查、相关测试和构建。

不推荐：

⚠️ 注意： 不要随便改数据库。

推荐：

⚠️ 注意： 禁止修改已发布迁移；结构变化必须新增迁移文件。

第十五部分：常见错误

三十三：把需求文档全部复制进去⚠️

问题：

文件过长 Codex 上下文被大量业务描述占用规则难以维护需求变化后容易过时

正确做法：

AGENTS.md 保存关键约束完整需求放 docs/requirements.md

三十四：写入错误测试命令⚠️

例如项目使用 PNPM，却写：

npm test

后果：

安装第二套依赖生成新的 package-lock.json 测试结果不一致

所有命令必须从：

package.json Makefile CI 项目文档

交叉确认。

三十五：规则互相矛盾⚠️

根目录写：

允许自动 Push。

子目录写：

⚠️ 注意： 任何情况下禁止 Push。

如果这不是有意差异，应及时统一。

规则冲突应有清晰业务原因。

三十六：把权限控制误认为 AGENTS.md 能强制执行⚠️

AGENTS.md 是行为指令，不是操作系统安全边界。

它不能替代：

Git 保护分支文件权限沙箱审批策略云 IAM Secret 管理 CI 质量门

例如即使规则写：

⚠️ 注意： 禁止访问生产环境。

仍然不应把生产管理员凭证提供给普通开发任务。

三十七：把 Secret 写进规则🚫

禁止：

数据库密码：123456
Harbor Token：xxxx

规则中只写：

凭证通过 Secret Manager 提供禁止打印和提交真实值

三十八：规则太多导致 Agent 行动僵化⚠️

不要把所有操作都写成：

✅ 推荐： 每一步都必须等待确认。

这样会导致简单任务也频繁中断。

推荐区分：

可直接执行

读取项目文件运行项目已有测试修改当前工作区文件查看 Git Diff

需要明确授权

生产部署生产迁移删除数据 Force Push 修改云资源

第十六部分：维护和版本管理

三十九：AGENTS.md 必须进入 Git📦

规则文件应提交到仓库：

git add AGENTS.md
git add server/AGENTS.md
git add citizen-h5/AGENTS.md
git add admin-web/AGENTS.md
git add database/AGENTS.md
git add deployment/AGENTS.md

建议 Commit：

docs: add Codex project development rules

也可以使用：

chore: add repository agent instructions

四十：规则修改需要审查🔍

规则会影响后续所有 Agent 任务，因此修改时应像代码一样 Review。

重点检查：

是否扩大了自动操作权限是否降低测试要求是否允许高风险 Git 操作是否改变分支策略是否引入错误命令是否误删安全限制

生产团队可为规则文件配置 CODEOWNERS：

/AGENTS.md @platform-team @tech-leads /server/AGENTS.md @backend-leads /citizen-h5/AGENTS.md @frontend-leads /admin-web/AGENTS.md @frontend-leads /database/AGENTS.md @dba-team @backend-leads /deployment/AGENTS.md @platform-team

四十一：定期校验🔄

建议在以下情况检查规则：

技术栈升级包管理器变化测试命令变化目录结构调整数据库工具更换 CI/CD 调整分支策略变化安全事故后

至少每季度检查一次，或随架构变更同步更新。

第十七部分：两小时实操安排

四十二：0～20 分钟：分析仓库⏱️

让 Codex 输出：

目录结构技术栈真实命令子项目差异现有 Git 规范

不写文件。

四十三：20～40 分钟：设计规则层级⏱️

确定：

根目录规则后端规则 H5 规则管理端规则数据库规则部署规则

删除不必要的规则层。

四十四：40～80 分钟：生成规则⏱️

创建：

AGENTS.md server/AGENTS.md citizen-h5/AGENTS.md admin-web/AGENTS.md database/AGENTS.md deployment/AGENTS.md

重点核对真实命令和目录。

四十五：80～100 分钟：验证规则⏱️

分别在：

项目根目录 server/ citizen-h5/ database/

启动 Codex，要求复述生效规则。

四十六：100～115 分钟：模拟任务⏱️

模拟后端任务：

请计划新增手机号注册接口，不修改代码。

根据当前规则说明：

应创建什么分支。

允许修改哪些层。

必须添加哪些测试。

是否允许 Commit 和 Push。

哪些操作被禁止。

模拟数据库任务：

请计划为事项表增加受理时间字段，不修改文件。

根据当前规则说明：

是否可以修改历史迁移。

应如何新增迁移。

需要评估哪些索引。

执行迁移前要确认什么。

四十七：115～120 分钟：提交规则⏱️

检查：

git status
git diff --stat
git diff -- AGENTS.md server/AGENTS.md citizen-h5/AGENTS.md admin-web/AGENTS.md database/AGENTS.md deployment/AGENTS.md

确认无误后：

git add AGENTS.md
git add server/AGENTS.md
git add citizen-h5/AGENTS.md
git add admin-web/AGENTS.md
git add database/AGENTS.md
git add deployment/AGENTS.md

git commit -m "docs: add Codex project development rules"
git push

规则建设任务可以使用独立分支：

fea-agentsguize

第十八部分：完整生成提示词

四十八：可直接交给 Codex 的提示词💬

请为当前仓库建立 AGENTS.md 项目规则体系。

开始前：

读取仓库结构。

读取 package.json、构建配置和 CI。

识别真实测试命令。

识别后端、前端、数据库和部署目录。

执行 git status。

暂时不要修改文件。

第一步，输出规则规划：

根目录 AGENTS.md 应包含什么。

哪些子目录需要独立规则。

哪些目录不需要规则。

各规则的作用范围。

可能发生的冲突。

需要我确认的内容。

规则必须包含：

项目目标

业务固定约束

目录边界

任务执行流程

分支规范

Commit 规范

Push 规范

测试要求

依赖管理

Secret 安全

高风险操作

完成报告

当前固定 Git 规则：

每个新功能创建独立分支。

分支格式为 fea-{功能简介拼音}。

允许测试通过后自动 Commit。

允许自动 Push 当前功能分支。

禁止 Force Push。

禁止自动合并 main。

禁止覆盖用户未提交修改。

城市随手拍固定业务规则：

市民端使用 H5。

不做小程序和原生 APP。

手机号注册不发送短信验证码。

最多上传 5 张图片。

不允许视频。

地图使用百度地图。

支持自动定位和手动选点。

地址允许修改。

事项由管理员手动派发。

一个事项只能派发给一个部门。

确认规划后再创建规则文件。

生成后必须：

检查规则是否重复。

检查命令是否真实存在。

检查是否包含 Secret。

检查是否存在规则冲突。

让 Codex分别模拟根目录、后端和数据库目录中的生效规则。

执行 git diff。

暂时不要修改业务代码。

第十九部分：验收标准

四十九：本篇验收清单✅

完成后应达到：

根目录存在 AGENTS.md 后端存在子目录规则 H5 存在子目录规则管理端存在子目录规则数据库存在安全规则部署目录存在生产限制所有规则使用真实命令子目录没有大量重复父级规则新功能分支统一为 fea-{功能简介拼音} 允许测试通过后 Commit 和 Push 禁止 Force Push 禁止直接修改 main 测试失败不能提交禁止读取和提交 Secret 禁止修改历史迁移 Codex 能正确复述不同目录的生效规则规则文件已经进入 Git 审查

第二十部分：本篇总结

五十：核心结论📝

AGENTS.md 是面向 Codex 的项目开发手册根目录规则管理全局规范子目录规则管理技术差异更具体的目录规则优先当前任务直接要求优先于仓库规则 AGENTS.override.md 只用于明确的临时覆盖规则必须具体、可执行、可验证规则命令必须来自真实项目不要把需求全文复制进规则不要把 Secret 写进规则 AGENTS.md 不能替代沙箱、RBAC 和保护分支规则变更应像代码一样 Review

推荐最终结构：