Mystpet's Blog

重点：

AGENTS.md：把项目规范、目录约定、测试命令、提交要求写成长期上下文
Rules：控制哪些命令可以越过sandbox，哪些必须询问，哪些直接禁止
Hooks：在Codex生命周期中运行确定性脚本
Skills：把重复工作流封装成可复用能力
MCP：把外部文档、工具和上下文接入Codex
Docs MCP：在需要查OpenAI官方文档时，把文档直接拉进上下文

1.简介

前三个阶段分别解决：

第1阶段：Codex是什么、有哪些入口、怎么拿上下文
第2阶段：如何在 CLI/IDE中读代码、改代码、跑命令、解释报错、做review
第3阶段：如何把需求写成可执行任务

第4阶段解决的是：如何治理Codex的长期上下文，让它每次都按同一套项目规则、工具边界和工作流执行。

这一步是从“偶尔能用”到“持续好用”的关键。

如果没有上下文治理，你每次都要重复告诉Codex：

这个项目用什么包管理器
测试命令是什么
哪些目录不能改
不能引入新依赖
review要看哪些风险
查OpenAI文档时要用官方文档
提交前要跑哪些检查

有了上下文治理，这些内容可以固化到配置和项目文件中。

2.AGENTS.md：项目长期说明书

官方说明：Codex在开始工作前会读取AGENTS.md文件。通过全局说明和项目说明分层，可以让每次任务都有稳定的默认预期。

AGENTS.md最适合存放“长期稳定、反复适用”的内容。

适合写入：

项目结构
目录职责
本地启动命令
测试命令
lint/typecheck/build命令
包管理器约定
代码风格
分支和提交要求
code review重点
安全注意事项
禁止事项
常见任务流程
外部文档使用要求不适合写入：
本次任务的具体bug描述
临时需求
一次性的文件路径
过期的业务背景
大段复制的外部文档

一句话区分：

text

AGENTS.md 写长期规则
Prompt 写本次任务

3.agents.md的发现和优先级

Codex会按层级读取说明文件。

官方文档中的发现规则可以理解成三层：

全局范围：默认从~/.codex读取AGENTS.override.md，如果没有则读取 AGENTS.md
项目范围：从项目根目录一路向当前工作目录查找
合并顺序：从根目录到当前目录拼接，越靠近当前目录的说明越晚出现，因此更具体

常见位置：

text

<repo>/AGENTS.md
<repo>/src/payments/AGENTS.md
<repo>/src/payments/AGENTS.override.md

推荐分层

位置	适合写什么
`~/.codex/AGENTS.md`	个人通用偏好，例如回答风格、默认验证习惯、常用安全原则
项目根目录 `AGENTS.md`	项目规范、测试命令、目录结构、提交要求
子目录 `AGENTS.md`	某个模块的特殊规则
`AGENTS.override.md`	更强的临时或局部覆盖规则

注意：

Codex会跳过空文件
合并后的项目说明有大小限制，默认约32KiB
如果说明太长，应该拆到更靠近模块的子目录，而不是把所有内容塞到根目录

4.一个实用的项目AGENTS.md模板

可以从这个模板开始：

markdown

# AGENTS.md

<!--
这个文件是给AI编程助手看的项目说明书。
例如Codex、Cursor、ClaudeCode等工具在处理仓库代码时，可以参考这里的规则。
-->

## Project overview

<!--
这里写项目基本情况，包括项目类型、源码位置、测试位置、文档位置。
-->
- This repository is a <项目类型> project.
  <!--
  说明当前仓库是什么项目。
  例如：
  This repository is a Vue3+TypeScript frontend project.
  This repository is a SpringBoot backend project.
  -->
- Main source code lives in `src/`.
  <!--
  说明主要源码目录在src下。
  AI改代码时应该优先查看这个目录。
  -->
- Tests live next to source files or under `tests/`.
  <!--
  说明测试文件的位置。
  测试可能和源码放在一起，也可能统一放在tests目录下。
  -->
- Documentation lives in `docs/`.
  <!--
  说明项目文档放在docs目录下。
  AI需要了解业务或设计时，可以先看这里。
  -->

## Commands

<!--
这里写项目常用命令。
AI修改代码后，可以根据这些命令安装依赖、启动项目、运行测试、检查类型、检查代码规范和构建项目。
-->
- Install dependencies: `pnpm install`
  <!--
  安装项目依赖。
  一般用于前端项目。
  -->
- Start dev server: `pnpm dev`
  <!--
  启动开发环境服务器。
  -->
- Run tests: `pnpm test`
  <!--
  运行测试用例。
  -->
- Run typecheck: `pnpm typecheck`
  <!--
  运行TypeScript类型检查。
  用于发现类型错误。
  -->
- Run lint: `pnpm lint`
  <!--
  运行代码规范检查。
  用于发现格式、语法风格或潜在问题。
  -->
- Build: `pnpm build`
  <!--
  构建项目。
  一般用于检查项目是否能正常打包。
  -->

## Working agreements

<!--
这里写AI修改代码时必须遵守的工作约定。
作用是限制AI不要乱改、不乱加依赖、不破坏原有结构。
-->
- Prefer existing utilities before creating new helpers.
  <!--
  优先使用项目中已有的工具类、公共方法和组件。
  不要一上来就新建工具函数。
  -->
- Keep changes scoped to the requested task.
  <!--
  修改范围只限于当前任务。
  不要顺手重构无关代码。
  -->
- Do not introduce production dependencies without confirmation.
  <!--
  不要未经确认就添加新的生产依赖。
  新依赖可能增加包体积、安全风险或维护成本。
  -->
- Do not modify generated files unless explicitly requested.
  <!--
  不要修改自动生成的文件。
  例如构建产物、接口生成文件、锁定生成的代码等。
  除非任务明确要求修改。
  -->
- Do not change public API shapes unless the task explicitly requires it.
  <!--
  不要随便修改公开API结构。
  例如接口字段名、请求参数、响应格式、方法签名等。
  这可能导致其他模块或前端调用出错。
  -->
- Preserve existing UI style and layout unless the task is a UI redesign.
  <!--
  除非任务是UI重设计，否则不要随便改变现有页面风格和布局。
  -->

## Testing expectations

<!--
这里写测试要求。
AI改完代码后，应该根据改动范围选择合适的测试命令。
-->
- After changing TypeScript files, run the smallest relevant test first.
  <!--
  修改TypeScript文件后，优先运行最小范围的相关测试。
  不要一开始就跑全部测试，除非有必要。
  -->
- If behavior crosses module boundaries, run typecheck and broader tests.
  <!--
  如果改动影响多个模块，需要运行类型检查和更大范围的测试。
  -->
- If tests cannot be run, explain why and list the residual risk.
  <!--
  如果测试无法运行，需要说明原因，并列出剩余风险。
  例如缺少环境变量、依赖未安装、外部服务不可用等。
  -->

## Review guidelines

<!--
这里写代码审查规则。
当用户让AI做代码审查时，AI应该按这些重点检查。
-->
- Prioritize bugs, behavior regressions, missing tests, security risks, and error handling.
  <!--
  审查时优先关注bug、功能回退、缺少测试、安全风险和异常处理问题。
  -->
- Findings should include file paths and concrete risk.
  <!--
  发现问题时，需要写清楚文件路径和具体风险。
  不要只说“这里可能有问题”。
  -->
- If no issues are found, say that clearly and mention remaining test gaps.
  <!--
  如果没有发现问题，要明确说明没有发现明显问题。
  同时说明还有哪些测试没有覆盖。
  -->

## OpenAI docs

<!--
这里写和OpenAI相关的特殊要求。
如果项目里涉及OpenAIAPI、ChatGPTAppsSDK、Codex或OpenAI模型，AI应该查官方文档，不要凭旧知识乱写。
-->
- When working with OpenAI API, ChatGPT Apps SDK, Codex, or OpenAI models, use the OpenAI developer documentation MCP server.
  <!--
  处理OpenAI相关内容时，使用OpenAI开发者文档MCP服务器。
  这样可以参考最新官方文档，减少写错API或配置的概率。
  -->

这个模板的作用不是让Codex“更礼貌”，而是让它稳定知道：

应该读哪里
应该怎么改
应该跑什么
不应该碰什么
review应该看什么
查文档时应该用哪里

5.`Rules`：命令权限治理

Rules用来控制Codex哪些命令可以在sandbox外运行。

官方文档说明Rules仍是experimental，可能变化。现阶段理解它的价值即可：

text

AGENTS.md 管“应该怎么做”
Rules 管“哪些命令能不能做”

规则文件通常放在：

text

~/.codex/rules/default.rules

或项目内：

text

.codex/rules/default.rules

项目内rules只会在trusted project 中加载。

核心语法是 prefix_rule()：

python

prefix_rule(  
    pattern = ["gh", "pr", "view"],  
    decision = "prompt",  
    justification = "Viewing PRs is allowed with approval",  
    match = [  
        "gh pr view 123",  
        "gh pr view 123 --json title,body,comments",  
    ],  
    not_match = [  
        "gh pr --repo openai/codex view 123",  
    ],  
)

decision 有三种：

decision	含义
`allow`	匹配命令可以直接在`sandbox`外运行
`prompt`	匹配命令每次运行前询问
`forbidden`	匹配命令直接禁止

Rules适合治理：

gh pr view 这类常用只读命令
部署命令
包管理器安装命令
删除文件命令
数据库迁移命令
访问网络的命令
团队明确禁止的命令

使用建议：

只给稳定、安全、低风险命令配置 allow
对可能影响远端、网络、依赖、部署的命令用 prompt
对危险命令用 forbidden
使用 match和not_match 给规则写示例，避免前缀匹配过宽

6.Rules的安全边界

Rules不是写得越宽越好。

不推荐：

python

prefix_rule(  
    pattern = ["bash"],  
    decision = "allow",  
)

问题是 bash 后面可能藏着复杂脚本。

更推荐：

python

prefix_rule(  
    pattern = ["npm", "run", "test"],  
    decision = "allow",  
    justification = "Project tests are safe to run",  
)

或：

python

prefix_rule(  
    pattern = ["git", "push"],  
    decision = "prompt",  
    justification = "Pushing changes affects remote branches",  
)

官方文档还说明：Codex会尽量拆解简单shell链式命令，例如 git add . && rm -rf / 会被拆成两个命令分别评估；但如果脚本中包含变量、重定向、通配符、控制流等复杂shell特性，Codex会更保守地把整个shell调用作为一个整体评估。

测试规则可以用：

bash

codex execpolicy check --pretty \  
  --rules ~/.codex/rules/default.rules \  
  -- gh pr view 7888 --json title,body,comments

阶段4 只需要记住：

Rules是安全阀，不是偷懒工具。前缀越宽，风险越高。

7.`Hooks`：生命周期中的确定性脚本

Hooks是Codex的扩展机制，可以在 agent生命周期中运行你自己的脚本。

官方文档给出的典型用途包括：

把对话发送到自定义日志或分析系统
扫描用户prompt，防止误贴 APIkey
自动总结对话，形成持久记忆
在一轮对话停止时运行自定义验证
在特定目录中注入额外提示

Hooks需要在config.toml 中启用：

toml

[features]  
codex_hooks = true

常见位置：

text

~/.codex/hooks.json  
~/.codex/config.toml  
<repo>/.codex/hooks.json  
<repo>/.codex/config.toml

项目级hooks只会在 trusted project 中加载。

常见 hook事件：

Hook	作用
`SessionStart`	会话启动或恢复时运行
`UserPromptSubmit`	用户提交`prompt`时运行
`PreToolUse`	工具调用前运行，例如 Bash、apply_patch、MCP
`PermissionRequest`	Codex请求权限时运行
`PostToolUse`	工具调用后运行
`Stop`	一轮任务停止时运行

8.Hooks适合做什么，不适合做什么

Hooks适合做确定性、可脚本化、低歧义的事情。

适合：

检查prompt是否包含密钥格式
在任务结束时检查是否有未提交的大diff
在特定目录加载额外上下文
自动记录每轮操作日志
在Bash命令执行前做安全检查
在任务结束时提醒运行测试

不适合：

替代完整权限系统
写复杂业务逻辑
强行修复代码
在每个turn做耗时操作
依赖不稳定网络
隐式修改用户文件

原因：

多个匹配hooks会并发运行
Hooks更像 guardrail和自动化插桩，不是完整的安全边界
过重的hooks会拖慢每次Codex交互

最小示例：

json

{  
  "hooks": {  
    "PreToolUse": [  
      {  
        "matcher": "Bash",  
        "hooks": [  
          {  
            "type": "command",  
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",  
            "statusMessage": "Checking Bash command"  
          }  
        ]  
      }  
    ]  
  }  
}

9.`Skills`：把重复工作流封装起来

Skills用来给Codex增加任务专用能力。

官方文档说明：一个skill可以打包instructions、resources和可选scripts，让Codex更可靠地执行某类工作流。

Skills适合：

固定格式的代码审查
前端页面实现规范
数据库迁移流程
发布检查清单
项目专用排障流程
根据公司规范写文档
OSS维护流程

一个skill通常是一个目录：

text

my-skill/  
  SKILL.md  
  scripts/  
  references/  
  assets/  
  agents/

其中SKILL.md必须包含：

markdown

---  
name: skill-name  
description: Explain exactly when this skill should and should not trigger.  
---  

Skill instructions for Codex to follow.

Skills的关键机制是 progressive disclosure：

Codex一开始只看到skill的 name、description和路径
只有决定使用某个skill时，才读取完整SKILL.md
这样可以避免把所有技能说明一次性塞进上下文

触发方式：

方式	说明
显式触发	在`prompt`中直接提到`skill`，例如 `$skill-name`
隐式触发	任务匹配`skill`的`description`，Codex自己选择使用

写skill的建议：

每个skill只做一类任务
description写清楚什么时候该触发、什么时候不该触发
优先用说明文字，只有需要确定性行为或外部工具时才写脚本
明确输入和输出
用真实prompt测试触发是否准确

一句话理解：

Skills是把“我每次都要教Codex的工作流”沉淀成可复用能力。

10.MCP：接入外部工具和上下文

MCP是Model Context Protocol，用来把外部工具和上下文接入Codex。

官方文档说明：MCP可以让Codex访问第三方文档，也可以让它操作浏览器、Figma等开发工具。

Codex的CLI和IDE Extension都支持MCP，并共享配置。

常见MCP类型：

类型	说明
STDIO server	作为本地进程启动的 MCP server
Streamable HTTP server	通过 URL 访问的 MCP server

MCP配置通常写在：

text

~/.codex/config.toml

或trusted project的：

text

.codex/config.toml

CLI添加MCP server的基本形式：

bash

codex mcp add <server-name> -- <stdio-server-command>

查看 MCP：

bash

codex mcp list

在TUI中可以用：

text

/mcp

MCP适合这些场景：

查框架最新文档
查OpenAI官方文档
读取内部API文档
访问设计工具上下文
连接公司内部开发工具
给Codex增加只靠本地repo看不到的信息

使用原则：

能从项目代码里确定的事实，优先读代码
涉及外部API、第三方库、版本变化时，用MCP查文档
不要把敏感系统随便接给Codex
给MCP server最小必要权限

11.`Docs MCP`：把OpenAI官方文档接进Codex

官方说明：OpenAI提供了一个公开 MCP server，用来搜索和读取 developers.openai.com 与 platform.openai.com 上的开发者文档。

Server URL：

text

https://developers.openai.com/mcp

它提供：

对OpenAI开发者文档的只读访问
搜索文档
读取页面内容
在工作时把官方文档拉进 agent上下文

它不做：

不替你调用OpenAI API
不访问你的账户数据
不执行业务操作

Codex CLI添加方式：

bash

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

验证：

bash

codex mcp list

也可以直接写入 ~/.codex/config.toml：

toml

[mcp_servers.openaiDeveloperDocs]  
url = "https://developers.openai.com/mcp"

为了让Codex稳定使用它，可以在 AGENTS.md 写：

markdown

## OpenAI docs  

- Always use the OpenAI developer documentation MCP server if you need to work with the OpenAI API, ChatGPT Apps SDK, Codex, or OpenAI models.

MCP与Skill工作示例：

场景	MCP 做什么	Skill 做什么
查 OpenAI 文档	连接 OpenAI Docs MCP，读取官方文档	告诉 Codex 遇到 OpenAI 问题时优先查官方文档
看 Figma 设计稿	连接 Figma MCP，读取设计文件	告诉 Codex 如何从设计稿落地成代码
查 Sentry 报错	连接 Sentry MCP，读取错误日志	告诉 Codex 如何 triage、定位、修复
管 Linear issue	连接 Linear MCP，读写 issue	告诉 Codex 如何拆任务、更新 issue、回写进度
浏览器调试	连接 Playwright / Chrome DevTools MCP	告诉 Codex 如何打开页面、截图、看 console、验证 UI

一句话理解：

Docs MCP是让Codex查OpenAI官方文档的标准入口，适合处理API、模型、Codex、Apps SDK等会随时间变化的问题。

12.五个治理工具的分工

工具	解决什么问题	典型内容
`AGENTS.md`	Codex每次应该知道什么	项目规范、测试命令、目录约定、`review`标准
Rules	Codex哪些命令能越过`sandbox`	`allow`/`prompt`/`forbidden`命令前缀
Hooks	在生命周期中自动运行什么脚本	`prompt`扫描、命令检查、结束校验、日志记录
Skills	某类任务怎么稳定执行	可复用工作流、参考资料、脚本、模板
MCP	Codex可以接入哪些外部上下文和工具	官方文档、第三方文档、Figma、浏览器、内部工具

最容易混淆的是这三组：

AGENTS.md vs Prompt
长期规则 vs 本次任务

Rules vs Hooks
命令权限策略 vs 生命周期脚本

Skills vs MCP
工作流能力包 vs 外部工具/上下文连接

13. 推荐的落地顺序

如果你刚开始做上下文治理，不要一次性上齐所有机制。

推荐顺序：

第一步：写项目根目录 `AGENTS.md`

先把最常重复的规则固化：

项目结构
包管理器
测试命令
lint/typecheck/build命令
不允许做的事情
review标准

第二步：给特殊模块加子目录 `AGENTS.md`

例如：

services/payments/AGENTS.md
frontend/components/AGENTS.md
docs/AGENTS.md

把模块特殊规则放近一点。

第三步：接 `Docs MCP`

如果你经常问OpenAI API、Codex、Apps SDK、模型、工具调用相关问题，就配置：

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp

并在AGENTS.md里要求需要OpenAI文档时优先使用 Docs MCP。

第四步：补 Rules

只给稳定命令加规则，例如：

常用测试命令allow
远端操作prompt
高风险命令forbidden

第五步：补 Skills

当你发现某类任务反复出现，例如：

PRreview
前端页面实现
测试补齐
发布检查
文档整理

再把它做成skill。

第六步：谨慎使用`Hooks`

Hooks最后上。只把确定性、低成本、高价值的自动化放进去，例如：

prompt密钥扫描
结束时提醒验证
命令执行前检查
会话日志

14.一个完整的上下文治理示例

假设这是一个前端项目，可以这样治理：

目录结构：

text

my-app/  
  AGENTS.md  
  .codex/  
    config.toml  
    rules/  
      default.rules  
    hooks.json  
  .agents/  
    skills/  
      frontend-implementation/  
        SKILL.md  
  src/  
    components/  
      AGENTS.md

根目录AGENTS.md：

markdown

# AGENTS.md  

## Commands  

- Install: `pnpm install`  
- Dev: `pnpm dev`  
- Test: `pnpm test`  
- Typecheck: `pnpm typecheck`  
- Lint: `pnpm lint`  
- Build: `pnpm build`  

## Rules  

- Keep changes scoped to the requested task.  
- Do not introduce production dependencies without confirmation.  
- Preserve existing UI style unless explicitly asked.  
- Prefer existing components and hooks.  
- Do not modify generated files.  

## Verification  

- Run the smallest relevant test first.  
- Run typecheck after changing TypeScript types.  
- If validation cannot run, explain why.  

## OpenAI docs  

- Use the OpenAI developer documentation MCP server for OpenAI API, Codex, Apps SDK, or model questions.

组件目录src/components/AGENTS.md：

markdown

# Component rules  

- Reuse existing design tokens.  
- Keep components accessible.  
- Do not introduce page-level data fetching here.  
- Add or update component tests when behavior changes.

Rules示例：

python

prefix_rule(  
    pattern = ["pnpm", "test"],  
    decision = "allow",  
    justification = "Project tests are safe to run",  
)  

prefix_rule(  
    pattern = ["git", "push"],  
    decision = "prompt",  
    justification = "Pushing affects remote branches",  
)  

prefix_rule(  
    pattern = ["rm", "-rf", "/"],  
    decision = "forbidden",  
    justification = "Never remove the filesystem root",  
)

Docs MCP配置：

toml

[mcp_servers.openaiDeveloperDocs]  
url = "https://developers.openai.com/mcp"

15.总结

text

`Prompt`解决本次任务
`AGENTS.md`解决长期规则
`Rules`解决命令权限
`Hooks`解决自动化检查
`Skills`解决重复工作流
`MCP`解决外部上下文
`Docs MCP`解决官方文档查询

一句话总结：

上下文治理的核心，是把项目规范、工具边界和常用工作流前置到Codex能自动读取的位置，让它每次都少猜一点、多遵守一点、少问一点、少犯一点。

1.短信登录

2.商户查询缓存

3.优惠卷秒杀

4.达人探店

5.好友关注

6.附近商铺

7.用户签到

8.UV统计

项目

项目

1.简介

2.AGENTS.md：项目长期说明书

3.agents.md的发现和优先级

4.一个实用的项目AGENTS.md模板

5.`Rules`：命令权限治理

6.Rules的安全边界

7.`Hooks`：生命周期中的确定性脚本

8.Hooks适合做什么，不适合做什么

9.`Skills`：把重复工作流封装起来

10.MCP：接入外部工具和上下文

11.`Docs MCP`：把OpenAI官方文档接进Codex

12.五个治理工具的分工

13. 推荐的落地顺序

第一步：写项目根目录 `AGENTS.md`

第二步：给特殊模块加子目录 `AGENTS.md`

第三步：接 `Docs MCP`

第四步：补 Rules

第五步：补 Skills

第六步：谨慎使用`Hooks`

14.一个完整的上下文治理示例

15.总结

1.简介 ​

2.AGENTS.md：项目长期说明书 ​

3.agents.md的发现和优先级 ​

4.一个实用的项目AGENTS.md模板 ​

5.Rules：命令权限治理 ​

6.Rules的安全边界 ​

7.Hooks：生命周期中的确定性脚本 ​

8.Hooks适合做什么，不适合做什么 ​

9.Skills：把重复工作流封装起来 ​

10.MCP：接入外部工具和上下文 ​

11.Docs MCP：把OpenAI官方文档接进Codex ​

12.五个治理工具的分工 ​

13. 推荐的落地顺序 ​

第一步：写项目根目录 AGENTS.md ​

第二步：给特殊模块加子目录 AGENTS.md ​

第三步：接 Docs MCP ​

第四步：补 Rules ​

第五步：补 Skills ​

第六步：谨慎使用Hooks ​

14.一个完整的上下文治理示例 ​

15.总结 ​

1.简介

2.AGENTS.md：项目长期说明书

3.agents.md的发现和优先级

4.一个实用的项目AGENTS.md模板

5.`Rules`：命令权限治理

6.Rules的安全边界

7.`Hooks`：生命周期中的确定性脚本

8.Hooks适合做什么，不适合做什么

9.`Skills`：把重复工作流封装起来

10.MCP：接入外部工具和上下文

11.`Docs MCP`：把OpenAI官方文档接进Codex

12.五个治理工具的分工

13. 推荐的落地顺序

第一步：写项目根目录 `AGENTS.md`

第二步：给特殊模块加子目录 `AGENTS.md`

第三步：接 `Docs MCP`

第四步：补 Rules

第五步：补 Skills

第六步：谨慎使用`Hooks`

14.一个完整的上下文治理示例

15.总结