黄兵的个人博客

Codex 的 agents.txt 具体作用是什么？

agents.txt 是 OpenAI Codex / ChatGPT Code Agent 体系里的一种“行为声明文件”，你可以把它理解为——给 AI 编程代理看的“项目级说明书”，作用有点像给人类开发者看的 README.md，但受众是 AI。

下面我分层说清楚它是什么、解决什么问题、怎么用、和其他文件的区别。

一句话版结论

agents.txt 用来告诉 Codex / Code Agent：
这个项目你该怎么理解、怎么改、什么能动、什么不能动。

一、agents.txt 解决的核心问题

在没有 agents.txt 的情况下，Codex：

• 会猜项目结构

• 可能误改关键代码

• 不知道哪些是：

  • 自动生成的

  • 遗留代码

  • 禁止修改的

• 不清楚你希望它：

  • 偏向重构？

  • 只修 bug？

  • 写测试还是不写？

agents.txt 的作用就是：降低 AI 的“猜测成本”。

二、agents.txt 是给谁看的？

👉 只给 AI / Agent 看，不是给人类看的

• Codex

• ChatGPT Code Agent

• IDE 内嵌 AI（未来会更常用）

它不会参与构建、不会被执行，也不影响运行环境

三、agents.txt 一般放在哪里？

通常在项目根目录：

/
├── agents.txt
├── README.md
├── pyproject.toml
├── src/
└── tests/

有点像：

• robots.txt → 给爬虫看的

• agents.txt → 给 AI agent 看

四、agents.txt 通常写什么内容？

1️⃣ 项目整体说明（非常重要）

This is a Flask-based object storage billing system.
The project focuses on hourly traffic and storage billing.

告诉 AI：

• 项目类型

• 技术栈

• 核心目标

2️⃣ 修改边界（最关键的部分）

DO NOT modify database schemas without explicit instruction.
DO NOT change production billing logic.

这能防止 AI“好心办坏事”。

3️⃣ 目录/模块说明

utils/
  calculate_util.py: hourly billing calculation logic
  database_util.py: MySQL query wrapper, do not refactor

避免 AI：

• 把关键 util 重写

• 随意“现代化”你刻意保留的代码

4️⃣ 编码风格 & 偏好

Prefer explicit variable names.
Avoid clever one-liners.
Follow existing logging style.

比 .editorconfig 更偏语义层。

5️⃣ 测试 / 文档偏好（可选）

When adding features, include unit tests if possible.
Documentation should be in Markdown.

五、agents.txt 和这些文件的区别

👉 agents.txt 是“AI 视角的 CONTRIBUTING.md”

六、agents.txt 会不会强制执行？

❌ 不是强制机制

• 它不是安全沙箱

• 它是 软约束 / 指导语义

但在 Codex / Code Agent 中：

• 权重很高

• 通常会优先遵守

七、一个偏实战的 agents.txt 示例

This project implements object storage traffic monitoring and billing.

Key principles:
- Traffic billing counts download_size only, not upload_size.
- Storage size is derived from upload_size.
- Billing is calculated hourly.

Important constraints:
- Do not change existing database schemas.
- Do not refactor calculate_util.py unless explicitly requested.
- Do not introduce new dependencies without asking.

Coding style:
- Keep logic explicit and readable.
- Avoid over-engineering.

When modifying code:
- Preserve backward compatibility.
- Prefer minimal, localized changes.

八、什么时候“必须”写 agents.txt？

强烈建议写的场景：

• 项目复杂、有历史包袱

• 有“不能动”的核心逻辑（你这个正中）

• 经常让 AI 帮你改代码

• 未来多人 + 多 AI 协作

九、总结一句大白话

agents.txt 就是你对 AI 说的那句：
“你可以帮我，但按我说的方式来，别自作聪明。”

其它相关推荐：

1、Codex stream error: error sending request for url

2、Gemini 设置长期记忆

3、Codex 折腾

4、ChatGPT 中的新建聊天中的分支作用

5、ChatGPT 聊天窗口太长导致加载迟缓的解决方案