Prompting Codex and the AGENTS.md File
Tight task prompts and a well-maintained AGENTS.md are the two cheapest investments that produce the biggest reliability gains in Codex-powered workflows.
Two Levers That Compound
Codex is capable. But capability and reliability are not the same thing. A capable model given a vague task will produce capable-but-wrong outputs — confidently, quickly, and at scale. The two practices in this lesson are the cheapest investments that close the gap between capability and reliability:
- Write tight task prompts with explicit scope and done criteria.
- Maintain an AGENTS.md file that gives Codex persistent project context.
Neither of these requires any engineering work. They require discipline.
Prompt Anatomy
A well-formed Codex task prompt has five components. Not all five are required for every task — a trivial task can be one sentence. But for any task that touches more than one file or involves judgment calls, all five should be present:
Role. Anchor the model's persona before the task. "You are a senior TypeScript engineer working on this codebase." This is not decoration. It sets the baseline for what the model treats as acceptable code quality, what patterns it considers idiomatic, and what it treats as a red flag. The same task prompt with and without a role statement can produce meaningfully different outputs on judgment calls.
Goal. One sentence, one task. If you find yourself writing "and also..." in the goal, split it into two tasks. Codex handles focused tasks reliably; Codex handling multiple interleaved goals is where unexpected behavior emerges. "Add input validation to the createUser endpoint in src/routes/user.ts" is a good goal. "Add validation, refactor the error handling, and update the tests" is three tasks.
Constraints. Explicit boundaries prevent the model from touching adjacent code. "Use Zod schemas. Do not modify the database migration files. Do not change the function signatures on the public API." Constraints are not distrust — they are communication. Without explicit constraints, the model infers them, and inferred constraints are often wrong.
Scope. List the specific files the model is allowed to modify. This is the single most effective way to prevent scope creep. "Only modify src/routes/user.ts and src/schemas/user.ts." If the task requires reading additional files for context, say so: "You may read src/types/ for type definitions but do not modify it."
Done criteria. How will the agent know when the task is complete? Without this, it either stops too early (first plausible implementation, not necessarily correct) or keeps iterating in search of a perfection it cannot define. "Task is complete when the endpoint rejects requests with missing required fields with a 400 status and npm test passes." That is a checkable condition the agent can evaluate.
The Surgical-Iteration Rule
The most important prompt discipline in any agentic coding workflow is ending task prompts with an explicit scope statement:
Fix only these items. Do not change anything else.
Knox's engineering workflow enforces this rule across every Codex and Claude Code session. Every AI prompt ends with "Fix only these items. Do not change anything else." This discipline eliminated an entire class of merge conflicts that arose from agents improving code that other agents or humans were in the middle of modifying. You can read more about the broader workflow at rewiredminds.io.
AGENTS.md: Persistent Project Instructions
AGENTS.md is a Markdown file that Codex reads automatically at the start of every session. It is the persistent project context that you would otherwise repeat in every task prompt.
Think of it as the project's standing orders. Instead of writing "never modify the migration files" in every prompt, you write it once in AGENTS.md. Instead of explaining the test framework in every prompt, you document it in AGENTS.md. The file is read every time; the rule applies every time.
The hierarchy:
Global (~/.codex/AGENTS.md) — your personal cross-project preferences. Your preferred code style, your default test frameworks, naming conventions you apply everywhere. This is the baseline that all projects inherit.
Repo root (<repo>/AGENTS.md) — project-specific rules. How to run the tests. Which files are never modified. What the codebase conventions are. What the current feature branch is working on. This is the file you maintain alongside the project and update as the project evolves.
Subdirectory (<repo>/src/api/AGENTS.md) — service or module-specific overrides. API contracts that must not be broken. Local conventions that differ from the repo root. Specific files that are off-limits within this subsystem.
Narrower files add to and override broader ones on conflict. All applicable files are read for every session — Codex merges them, with the most specific scope taking precedence.
This is directly analogous to Claude Code's CLAUDE.md hierarchy, which Knox's team uses across all infrastructure repos. The pattern is identical: global defaults, repo-specific conventions, directory-level overrides. The naming differs; the concept is the same.
What Goes in AGENTS.md
The sections that pay the highest dividend:
Project overview. Two to three sentences describing what the project does and its primary users. The model will use this to infer appropriate code patterns and error handling conventions.
Conventions. Language and framework version, linting rules, naming patterns, comment style. Anything you would tell a new engineer on day one.
Do-not-touch list. Files or directories that are never modified by Codex. Migration files. Auto-generated code. Files maintained by another system. Being explicit here prevents silent corruption of files the model would otherwise consider fair game.
Test command. Exactly how to run the test suite. Codex uses this to verify its own work during the observe phase. Without a test command, it cannot close the loop on whether its changes work.
Current context. What is the team working on right now? What decisions have recently been made? What is in progress? This is the section that changes most frequently — update it when the project direction shifts.
Keeping AGENTS.md Current
AGENTS.md is only valuable if it is accurate. An outdated AGENTS.md is worse than no AGENTS.md — the model will follow stale rules confidently.
Treat AGENTS.md as a living document, not a setup artifact. When a convention changes, update it. When a new file is added to the do-not-touch list, add it. When the test command changes, fix it.
A useful discipline: when a Codex session produces unexpected behavior that could have been prevented by a clearer AGENTS.md entry, add that entry before starting the next session. This is the same compounding-learning loop that Knox's team uses with lessons.md — every correction becomes a rule that prevents the same mistake in future sessions.