Effective Prompting and AGENTS.md Strategies

Two developers on the same team give Codex the same task. One gets a clean, well-tested implementation in two turns. The other gets a rambling, half-broken result that requires three follow-ups. The difference is not luck or model randomness — it is prompt quality. Codex is only as effective as the instructions you give it, and those instructions come from two sources: your prompts and your AGENTS.md files.

What You’ll Walk Away With

• A prompt structure that consistently produces high-quality Codex output on the first try
• AGENTS.md patterns that provide the right context without burning tokens on irrelevant guidance
• Techniques for verification-driven prompting that makes Codex self-check its work
• Anti-patterns to avoid that waste tokens and produce worse results

The Anatomy of an Effective Prompt

Every high-quality Codex prompt has four components:

1. What — The specific task, stated clearly
2. Where — The files, directories, or modules involved
3. How — The patterns, conventions, or constraints to follow
4. Verify — How Codex should validate its own work

Implement rate limiting for the /api/v2/orders endpoint.        [What]
The route is in src/routes/orders.ts and the middleware          [Where]
directory is src/middleware/.
Follow the pattern used in src/middleware/auth-limiter.ts.       [How]
Add a unit test in tests/middleware/. Run npm test to verify.    [Verify]

Prompt: Verification-driven task

“Add input validation to the user registration endpoint in src/routes/auth.ts. Use Zod schemas matching the patterns in src/schemas/. Validate email format, password strength (min 8 chars, one number, one special char), and username uniqueness. Write tests in tests/routes/auth.test.ts. Run npm test after each change to verify nothing breaks.”

AGENTS.md Hierarchy

Codex reads AGENTS.md files in a specific order and concatenates them. Files closer to your working directory override earlier guidance.

Global AGENTS.md

Create ~/.codex/AGENTS.md for universal preferences:

# Working Agreements

- Always run tests after modifying code files
- Prefer pnpm for dependency management
- Ask before adding new production dependencies
- Use TypeScript strict mode for all new files

Repository Root AGENTS.md

Project-wide conventions:

# Repository Expectations

- Run pnpm lint before opening a pull request
- Follow the error handling pattern in src/lib/errors.ts
- All API routes must have OpenAPI annotations
- Test files live next to source files: foo.ts -> foo.test.ts

Nested AGENTS.md for Specialization

For monorepos, add directory-specific guidance:

services/payments/AGENTS.md

- Use make test-payments instead of npm test
- Never modify payment amounts without explicit user confirmation
- All database queries must use the payments-specific connection pool
- Follow PCI-DSS logging rules: never log card numbers or CVVs

Prompt: Generate an AGENTS.md for your project

“Analyze this repository’s structure, test patterns, linting configuration, and coding conventions. Generate an AGENTS.md file that captures the key instructions a new Codex session should follow. Include: test commands, lint commands, naming conventions, file organization patterns, and any project-specific rules you can infer from the codebase.”

Prompting Anti-Patterns

The Kitchen Sink

Bad: “Refactor the entire auth system, add tests, update docs, fix all lint issues, and optimize performance.”

This prompt tries to do five things at once. The agent will likely do a mediocre job at all of them.

Good: Split into five focused prompts, each in its own thread.

The Placeholder Overload

Bad: “Add [TYPE] validation to [ENDPOINT] using [LIBRARY] following [PATTERN].”

Good: Be specific. “Add Zod validation to the POST /users endpoint following the pattern in src/schemas/order.schema.ts.”

The Implicit Expectation

Bad: “Fix the bug.”

Good: “The login endpoint returns 500 when the email contains a plus sign. The error is in src/routes/auth.ts around the email parsing logic. Add a regression test that covers email addresses with plus signs.”

The Over-Scoped Context

Bad: A 2000-line AGENTS.md that describes every aspect of your entire organization.

Good: A 100-line root AGENTS.md with nested 50-line files for each service. Total context per task: 150 lines.

Advanced Prompting Techniques

Plan-First Prompting

Ask Codex to propose a plan before implementing:

Before making any changes, outline a plan for migrating our Express
middleware to Fastify hooks. List each file that needs changes and
the specific transformation for each. Wait for my approval before
implementing.

Constraint Anchoring

Explicitly state what the agent should NOT do:

Update the user model to support soft deletes. Do NOT modify the
migration files -- I will handle migrations separately. Do NOT
change the API response format. Only modify the model, repository,
and service layers.

Self-Verification Loops

Ask Codex to verify its own work:

After implementing the changes:
1. Run pnpm test and fix any failures
2. Run pnpm lint and fix any warnings
3. Verify the API still returns the correct response shape by
   checking against the OpenAPI spec
4. Report what you changed and the verification results

When This Breaks

• Agent ignores AGENTS.md guidance: Check that Codex loaded the file by asking “Summarize the current instructions.” If the file is too large, it may be truncated (default limit: 32KB). Split into nested files.
• Prompt produces inconsistent results: Add more constraints. Vague prompts produce variable output. Specific prompts with verification steps produce consistent output.
• Context window fills up: Long AGENTS.md files and many MCP servers eat context. Trim AGENTS.md to essentials and disable unused MCP servers.
• Agent over-refactors: Add explicit constraints like “Do NOT refactor unrelated code” or “Only modify the files listed above.”

What’s Next

• Context Patterns — Manage context effectively across long sessions
• Review Strategies — Review agent output efficiently
• Efficiency Hacks — Quick tips that make every prompt more effective