一套可直接复用的 Codex AGENTS.md：全局规则与 Java 项目规则分层实践

一套可直接复用的 Codex AGENTS.md全局规则与 Java 项目规则分层实践摘要把跨项目行为放进全局规则把可验证的技术、命令和交付约束放进项目规则才能让 Codex 有执行力而不越权。目录文章目录一套可直接复用的 Codex AGENTS.md全局规则与 Java 项目规则分层实践目录一、先把规则边界划清楚二、可复用的全局 AGENTS.md 模板为什么全局模板不写技术栈三、可复用的 Java / Spring Boot 项目 AGENTS.md 模板示例把通用模板收敛到真实项目四、当前 Freight Assistant 的已核实落地五、日常使用流程与反模式一次安全的改动流程六、上线前检查清单七、参考与结论一、先把规则边界划清楚AGENTS.md不是需求文档也不是把所有最佳实践堆进去的清单。它的职责是约束 AI 在缺少即时人工监督时如何理解上下文、控制改动范围、验证结果并交付。规则应按“稳定性”和“适用范围”分层越稳定、越跨项目的内容越靠上越依赖仓库事实的内容越靠近代码。用户当轮明确要求全局 AGENTS.md项目根目录 AGENTS.md子目录 AGENTS.md具体代码与配置实现、验证与交付图 1从广泛规则到局部事实逐层收敛。下层规则只能补充或细化不能违背上层要求。层级放什么不该放什么用户请求本次目标、验收、授权范围永久团队规范全局~/.codex/AGENTS.md沟通方式、风险判断、Git 安全、完成标准某项目端口、数据库密码、目录结构项目AGENTS.md技术栈、目录、构建命令、配置策略、测试要求与项目无关的长篇方法论子目录AGENTS.md模块专属协议、迁移规则、前端或服务边界重复整个项目规则[!IMPORTANT]“项目已有实现优先”必须写进规则。否则通用模板很容易强行覆盖既有路由、错误码、配置方式或认证协议造成看似规范、实际不兼容的改动。二、可复用的全局 AGENTS.md 模板下面的模板适合放在~/.codex/AGENTS.md。它不绑定 Java、前端框架、端口或部署工具目标是让所有项目中的行为一致。# Codex 全局工作规则 ## 规则优先级 - 系统指令、用户当轮明确要求优先于本文件。 - 距离目标文件更近的项目或子目录 AGENTS.md 优先于本文件。 - 规则冲突时选择更具体、更严格且不违背上级要求的一项。 ## 沟通与判断 - 使用用户的语言结论先行区分已核实事实、合理推测和个人建议。 - 对方案、风险、关键结论和重要决策检查错误前提、逻辑跳跃和信息缺失。 - 仅在关键歧义会显著改变范围、风险或验收标准时提问其余按最小合理假设推进并说明假设。 - 不把“未测试”“仅编译通过”或“推测可用”写成“已完成”。 ## 执行与范围 - 先阅读相关代码、调用链、配置和测试再修改不凭空假设字段、接口、权限或运行环境。 - 优先最小改动不顺手重构、不替换框架、不修改无关文件。 - 修改前检查工作目录、分支和 git status保留用户已有无关改动。 - 遇到外部系统、生产操作、数据删除、批量更新、发布、权限提升或不可逆变更先说明影响并等待明确授权。 ## 验证与交付 - 将任务转成可验证目标修复先复现或测试证明新增能力明确输入、输出、异常和验收条件。 - 完成后运行与改动风险相称的格式化、静态检查、测试或联调检查最终 diff。 - 交付时说明已完成内容、验证证据、未执行验证、已知风险和后续操作。 ## Git 与安全 - 未经明确授权不提交、推送、创建标签、合并分支或发布。 - 禁止执行 git reset --hard、强制推送和交互式改写历史。 - 不在命令输出、日志、文档或代码中暴露密码、令牌、连接串、Cookie、个人隐私或生产密钥。 ## 会话恢复 - 任务中断前在不泄露敏感信息的前提下记录进度、已验证事实、下一步和阻塞项。 - 恢复后先读取已有进度记录已完成的检查不重复执行无阻塞则继续推进。为什么全局模板不写技术栈“所有项目都用 Java 17”“所有接口都必须以/api开头”“必须用 Docker”都不是全局事实。把这类规则放到全局层会让 AI 在不匹配的仓库里做错误迁移。全局层只定义行为项目层才定义事实。三、可复用的 Java / Spring Boot 项目 AGENTS.md 模板以下模板面向 Maven、Java 17、Spring Boot 3.x 项目。方括号中的内容必须先用仓库事实替换不能直接当作真实配置。# Repository Guidelines ## 项目事实 - 技术栈[Java 17]、[Spring Boot 3.x]、[Maven]、[MyBatis / JPA]。 - 主代码位于 [src/main/java/...]测试位于 [src/test/java/...]迁移脚本位于 [实际目录]。 - 配置 profile 为 [dev/test/prod]配置策略遵循现有 application-*.yml 或受控配置中心未经确认不得替换。 ## 构建、测试与本地运行 - 使用项目已有命令mvn test、mvn clean package、mvn spring-boot:run。 - 先确认 Java 版本、profile 与外部依赖隔离性不得把测试连到生产服务。 - [如仓库明确禁止 Docker、Testcontainers 或环境变量覆盖在此逐条写明。] ## 架构与接口 - Controller 只负责参数接收、鉴权和响应业务规则、事务与状态流转放在 Service数据库访问放在 Mapper/Repository。 - DTO 用于请求VO/BO 用于响应或业务传递Entity 不直接暴露为外部接口契约。 - 写操作明确事务边界删除、审批、状态变更和批处理校验权限与数据归属。 - 遵循已有统一响应、错误码、HTTP 状态、REST 路径和字段命名契约禁止凭模板强制改成 /api 或 HTTP 200 包装所有失败。 ## 数据、安全与外部调用 - 数据库结构修改必须提供版本化迁移不可逆、大表或数据清洗操作先说明影响并取得确认。 - 金额使用 BigDecimal时间、时区、枚举值和缓存 TTL 遵循现有约定。 - 禁止拼接 SQL、Shell 命令和文件路径日志与文档不得出现密钥、令牌、连接串或完整敏感数据。 - 外部 HTTP、消息、文件和缓存调用应设置超时、失败处理和幂等边界仅对可幂等操作重试。 ## 注释、OpenAPI 与测试 - 公共 Controller、Service、DTO、VO、Entity、Enum 和配置对象以中文 Javadoc 说明职责、权限、边界和副作用。 - 对外 API 使用项目既有的 OpenAPI 注解接口变更同步更新示例、错误响应和前端契约。 - Bug 修复需覆盖根因回归新增能力覆盖正常路径、参数异常、权限边界和关键失败路径。 - 使用项目已有格式化、静态检查和测试工具外部依赖使用隔离替身不 mock 被测对象。 ## Git 与交付 - 提交信息格式feat|fix|docs|refactor|test|chore: 中文摘要。 - 未经授权不提交、推送、合并或发布提交前检查目标 diff 不含构建产物、日志、临时文件或敏感数据。 - 交付必须写明发布范围、已完成内容、修改文件、验证结果、未验证项和剩余风险。示例把通用模板收敛到真实项目假设一个项目的事实是“Java 17、Spring Boot 3.0.2、Maven、MyBatis-Plus、本机运行且禁止容器”项目规则应写成确定句而不是“可能使用 Docker”或“建议使用 JPA”。AI 因此能直接执行mvn test并知道不能用 Docker、Compose 或 Testcontainers 规避本机依赖。四、当前 Freight Assistant 的已核实落地当前工作区的规则已经具备两层结构全局规则负责优先级、独立判断、会话恢复和安全边界项目规则负责 Java 17、Spring Boot 3.0.2、Maven、包结构和验证命令。已核实项当前项目约束这样写的原因运行方式本机 Maven / Spring Boot仓库明确禁止 Docker、Compose、Testcontainers 与容器连接配置application-dev.yml、application-test.yml、application-prod.yml本地开发配置保留在配置文件不能擅自改为环境变量占位符数据访问MyBatis-Plus MapperSQL 映射与 DAO 同名避免凭空切换到 JPAAPI 文档OpenAPISchema等注解DTO、BO 的字段契约要与接口同步测试JUnit 5、mvn test服务、控制器或 DAO 改动应有对应测试交付标注发布范围与验证证据防止“代码改完”被误写为“功能已可发布”[!WARNING]当前项目规则中“所有 API 都以/api开头”只能在仓库现有接口确实如此时保留。若当前契约使用其他前缀应把这条改为“遵循已有 API 路径契约”否则会制造兼容性破坏。五、日常使用流程与反模式一次安全的改动流程阅读用户目标、全局规则、项目规则与目标模块。用git status确认工作树并定位真实调用链。写出输入、输出、权限、副作用和异常路径必要时先补测试。只修改调用链涉及的文件复用已有约定。运行格式化、相关测试和风险相称的接口验证。审查 diff交付事实、证据和限制。反模式后果替代做法全局规则硬编码项目端口和框架切换仓库就误操作放到项目规则并标注事实来源模板强制改接口前缀或配置形式破坏已有前后端契约“遵循项目既有契约”优先只要求“写代码”AI 容易停止在未验证状态明确格式化、测试、diff 检查和交付字段用大段禁令代替授权边界常规开发也被卡住只对发布、外部写入、删除和不可逆操作要求确认六、上线前检查清单全局规则没有包含任何项目密码、端口、路径或环境事实。项目规则中的 Java 版本、构建命令、profile、目录和测试命令已通过仓库核实。同一规则没有在两个层级以相互矛盾的方式重复。数据迁移、生产操作、第三方写入与 Git 提交都有明确授权门槛。交付标准区分“已验证”和“尚未验证”。每次规则改动后检查git diff --check并审查是否意外改动业务文件。七、参考与结论当前全局规则文件~/.codex/AGENTS.md。当前项目规则文件AGENTS.md。Codex 的实际行为仍应以系统指令、用户当轮要求和最近目录的AGENTS.md为准。结论很简单全局规则管理“怎么做事”项目规则管理“在这个仓库里做什么”。两层都短、准、可验证时AI 才能既自主推进也不会越权替团队做架构或发布决策。