全局 AGENTS.md

全局 AGENTS.md 用于给 Codex 提供默认编码规则。除非项目目录中的 AGENTS.md 另有说明，否则这些规则适用于所有 Codex 编码任务。

方式一：通过 Codex 客户端配置

打开 Codex 客户端设置，在 个性化 页面找到 自定义指令，粘贴下面的全局编码指令后点击保存。

（内部环境截图已移除。）

方式二：不使用 Codex 客户端配置

如果不使用 Codex 客户端，可以直接在用户目录下创建全局 AGENTS.md 文件。

系统	文件路径
macOS / Linux	~/.codex/AGENTS.md
Windows PowerShell	$env:USERPROFILE\.codex\AGENTS.md

macOS / Linux：

mkdir -p ~/.codex
vim ~/.codex/AGENTS.md

Windows PowerShell：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"
notepad "$env:USERPROFILE\.codex\AGENTS.md"

将下面内容写入文件后保存即可。

推荐内容

# 全局编码指令

除非项目目录中的 AGENTS.md 另有说明，否则这些规则适用于所有 Codex 编码任务。

## 核心原则

用最小、最清晰、最可验证的改动解决当前任务。

优先：

- 简单直接。
- 精准修改。
- 遵循现有代码风格。
- 明确假设。
- 结果可验证。

避免：

- 默默猜测。
- 大范围重写。
- 添加未要求的功能。
- 为未来可能性过早设计。
- 顺手优化无关代码。
- 声称未经验证的正确性。

## 编码前思考

- 明确假设，不确定时询问而非猜测。
- 存在歧义时，列出多种解释，不默默选一种。
- 如果任务有明显更简单的做法，直接指出。
- 发现矛盾或不一致时停下来，要求澄清。
- 修改前先理解相关代码路径，不要直接猜实现。

## 简洁优先

- 用最少的代码解决问题。
- 不为一次性需求创建抽象层。
- 不为“万一以后需要”增加灵活性和可配置性。
- 如果当前任务涉及的代码可以从 200 行简化为 50 行，并且风险可控，优先简化；否则只提出建议，不主动大改。
- 检查标准：资深工程师会觉得这过于复杂吗？如果是，简化。

## 精准修改

- 只修改与当前任务直接相关的代码。
- 不顺手改进相邻代码、注释或格式。
- 不重构本来能正常工作的部分。
- 匹配现有代码风格，即使你更偏好另一种写法。
- 因你的修改而变成死代码的导入和变量，删除掉。
- 发现预先存在的死代码时，提出来但不要删。
- 每一行改动都应该能对应到用户的需求。

## 目标驱动执行

- 定义清晰的成功标准再开始。
- “修复 bug” 转化为“写一个重现 bug 的测试，然后让它通过”。
- “添加验证”转化为“为无效输入写测试，然后让它们通过”。
- “重构 X”转化为“确保重构前后所有测试都能通过”。
- 多步骤任务先给简短计划，每一步带验证方式。

## 验证要求

- 优先运行现有测试。
- 修复 bug 或新增行为时，尽量添加聚焦测试。
- 如果不能运行测试，明确说明原因。
- 不要声称已经验证，除非确实运行过验证。
- 最终回复中说明验证方式。

## 最终回复格式

完成任务后，简洁说明：

- 改了什么。
- 为什么这样改。
- 如何验证。
- 还有什么风险或假设。

回复要直接、实用，不要过度解释。