Codex 上下文 + 主动读取 + AGENTS.md 生成组合版

1. 文档目标

这份文档要解决的是三个经常被分开处理、但实际上应该连起来看的问题：

• 怎么给 Codex 足够完整的上下文
• 怎么让 Codex 主动读取更多关键文件、目录和规则文件
• 怎么把它的项目理解进一步沉淀成AGENTS.md

读完后，你应该能够：

• 让 Codex 更快建立正确项目认知
• 避免只给少量上下文导致输出泛化
• 让 Codex 主动补齐更多项目理解材料
• 基于读取结果生成团队 AI 规范与AGENTS.md
• 形成一套可反复复用的项目初始化流程

2. 为什么这三件事要连起来做

很多团队现在的方式是：

• 提一个需求
• 贴几段代码
• 直接让 Codex 开始改

这样的问题是：

• 上下文不完整
• 文件读取不系统
• 理解结果无法沉淀
• 下一次还要重新解释一遍

而把这三件事串起来后，流程会更像：

1. 先给初始上下文
2. 再让 Codex 主动读更多高价值文件
3. 再让它总结项目结构、规则和边界
4. 最后产出AGENTS.md和团队规范

这样，后续所有协作都会更稳。

3. 三件事分别解决什么问题

3.1 上下文提供

解决的问题：

• Codex 不知道你到底要它做什么
• 没有目标、约束和验证标准

3.2 主动读取

解决的问题：

• 你自己也不清楚还缺哪些关键信息
• 只靠你手动挑文件容易遗漏

3.3 AGENTS.md 生成

解决的问题：

• 一次理解不能长期复用
• 团队没有统一 AI 协作规则

4. 这套组合方法的核心思想

可以把它概括成一句话：

先给 Codex 足够方向，再让它主动补齐项目理解，最后把理解结果沉淀成规则。

这三步缺一不可：

• 只有上下文，没有主动读取，理解可能太浅
• 只有主动读取，没有结构化上下文，方向可能发散
• 只有理解，没有沉淀，后续仍然重复劳动

5. 推荐的整体流程

6. 第一步：先给初始上下文，而不是直接放手让它乱读

即使你希望 Codex 主动读取项目，也不意味着完全不给方向。

你至少要先告诉它：

• 当前目标是什么
• 项目大概是什么类型
• 你希望它先做理解，不要直接改代码
• 它最终要输出什么

推荐初始上下文模板

请先不要改代码，先帮我建立这个项目的完整上下文。 目标： 我希望你先理解项目，再进一步生成适合团队使用的 AGENTS.md。 项目背景： 这是一个 [项目类型 / 技术栈] 项目。 当前要求： 1. 先主动读取关键文件、目录和规则文件 2. 再输出结构化项目理解结果 3. 最后基于理解结果生成 AGENTS.md 草案

7. 第二步：让 Codex 主动读取关键入口文件

这是最稳的起点。

推荐优先读取

• README
• 构建文件，例如pom.xml
• 配置文件，例如application.yml
• 启动入口
• 核心模块目录

示例提示词

请先主动读取这个项目的关键入口文件，帮助我建立第一层上下文。 请优先阅读： 1. README 2. pom.xml 3. application.yml / bootstrap.yml 4. 启动类 5. 核心业务模块根目录 输出： 1. 项目结构概览 2. 技术栈 3. 模块大致职责 4. 接下来建议继续读取哪些位置

8. 第三步：让 Codex 继续读取规则文件和协作文档

如果项目里已经有协作规则，不让它读这些文件，就等于主动丢掉高价值上下文。

常见规则文件

• AGENTS.md
• CLAUDE.md
• README
• docs目录中的规范文档
• 脚本说明、部署说明、SQL 工具说明

示例提示词

请继续主动检查这个项目是否存在规则文件和协作文档。 优先关注： 1. AGENTS.md 2. CLAUDE.md 3. README 4. docs 目录下的规范文档 5. 脚本和部署说明 输出： 1. 找到了哪些规则文件 2. 每个文件约束了什么 3. 哪些规则必须优先遵守

9. 第四步：让 Codex 主动追“典型业务链路”

只看目录和规则还不够，项目理解一定要下钻到真实调用链。

推荐追踪对象

• 一个典型接口
• 一个典型查询链路
• 一个典型保存链路

示例提示词

在理解完项目结构和规则后，请继续主动追踪一个典型业务链路。 目标链路： 订单分页查询 请输出： 1. Controller 入口 2. Service 调用链 3. Mapper / XML 位置 4. 查询条件在哪一层处理 5. 哪些文件是这个链路的关键上下文

10. 第五步：让 Codex 输出结构化项目理解结果

不要让理解停留在“它看过了”，而要输出结构化结果，便于后续沉淀。

推荐输出结构

• 项目定位
• 技术栈
• 模块与目录职责
• 典型业务链路
• 规则与约束
• 高风险区域
• 适合沉淀成AGENTS.md的规则

示例提示词

请把你当前主动读取后的理解结果，按结构化方式输出： 1. 项目定位 2. 技术栈 3. 模块职责 4. 典型链路 5. 已发现的规则和约束 6. 高风险区域 7. 适合写入 AGENTS.md 的规则草案

11. 第六步：基于理解结果提炼团队规则

项目理解完成后，下一步不是立即写代码，而是先把它提炼成规则。

建议提炼的内容

• AI 工作方式
• 修改边界
• 高风险操作约束
• 测试与验证要求
• Git 协作要求

示例提示词

请基于你当前对项目的理解，提炼一份团队 AI 协作规则草案。 要求覆盖： 1. AI 使用目标 2. 修改边界 3. 高风险操作约束 4. 验证要求 5. Git commit / 分支 / 回滚要求

12. 第七步：生成 AGENTS.md 草案

这一步才是最终沉淀动作。

一个好的 AGENTS.md 至少应包含

• 项目说明
• 模块说明
• AI 工作原则
• 修改规则
• Git 协作规则
• 高风险场景规则
• 测试与验证要求
• 禁止事项

示例提示词

请基于你刚才的项目理解和团队规则草案，生成一份 AGENTS.md。 要求： 1. 内容结构化 2. 贴近真实项目 3. 包含 Git 协作规则 4. 包含修改边界、验证要求和禁止事项

13. 一份组合式通用提示词

下面这段可以在新项目初始化时直接用。

请先不要改代码，先帮我建立这个项目的完整协作上下文，并最终生成 AGENTS.md 草案。 请按下面顺序进行： 1. 先读取 README、构建文件、配置文件、启动类 2. 再读取核心业务模块目录 3. 再检查 AGENTS.md、CLAUDE.md、docs 中的规则文件 4. 再主动追踪一个典型业务链路 5. 输出结构化项目理解结果 6. 提炼团队 AI 协作规则 7. 最后生成 AGENTS.md 草案 输出要求： 1. 当前项目定位和技术栈 2. 模块职责 3. 业务链路 4. 已发现规则 5. 高风险区域 6. 团队 AI 协作规则草案 7. AGENTS.md 草案

14. Java / Spring Boot 项目实战实例

场景

你接手一个 Spring Boot 项目，希望让 Codex 快速进入状态，并最终产出团队规则文件。

推荐执行路径

第一步：给初始上下文

这是一个 Java / Spring Boot + MyBatis 项目。 请先不要改代码，先帮我建立完整上下文，并最终生成 AGENTS.md 草案。

第二步：让它主动读取

请主动读取： 1. README 2. pom.xml 3. application.yml 4. 启动类 5. yudao-module-system 和 yudao-module-member 核心目录 6. AGENTS.md / CLAUDE.md / docs 中的规则文件

第三步：让它追典型链路

请继续主动追踪一个典型业务链路： 用户分页查询 输出： 1. Controller 2. Service 3. Mapper / XML 4. 关键约束 5. 高风险区域

第四步：生成 AGENTS.md

请基于你当前的理解，生成一份适用于该项目的 AGENTS.md 草案。

这样做的价值

• 不是一次性问答
• 而是一次完整的项目上下文建立过程

15. 团队初始化实战实例

场景

团队准备在一个新仓库里系统引入 Codex。

推荐做法

1. 先由一位负责人运行组合式提示词
2. 产出第一版项目理解结果
3. 产出第一版团队规则草案
4. 产出AGENTS.md草案
5. 团队评审后正式入库

图示

16. 常见误区

16.1 误区一：只给上下文，不让它继续主动读取

问题：

• 理解容易停留在表层

16.2 误区二：只让它读目录，不让它追链路

问题：

• 很难真正理解业务结构

16.3 误区三：读完就结束，不做沉淀

问题：

• 下一次还要重新解释

16.4 误区四：一上来就让它直接生成 AGENTS.md

问题：

• 没有足够项目理解支撑，规则容易空泛

17. 注意事项

• 先给方向，再让 Codex 主动读取
• 主动读取要有顺序，不要盲扫
• 一定要让它继续追规则文件和典型链路
• 生成 AGENTS.md 前，先让它输出结构化理解结果
• 团队规则必须人工评审，不要直接无脑落库

18. 高质量提示词模板

18.1 组合初始化模板

请先不要改代码，先帮我完成项目上下文建立，并最终生成 AGENTS.md 草案。 请按顺序： 1. 读取关键入口文件 2. 读取模块目录 3. 读取规则文件 4. 追踪典型业务链路 5. 输出项目理解结果 6. 提炼团队规则 7. 生成 AGENTS.md

18.2 规则提炼模板

请基于当前项目理解结果，提炼一份团队 AI 协作规则。 要求覆盖： 1. 修改边界 2. 高风险约束 3. Git 协作要求 4. 测试与验证要求 5. 禁止事项

18.3 AGENTS 生成模板

请基于当前项目结构、规则和风险点，生成一份 AGENTS.md。 要求： 1. 内容结构化 2. 贴近真实项目 3. 可直接入库

19. 团队落地建议

如果你想把这套方法推广到团队里，建议这样做：

1. 把这套流程作为新项目初始化步骤
2. 固化一份组合式提示词
3. 团队统一 review 第一版 AGENTS.md
4. 后续随着项目演进持续更新

20. 一句话总结

“上下文 + 主动读取 + AGENTS.md 生成”的组合版，本质上是在把一次性的 AI 问答升级成一套长期可复用的项目理解与规则沉淀机制。

21. 快速上手清单

• 先给初始上下文
• 再让 Codex 主动读取入口文件
• 再让它读取规则文件和典型链路
• 再输出结构化项目理解结果
• 再提炼团队规则
• 最后生成 AGENTS.md 草案