OpenAI Codex's AGENTS.md: Rules for AI Written by a Real Large Project
A breakdown of the AGENTS.md actually in use in OpenAI's official codex repository — see how a project with millions of lines of code writes team conventions like formatting, testing, commits, module size limits, and API naming into an instruction file that an AI agent can understand and follow, plus a Traditional Chinese adaptation template you can apply directly to your own project.
# AGENTS.md
> 給 AI coding agent（Codex / Claude Code 等）讀的專案規則檔。放在 repo 根目錄（子目錄可放更貼近該層的覆寫版）。原則：寫成「明確、有立場、可機械執行」的條列，而不是抽象原則。
## Project Setup
- Toolchain / runtime: {{TOOLCHAIN}}（例：Node 20 + pnpm / Rust stable / Python 3.12）
- Required tools to install before starting: {{REQUIRED_TOOLS}}（例：`just`, `rg`, linter）
- DO NOT touch: {{DO_NOT_TOUCH}}（例：sandbox / 環境變數開關 / 生成檔；列出 agent 絕不能改的東西）
## Code Style
- Run `{{FORMAT_CMD}}` automatically after every change (e.g. `just fmt`, `npm run format`).
- Lint with `{{LINT_CMD}}`; fix all warnings before finishing.
- API design: prefer explicit enums/named methods over boolean or ambiguous optional params.
- Prefer private modules with explicit public exports; add doc comments to new public APIs.
## Testing
- Run `{{TEST_CMD}}` (NOT the raw test runner) — e.g. `just test`, `npm test`.
- Scope a single package: `{{TEST_PACKAGE_CMD}}`.
- After changes to {{CORE_AREAS}}, run the full suite.
- Test authoring: compare whole objects, not individual fields; don't write tests for static constants or removed logic.
- {{SNAPSHOT_RULE}}（若有快照測試：所有 UI/輸出變更都要附對應快照，並用 review→accept 流程）
## Module Size & Organization
- Target modules under {{SOFT_LOC}} LoC (excluding tests); split before {{HARD_LOC}} LoC.
- Don't grow large orchestration files; when extracting code, move its tests and docs together.
## Change Size Guidance
- General changes: max {{MAX_LINES}} lines per change.
- Complex logic: keep under {{COMPLEX_MAX_LINES}} lines; stage larger work into reviewable pieces.
- Build context incrementally; do not rewrite history.
## API / Naming Conventions（依專案調整或刪除）
- New surface goes in {{API_VERSION}} only; no additions to deprecated versions.
- Naming: `*Params` (requests), `*Response` (responses), `*Notification` (events).
- Serialization: {{SERIALIZATION_RULE}}（例：camelCase via serde rename / snake_case for config）.
## Breaking Changes — check impact on
- Public APIs / CLI params / config loading / session or state resumption.
## Commits & PRs
- {{COMMIT_CONVENTION}}（例：Conventional Commits；一個邏輯變更一個 commit）
- 完成前自我檢查：format ✅ / lint ✅ / test ✅ / 變更行數在上限內 ✅Swap the variables inside the [ ] brackets for your own content, then paste into OpenAI Codex.
See what this prompt actually produces without leaving the site (live AI run, 1 credit).
Don't just copy-paste — download and drop it at ~/.codex/prompts/openai-codex-agents-md-real-world-example.md then invoke it with /openai-codex-agents-md-real-world-example.
mkdir -p ~/.codex/prompts && mv ~/Downloads/openai-codex-agents-md-real-world-example.md ~/.codex/prompts/openai-codex-agents-md-real-world-example.mdNew-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\prompts" | Out-Null; Move-Item "$env:USERPROFILE\Downloads\openai-codex-agents-md-real-world-example.md" "$env:USERPROFILE\.codex\prompts\openai-codex-agents-md-real-world-example.md"## What This Is / What Problem It Solves AGENTS.md is a 'machine-readable README' placed at the root of a code repository, written specifically for AI coding agents (Codex, Claude Code, etc.) to read. The pain point is very concrete: when you ask an AI to modify a project of any real size, it doesn't know which command to run tests with, how to format commit messages, which files are off-limits, how many lines a single file is allowed to grow to, or how APIs should be named — the result is inconsistent code style, stepping on landmines, or PRs so large nobody wants to review them. AGENTS.md is where you write down these 'team conventions' in black and white, in a form an agent can understand and follow. ## Why This Source Is Worth Using What's curated here isn't a tutorial — it's **the actual AGENTS.md that OpenAI's own codex repository uses**, a real, large, multi-crate Rust/TypeScript/Python hybrid project. Its value is that it's 'actually running': every rule you see here is something the OpenAI team learned the hard way, not something imagined in the abstract. It demonstrates what dimensions a mature AGENTS.md should cover. ## Key Highlights from the Original File (Excerpted Observations) - **Formatting and linting**: run `just fmt` automatically after changes, inline `format!` arguments, `match` statements must be exhaustive with no leftover wildcard branch. - **Testing discipline**: use `just test` instead of `cargo test`, compare 'the whole object' rather than individual fields, UI changes must always come with an insta snapshot. - **Hard caps on module size**: target under 500 LoC per module, split once it approaches ~800 LoC; explicitly warns against letting orchestration files like `chatwidget.rs` / `app.rs` balloon in size. - **Change size**: a normal change is capped at 800 lines, complex logic at 500 lines or less; anything larger should be split into reviewable chunks. - **API naming conventions**: new interfaces only go into v2, naming conventions like `*Params` / `*Response` / `*Notification`, serde camelCase, etc. — demonstrating how to write 'team API conventions' into agent rules too. - **Do-not-touch list**: explicitly flags code related to sandbox environment variables as 'never modify this.' ## How to Use It 1. Create an `AGENTS.md` at the root of your repo (subdirectories can hold override versions closer to that layer, which the agent will prefer when relevant). 2. Apply the full_prompt template on the right, replacing placeholders like `{{TOOLCHAIN}}`, `{{TEST_CMD}}`, `{{FORMAT_CMD}}`, and line-count caps with your project's real values. 3. Focus on items that are 'mechanically enforceable' — commands, numeric caps, naming rules — rather than abstract slogans like 'please write clean code.' 4. Explicitly list 'files/settings that must never be touched' — this single item saves you from the most disasters. ## When to Use It Any project where you plan to have an AI agent make repeated changes should have one of these. The bigger the project, the more contributors, and the more conventions it has, the higher the payoff from an AGENTS.md. 📎 Source: the AGENTS.md in the openai/codex repository (by OpenAI, Apache-2.0 License) — this piece is a Traditional Chinese adaptation and summary, rewritten rather than copied verbatim; see the original file at the link above.
[TOOLCHAIN]專案的語言與工具鏈，例：Node 20 + pnpm / Rust stable / Python 3.12
[REQUIRED_TOOLS]開工前必裝的工具清單，例：just、ripgrep、linter
[DO_NOT_TOUCH]agent 絕對不能改的檔案或設定（sandbox 開關、生成檔等）
[FORMAT_CMD]格式化指令，例：just fmt 或 npm run format
[LINT_CMD]lint 指令
[TEST_CMD]跑測試的標準指令（用包好的指令而非裸 test runner）
[TEST_PACKAGE_CMD]只跑單一套件/模組的測試指令
[CORE_AREAS]改動後需要跑全套測試的核心區域
[SNAPSHOT_RULE]快照測試規則（若無可刪此行）
[SOFT_LOC]模組建議行數上限，例：500
[HARD_LOC]模組必須拆分的硬行數，例：800
[MAX_LINES]單次變更建議最大行數，例：800
[COMPLEX_MAX_LINES]複雜邏輯單次變更上限，例：500
[API_VERSION]新 API 應放入的版本，例：v2
[SERIALIZATION_RULE]序列化命名規則，例：camelCase via serde rename
[COMMIT_CONVENTION]commit / PR 慣例，例：Conventional Commits、一變更一 commit
填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。
# AGENTS.md
> 給 AI coding agent（Codex / Claude Code 等）讀的專案規則檔。放在 repo 根目錄（子目錄可放更貼近該層的覆寫版）。原則：寫成「明確、有立場、可機械執行」的條列，而不是抽象原則。
## Project Setup
- Toolchain / runtime: {{TOOLCHAIN}}（例：Node 20 + pnpm / Rust stable / Python 3.12）
- Required tools to install before starting: {{REQUIRED_TOOLS}}（例：`just`, `rg`, linter）
- DO NOT touch: {{DO_NOT_TOUCH}}（例：sandbox / 環境變數開關 / 生成檔；列出 agent 絕不能改的東西）
## Code Style
- Run `{{FORMAT_CMD}}` automatically after every change (e.g. `just fmt`, `npm run format`).
- Lint with `{{LINT_CMD}}`; fix all warnings before finishing.
- API design: prefer explicit enums/named methods over boolean or ambiguous optional params.
- Prefer private modules with explicit public exports; add doc comments to new public APIs.
## Testing
- Run `{{TEST_CMD}}` (NOT the raw test runner) — e.g. `just test`, `npm test`.
- Scope a single package: `{{TEST_PACKAGE_CMD}}`.
- After changes to {{CORE_AREAS}}, run the full suite.
- Test authoring: compare whole objects, not individual fields; don't write tests for static constants or removed logic.
- {{SNAPSHOT_RULE}}（若有快照測試：所有 UI/輸出變更都要附對應快照，並用 review→accept 流程）
## Module Size & Organization
- Target modules under {{SOFT_LOC}} LoC (excluding tests); split before {{HARD_LOC}} LoC.
- Don't grow large orchestration files; when extracting code, move its tests and docs together.
## Change Size Guidance
- General changes: max {{MAX_LINES}} lines per change.
- Complex logic: keep under {{COMPLEX_MAX_LINES}} lines; stage larger work into reviewable pieces.
- Build context incrementally; do not rewrite history.
## API / Naming Conventions（依專案調整或刪除）
- New surface goes in {{API_VERSION}} only; no additions to deprecated versions.
- Naming: `*Params` (requests), `*Response` (responses), `*Notification` (events).
- Serialization: {{SERIALIZATION_RULE}}（例：camelCase via serde rename / snake_case for config）.
## Breaking Changes — check impact on
- Public APIs / CLI params / config loading / session or state resumption.
## Commits & PRs
- {{COMMIT_CONVENTION}}（例：Conventional Commits；一個邏輯變更一個 commit）
- 完成前自我檢查：format ✅ / lint ✅ / test ✅ / 變更行數在上限內 ✅Suno Engineer's Mindset: 4 Steps to a Song That Doesn't Sound Like AI
A studio engineer's breakdown of Suno's fatal weaknesses (fried vocals, high-frequency artifacts), plus a 4-step DAW workflow and a Suno Studio cleanup prompt.
5 Claude Weekly Workflows That Stuck After 6 Months
Proposal generator / meeting processor / content repurposer / Friday review / shutdown reset — out of 40 I tried, only these 5 survived, each saving 30+ minutes per run.
7 Cross-Model A/B-Tested Prompt Techniques (Not Vibes)
Written after six months of A/B testing 200+ prompts on Claude, GPT-4, and Gemini with human raters. Covers persona + constraint stacking, anti-examples, role-reversal QA, cognitive scaffolds, emotional priming, uncertainty CoT, and steelman-first.
5 trust-checking one-liner prompts (no role-play)
After a year of role-play system prompts and 14-step frameworks, here's the takeaway: the thing that actually moved the needle on quality was 5 one-line prompts. No roles, no markdown, no "you are an expert."