Skip to main content
PromptPalPromptPal
Pricing
Sign inGet started free
  1. Home
  2. /
  3. Blog
  4. /
  5. General

Codex System Prompt: What It Is and How to Customize It

The Codex system prompt is built in, but you control the instructions layered on top. Here is where each one goes, with copy-ready AGENTS.md and task prompts.

Author: PromptPal TeamNovember 21, 20268 min read
blog-2
On this page
  1. What the built-in prompt covers, and what it can't know
  2. The three layers you control
  3. A copy-ready AGENTS.md block
  4. A task prompt that works with those rules
  5. A review prompt for the diff Codex hands back
  6. How this compares to Claude Code and ChatGPT system prompts
  7. Mistakes that make Codex ignore your instructions
  8. Keeping your Codex prompts versioned and reusable
  9. A quick test for any Codex instruction
  10. Next step

The Codex system prompt is the built-in instruction set that ships with OpenAI's coding agent. You don't usually edit it. You steer Codex with the layers you control: an AGENTS.md file in your repo, any config you set, and the prompt you type for each task. Most of the quality difference comes from those last two.

The exact wording of the built-in prompt changes between versions, so don't rely on a copy from a blog post, including this one. The Codex CLI is open source, so if you want the current text, read it in the project repo. What matters for daily work is knowing what the built-in prompt already handles so you stop repeating it.

What the built-in prompt covers, and what it can't know

The base prompt tells the model it is a coding agent: how to read files, run commands, edit code, and report back. That is general behavior. It applies to every user and every project.

What it can't know is anything about your project. It doesn't know you use pnpm instead of npm. It doesn't know the legacy/ folder is off limits, that tests must pass before a commit, or that your team writes commit messages in a particular format. Every one of those is a thing you either write down once or correct in every session.

So the useful question isn't 'how do I rewrite the system prompt'. It's 'what does Codex need to know about this repo that it can't infer from the code'.

If you want the general theory of what belongs in a system prompt versus a message, we cover it in System Prompt vs User Prompt: What Goes Where and Why. The short version: standing rules go in the persistent layer, one-off requests go in the task.

The three layers you control

Think of your instructions in three layers, from most permanent to least.

  1. Project instructions (AGENTS.md). Codex reads AGENTS.md files from your repo. This is where standing rules live: commands, conventions, boundaries. It works like a system prompt you own and can commit to version control.

  2. Configuration. Model choice, approval mode, and sandbox settings. These change what Codex is allowed to do, not how it thinks. Check the current Codex docs for the exact options, since they move.

  3. The task prompt. What you type for this specific job. It should state the goal, the scope, and how you'll know it's done.

A common mistake is cramming layer 3 content into layer 1. 'Fix the login bug' doesn't belong in AGENTS.md. And the reverse: typing 'remember to run the linter' into every task prompt means your AGENTS.md is missing a line.

A copy-ready AGENTS.md block

Keep this short. Codex has to read it every session, and a long rulebook gets followed less reliably than a few clear lines. Cut anything the code already makes obvious.

Prompt template
# Project instructions

## What this repo is
[One or two sentences: what the product does and the main stack, e.g. 'A Next.js billing dashboard using TypeScript and Postgres.']

## Commands
- Install: [install command]
- Run tests: [test command]
- Lint and typecheck: [lint command]
- Run a single test: [single test command]

## Before you say a task is done
1. Run the tests and the linter. Report the actual output, not a guess.
2. If a test fails and you didn't change the related code, say so instead of editing the test to pass.
3. List every file you changed and why.

## Boundaries
- Do not edit anything under [protected folder, e.g. legacy/ or migrations/].
- Do not add new dependencies without asking first. Propose the package and the reason.
- Do not change public API signatures in [folder] unless the task says to.

## Conventions
- [Naming or style rule the linter doesn't catch]
- [Commit message format]
- [Where new tests go]

## When you're unsure
Ask one specific question and stop. Don't guess at business rules, pricing logic, or anything involving user data.

The 'before you say a task is done' section does the most work. Without it, coding agents tend to report success after editing code without running anything. Asking for actual command output gives you something to check.

The 'when you're unsure' line matters too. It trades a little speed for far fewer confident wrong guesses in the places where wrong guesses are expensive.

A task prompt that works with those rules

Once AGENTS.md holds the standing rules, your task prompt can stay small. Here is the before and after.

Before:

Fix the bug where users get logged out.

Codex will look around, form a theory, and probably change something plausible. You get a diff you can't easily judge.

After:

Prompt template
Goal: Users are logged out after about [time period] even when they're active. Find the cause and fix it.

Context:
- Session handling lives in [file or folder].
- It started after [change, release, or date, if you know].
- Steps to reproduce: [steps].

Scope: Touch only [folder or files]. If the real cause is somewhere else, stop and tell me before editing.

Done when:
- A new test fails before your fix and passes after it.
- The existing test suite passes.
- You explain the root cause in two or three sentences.

First, tell me your plan in a few lines. Then proceed.

The changes are small but each one does something. The scope line stops a one-line fix from becoming a refactor. The 'done when' list turns a vague request into something checkable. Asking for a plan first gives you a chance to redirect before any files change.

If you want a stricter version for risky changes, add 'Do not edit files until I approve the plan.' That costs one round trip and is worth it on anything touching payments, auth, or migrations.

A review prompt for the diff Codex hands back

Use a second pass to check the work. This is cheap and catches the most common problems.

Prompt template
Review the changes you just made as if someone else wrote them.

1. Does the diff do only what the task asked? List anything extra.
2. Which edge cases are not covered by tests? Name at least [number] specific inputs.
3. Did you change any test to make it pass? If so, justify it.
4. What is the most likely way this change breaks in production?

Be blunt. If the change is weaker than you reported, say so.

The fourth question tends to produce the most useful answer, because it forces a specific failure scenario rather than reassurance.

How this compares to Claude Code and ChatGPT system prompts

People searching for a 'claude system prompt' or 'chatgpt system prompt' are often after one of two things: the hidden built-in prompt, or the place to put their own instructions. The mechanics differ by tool, but the principle holds across all of them.

  • Claude Code uses a CLAUDE.md file for project instructions, the same role AGENTS.md plays for Codex. The advice above carries over almost unchanged: short, specific, with commands and boundaries.

  • ChatGPT has custom instructions and project instructions. These are persistent, but they aren't tied to a repo or to files the agent can run. Good for tone and preferences, weaker for build commands.

  • Claude and ChatGPT in the browser don't let you replace the vendor's prompt at all. You add yours on top.

Published copies of vendor system prompts circulate online. Treat them as curiosities. They go stale, they may be incomplete, and copying a vendor's whole prompt into your own setup usually makes things worse, since you're duplicating instructions the model already has.

If you work across several tools, keep one source of truth for your standing rules and adapt the file name per tool. AGENTS.md, Skills or MCP? Giving AI Agents Context explains when a static file is enough and when you want context delivered at runtime instead.

Mistakes that make Codex ignore your instructions

Writing a rulebook. Forty rules compete with each other. Pick the ten that prevent real damage and delete the rest. If a rule has never been broken, you probably don't need it.

Using vague adjectives. 'Write clean code' means nothing. 'Functions stay under [number] lines and have no more than [number] parameters' can be checked.

Contradicting yourself across layers. AGENTS.md says 'ask before adding dependencies' and the task prompt says 'use whatever library you want'. The agent has to guess which you meant. When you override a rule, say so explicitly: 'For this task only, you may add one dependency.'

Putting secrets in instructions. Don't paste API keys or credentials into AGENTS.md or a task prompt. Instruction files get committed and shared.

Never testing the instructions. Treat AGENTS.md as code. After you change it, run a task you know the answer to and see whether behavior shifted. If nothing changed, the line was either unnecessary or phrased too loosely.

Keeping your Codex prompts versioned and reusable

AGENTS.md lives in the repo, so git already tracks it. The task prompts and review prompts are the part that gets lost: they sit in a terminal history or a scratch file, and the good version you wrote last month is gone.

A workflow that works:

  1. Save the task prompt and the review prompt as templates in your PromptPal library, with the [placeholders] intact.

  2. Name them by job, such as 'Bug fix with plan first' and 'Post-change self review', so teammates can find them.

  3. When you tighten a prompt after a bad run, save it as a new version rather than overwriting. Prompt version control lets you compare what changed when results got better or worse.

  4. Share the set with your team so everyone starts from the same prompts instead of improvising their own.

If you're a developer wiring agents into your own pipelines, the same saved prompts can be delivered at runtime through PromptPal's MCP server rather than pasted by hand. That is useful once more than one person, or more than one agent, depends on the same wording.

A quick test for any Codex instruction

Before adding a line to AGENTS.md, ask three things. Would a new engineer on the team need to be told this? Has the agent actually gotten it wrong before? Can you tell from the output whether it followed the rule?

If the answer to all three is yes, add it. If the agent has never made that mistake, leave it out and add the line the first time it happens. Instructions that respond to real failures stay short and keep working. Instructions written in advance for imagined failures pile up.

Next step

Paste your current AGENTS.md or task prompt into the Refine agent and see which lines it tightens or cuts. Then save the version that works to your library so you can reuse it on the next repo.

Tags:codexsystem promptagents.mdcoding agentsprompt engineering

Read this article as Markdown

Stay Updated

Get the latest blog posts and AI prompt engineering tips delivered to your inbox.

No spam, unsubscribe at any time. We respect your privacy.

On this page

  1. What the built-in prompt covers, and what it can't know
  2. The three layers you control
  3. A copy-ready AGENTS.md block
  4. A task prompt that works with those rules
  5. A review prompt for the diff Codex hands back
  6. How this compares to Claude Code and ChatGPT system prompts
  7. Mistakes that make Codex ignore your instructions
  8. Keeping your Codex prompts versioned and reusable
  9. A quick test for any Codex instruction
  10. Next step

Turn ideas into prompts that work

Describe what you need and PromptPal writes a reusable prompt in your style for ChatGPT, Claude and Gemini.

Try PromptPal free

Related Posts

Continue reading

General · November 21, 2026

Claude Code Prompt Library: 5 Prompts to Save and Reuse

Build a Claude Code prompt library you actually reuse: five copy-ready prompts for planning, bug fixes, refactors and reviews, plus how to store and version them.

General · November 21, 2026

Prompt Engineering Job: What It Is and How to Get One

What a prompt engineering job involves day to day, which skills get you hired, and how to build a portfolio of tested, versioned prompts that proves you can do it.

General · November 20, 2026

ChatGPT API: How to Write Prompts That Work in Code

Using the ChatGPT API? Here's how to structure system and user messages, keep prompts out of your code, and copy-ready prompts for production use.

Ready to get started?

Join thousands of developers and teams using PromptPal to build better AI prompts.

Start for freeContact Sales

Footer

Get better at AI, one email a week

One great prompt, one quick tip, and what’s new in ChatGPT, Claude and Midjourney. Five minutes, every Thursday.

No spam. Unsubscribe in one click.

PromptPalPromptPal

Great prompts for any AI, in seconds. Free to start, no account needed.

Create a prompt
Browser extensionConnect to Claude, ChatGPT, Cursor
Featured on SaaSearch

Product

  • Prompt builder
  • Browser extensionNew
  • Connect to your AI
  • Pricing

Prompt generators

  • ChatGPT
  • Claude
  • Gemini
  • Midjourney
  • Perplexity
  • See all

Use cases

  • Students
  • Writers
  • Solo builders
  • Everyday users
  • Developers
  • AI teams

Resources

  • Guides
  • Blog
  • Prompt Store
  • Docs
  • Compare
  • Help center

Company

  • About
  • Contact
  • Enterprise
  • Press

© 2026 Securestack Technologies Inc.

PrivacyTermsRefund policyChangelog

PromptPal