# Codex Features and Practical Usage 📝 Stop repeating the same context in every prompt. AGENTS.md is a layered instruction file that teaches Codex your build steps and code conventions for good. 🏷️ Title: Hierarchical Project Instructions (AGENTS.md) 🔗 URL: 📘 Overview AGENTS.md files are persistent instructions Codex reads before starting work. Encode your project norms, build commands, and code standards in Markdown, and Codex automatically discovers and applies them. The defining trait is a layered model where files closer to your current directory take precedence. ⚙️ How It Works Codex builds an instruction chain with strict precedence. ・Global (`~/.codex/`): checks `AGENTS.override.md` first, then `AGENTS.md` ・Project (Git root down to cwd): at each level checks `AGENTS.override.md`, then `AGENTS.md`, then custom fallback names ・Merge: files concatenate from the root downward with blank lines; later files (closer to cwd) override earlier ones It stops adding files once the combined size hits `project_doc_max_bytes` (32 KiB default). Naming conventions: ・`AGENTS.md`: the standard instruction file ・`AGENTS.override.md`: a temporary replacement that takes precedence at its level ・fallback names: configurable via `project_doc_fallback_filenames` (e.g. `TEAM_GUIDE.md`) 🛠️ Practical Usage Split by role for best effect. ・`~/.codex/AGENTS.md` (global): universal personal preferences, e.g. "Always run `npm test` after editing JS," "Prefer `pnpm`" ・repo-root `AGENTS.md`: team norms like linting standards, documentation expectations, and review criteria ・subdirectory `AGENTS.override.md` (e.g. `services/payments/`): override broader rules for a specific domain without deleting parent guidance Verify what loaded by asking Codex to summarize the current instructions, e.g. `codex --ask-for-approval never "Summarize the current instructions."` 💡 Use Cases In a monorepo where only the payments service needs a different test command or review bar, dropping a `services/payments/AGENTS.override.md` switches the rules on only when Codex works under that path. The "Review guidelines" you write here also apply to GitHub's `@/codex review`. ⚠️ Caveats Codex rebuilds the instruction chain on every run, so there is no cache to clear — if guidance looks stale, restart in the target directory. Empty files are skipped and non-existent fallback names are ignored. The `CODEX_HOME` environment variable overrides the default profile location. #OpenAICodex# #AGENTSmd#

One Agents.md/Claude.md rule I find really useful on plan mode: In Plan mode, when the user asks for a revised or new plan after changing the plan, fully rewrite it around the final intended implementation. Do not recap obsolete plan history or include prior revision notes unless the user explicitly asks for that history, because stale process notes can mislead implementation and add redundant work.

If you maintain an AGENTS.md or a CLAUDE.md, this is worth a read. (bookmark it) 288 gold-test evaluated runs across Claude Code and Codex, 17 real tasks from 3 repositories, with context-injection strategy as the only variable. Correctness does not move on either agent. Equivalence testing bounds any effect to at most 10 to 15 percentage points. A failure-mode triage explains why. Agents fail on implementation skill, feature design, pattern selection and exact wiring, rather than on repository knowledge a markdown file could supply. A manipulation probe confirms it, since the real AGENTS.md never converted a near-miss into a pass on either agent. Borderline task difficulty is agent-specific with Spearman rho of 0.75, so single-agent studies draw tasks from different informative bands and reach opposite conclusions. That explains a lot of the contradictory prior evidence. Paper: Track more trending AI papers in our academy:

开发系统最极致高效的Agents.md，没有之一： # AGENTS.md ## Core Principles - Choose the simplest implementation that fully satisfies the current requirements. Avoid unnecessary abstraction, configuration, indirection, or speculative extensibility. - Make the smallest necessary change that fixes the root cause. Do not refactor unrelated modules or change strategy semantics unless explicitly requested. - Grow the system in layers. Start from the smallest working end-to-end version and add new capabilities incrementally. Never replace a working system with unfinished complexity. - Reuse existing project components before creating new ones. Prefer extending proven modules over introducing parallel implementations. - Prefer well-maintained libraries when they reduce overall complexity or improve reliability. Do not reimplement common functionality without a clear benefit. - Keep components modular with clearly defined responsibilities. Avoid unnecessary coupling between strategy logic, execution, accounting, replay, and infrastructure. - Design for long-term maintainability once a feature or strategy has been validated. Do not over-engineer speculative ideas before evidence exists. --- ## Strategy Development - Validate hypotheses with historical replay before introducing forward-only logic whenever historical validation is possible. - Every trading strategy must progress through Replay → Shadow → Canary → Live. Do not skip validation stages. - Base design decisions on measurable evidence rather than intuition. Optimize only after demonstrating that an edge exists. - Treat every strategy as an independent contract. Do not silently alter frozen behavior without explicit authorization. --- ## Existing Systems - Do not break running Shadow or Live systems for unrelated work. - Preserve compatibility only when required by active production or validation workflows. Otherwise, remove obsolete code instead of accumulating compatibility layers. - Reuse existing infrastructure whenever possible, including replay engines, accounting, execution, wallet management, order book handling, logging, monitoring, and daemon frameworks. --- ## Engineering Standards - Prefer deterministic behavior over hidden automation. - Fail loudly when assumptions are violated. Do not silently ignore errors or fall back to unexpected behavior. - Keep configuration minimal. Introduce new configuration only when behavior genuinely needs to vary. - Remove dead code instead of leaving unused paths behind. - Write code that is easy to inspect, replay, test, and reason about. - Keep implementation consistent with existing project architecture unless an architectural change is explicitly requested. --- ## Scope Discipline - Implement only the requested scope. - Do not introduce unrelated optimizations, redesigns, migrations, or feature expansions. - Non-blocking findings outside the requested scope may be noted separately but must not be merged into the current task. - Consider a task complete once its agreed acceptance criteria are satisfied. Treat subsequent improvements as separate work items.

Codex Code Review can now use custom repository rules in AGENTS.md. Start with a check your reviewers keep repeating. Keep it concise and scoped so Codex can catch repository-specific issues even when the relevant context is siloed.

We added @karpathy -inspired coding rules from @jiayuan_jy to AGENTS.md and ran 40 @openclaw PRs through three coding agents. The result: Code quality was basically unchanged, but the agents got there with less work. Fewer tool calls, lower time and cost.

codex tip: teach code review what your team keeps repeating. add a “Code Review Rules” section to AGENTS.md. codex will apply your repo-specific guidance and cite it on pull requests.